Go Code Audit

Comprehensive code quality analysis against Go best practices. Identifies code smells, anti-patterns, and non-idiomatic patterns with categorized findings.

What It Checks

Idiomatic Go Patterns

Proper use of interfaces (accept interfaces, return structs)
Channel and goroutine patterns
Error wrapping with %w and sentinel errors
Use of context.Context as first parameter
Functional options pattern where appropriate

Naming & Style

Package naming (short, lowercase, no underscores)
Exported name stuttering (user.UserService → user.Service)
Acronym consistency (URL, HTTP, ID)
Variable scope and naming length conventions

Package Structure

internal/ usage for non-public packages
Circular dependency detection
Package cohesion (single responsibility)
cmd/ and pkg/ conventions

Error Handling

Unchecked errors (errcheck patterns)
Bare log.Fatal in library code
Panics in recoverable code paths
Error wrapping without context

Code Smells

Global mutable state
init() function overuse
Empty interfaces where concrete types suffice
Overly complex functions (cyclomatic complexity)
Dead code and unused exports

How to Run

API Integration (Optional)

If GOPHER_GUIDES_API_KEY is set, verify it:

curl -s -H "Authorization: Bearer $GOPHER_GUIDES_API_KEY" \
  https://gopherguides.com/api/gopher-ai/me

If not set, local analysis tools (go vet, staticcheck, golangci-lint) still provide comprehensive analysis. Set the key for enhanced API-powered insights. Get your key at gopherguides.com.

Full Project Audit

Analyze the entire Go project:

# Run static analysis tools
go vet ./...
staticcheck ./...
golangci-lint run --max-issues-per-linter 0 --max-same-issues 0 ./...

Then review the codebase for patterns the tools don't catch:

Read each package's exported API — check for stuttering, interface bloat, and naming
Trace error paths — ensure all errors are wrapped with context
Review concurrency — check goroutine lifecycle management
Check test coverage — identify untested critical paths

Gopher Guides API (Enhanced Analysis)

Note: API calls send source code to gopherguides.com for analysis. Ensure your organization's policy permits external code analysis.

For full API usage examples, see API Usage Reference.

Helper Script

After installation via install.sh, scripts are at .github/skills/scripts/. For a full audit including local tools + API:

bash .github/skills/scripts/audit.sh

Severity Configuration

After installation via install.sh, severity configuration is at .github/skills/config/severity.yaml. Teams can override severity levels per category or per rule. See the Setup Guide for details.

Output Format

Categorize all findings by severity:

🔴 Critical

Issues that will cause bugs, data races, or security vulnerabilities.

🟡 Warning

Non-idiomatic patterns, maintainability concerns, or performance issues.

🟢 Suggestion

Style improvements, naming refinements, or minor optimizations.

Report Template

## Code Audit Report

**Project:** {name}
**Date:** {date}
**Files Analyzed:** {count}

### Summary
- 🔴 Critical: {n}
- 🟡 Warning: {n}
- 🟢 Suggestion: {n}
- Quality Score: {score}/100

### Findings

#### 🔴 Critical

1. **{title}** — `{file}:{line}`
   - Issue: {description}
   - Fix: {recommendation}

#### 🟡 Warning

1. **{title}** — `{file}:{line}`
   - Issue: {description}
   - Fix: {recommendation}

#### 🟢 Suggestion

1. **{title}** — `{file}:{line}`
   - Issue: {description}
   - Fix: {recommendation}

### Recommendations
1. {top priority action items}

References

Existing gopher-ai skill: plugins/go-dev/skills/go-best-practices/
Gopher Guides API: plugins/gopher-guides/skills/gopher-guides/
Effective Go
Go Code Review Comments