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")

4. Write the file

Write to .claude/go-conventions.md in the repo root (create .claude/ if needed).

With --refresh: read the existing file first, merge new patterns in, keep existing content that is still valid. Never overwrite hand-edits — look for # NOTE: or # OVERRIDE: markers and preserve them.

File header:

# Go conventions — {module-name}

Derived from codebase scan on {date}. Maintained by `/go-conventions --refresh`.
Global baseline: `${CLAUDE_PLUGIN_ROOT}/references/go/app-erp-conventions.md`.

> **Stack:** Go {version} · {key libs}

Then one section per category found. Each section:

• States the rule plainly (imperative)
• Shows a short code example where the rule isn't obvious
• Cites the example file/pattern it was derived from (e.g. // see pkg/sales/service.go)

Keep each section tight — 5-15 lines max. This file is loaded every session; brevity matters more than completeness.

5. Report

Tell the user:

• Path of the written file
• Number of sections covered
• Any areas where you couldn't find an established pattern (and what to do)
• How to view/edit it (it's plain markdown — open in any editor)
• Suggest adding @.claude/go-conventions.md to the project's CLAUDE.md for automatic inclusion (optional; rules/go.md reads it on demand without this)

Do not commit the file unless the user asks.

Notes

• This skill writes to the target project repo, not to the addit-harness repo.
• The file it generates is a supplement to ${CLAUDE_PLUGIN_ROOT}/references/go/app-erp-conventions.md, not a replacement. Put only the delta — what differs from or extends the global baseline.
• If the project is a perfect match for the baseline (same stack, same patterns), say so and write a minimal file noting the match rather than duplicating all baseline content.