go-conventions

/go-conventions — generate per-project Go conventions

Scans the current Go module and produces .claude/go-conventions.md — a lightweight, project-specific convention reference. rules/go.md reads this file first on every session, so conventions load cheaply without re-scanning.

When to run

• First time in a Go repo — before any substantial code work.
• --refresh — when conventions have evolved or a new area has been added. Merges new patterns into the existing file; preserves hand-edits.
• Prompted by a gap — if you hit a pattern the file doesn't cover while coding, append the rule inline (don't re-run the full scan).

Procedure

1. Confirm context

Verify you're in a Go repo: check for go.mod. If absent, stop and say so.

2. Scan the repo

Read these artifacts in priority order:

a. Module identity

• go.mod — module path, Go version, key direct dependencies (web framework, DB driver, logging, IDs, config)

b. Existing config (if any)

• .golangci.yml / .golangci.toml — enabled linters and their settings
• Makefile — build, test, lint, run targets
• .cursor/rules/*.mdc or .github/copilot-instructions.md — any pre-existing convention docs

c. Project layout (just list, don't read all files yet)

• Top-level dirs: cmd/, internal/, pkg/, api/, app/, etc.

d. Representative code — read 2-3 files from each category:

• Entry point: cmd/*.go or main.go
• Domain package: a service.go + repository.go + model.go from the largest domain
• HTTP/transport: a handler or controller file
• Error handling: look for custom error types
• Logging: find where logs are initialized and called

3. Derive conventions

From what you read, identify the established patterns for each section below. Only document what you actually observed — don't invent from general knowledge. If a section has no established pattern, omit it (leave a brief # TODO: note).

Sections to cover:

1. Project layout — the actual top-level structure and what lives where
2. Package / module structure — how domain packages are organized (which files, naming pattern for constructors, interfaces vs structs)
3. Naming — types, functions, constants, files, packages
4. Dependency injection — constructor pattern (Builder? functional options? plain params?)
5. Model/DTO separation — where domain entities live vs API types; how they're mapped
6. Error handling — custom error types, wrapping, sentinel errors, propagation
7. Logging — library, how to acquire a logger, log levels used
8. Data access — DB driver, query patterns, pagination, soft delete, collection naming
9. HTTP layer — router framework, handler signature, request binding, error response
10. Events / async — if an event bus exists: how events are defined, published, subscribed
11. Context & auth — how user/auth context flows through the system
12. Validation — library, where validation happens, custom validators
13. Import order — observed ordering convention
14. Key libraries — for each direct dep, one-line usage note (e.g. "uuid.New() for IDs")