claude-mit-go-template
AGENTS.md0 starsChanged 45 days agoMITView on GitHub
Scaffolding for new Go module projects: a pinned toolchain, the merge gates wired to CI, and the agent rules already in place. Fork or copy it to start a project. Toolchain: The Go version is pinned via the go and toolchain directives in go.mod (mirrored in .go-version). With GOTOOLCHAIN=auto (the default) every contributor automatically downloads the pinned toolchain on first go invocation. The full-parity dev tools are golangci-lint (lint + format), gotestsum (test runner), govulncheck (CVE scan), go-licenses (license check),…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository4 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- gatesSkill
- new-packageSkill
- whySkill
The file
We split this AGENTS.md into the rules it gives an agent
9 rules. About 0 are common, 8 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 51
Maintain the Build: Never leave the codebase in a state where build, lint, or tests fail.
- Distinctive: line 62
If multiple interpretations exist, present them - don't pick silently.
- Distinctive: line 63
If a simpler approach exists, propose it.
- Distinctive: line 69
No features beyond what was asked.
- Distinctive: line 71
If you write 200 lines and it could be 50, rewrite it.
- Distinctive: line 77
Don't "improve" adjacent code, comments, or formatting.
- Very specific: line 79
Remove imports/variables/functions that YOUR changes made unused.
- Distinctive: line 94
Keep the example code minimal.
- Distinctive: line 107
Read these when they apply.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Scaffolding for new Go module projects: a pinned toolchain, the merge gates wired to CI, and the agent rules already in place. Fork or copy it to start a project.
<!-- agentcfg:start --><!-- language/go/tooling.md · v1.0.1 -->Build and test commands
Toolchain: The Go version is pinned via the go and toolchain directives in go.mod (mirrored in .go-version). With GOTOOLCHAIN=auto (the default) every contributor automatically downloads the pinned toolchain on first go invocation. The full-parity dev tools are golangci-lint (lint + format), gotestsum (test runner), govulncheck (CVE scan), go-licenses (license check), and air (live reload).
Commands live in the Makefile, which is the single source of truth — do not
copy the underlying go invocations into docs or CI, call the target.
make # list every target
make ci # every merge gate, in order — run this before every commit
make build # build all packages
make fmt # format in place
make fmt-check # gate 1
make vet # gate 2, first half
make lint # gate 2 — golangci-lint
make test-race # gate 3 — race detector plus coverage
make vuln # gate 4 — govulncheck
make licenses # gate 4 — go-licenses
make cover # coverage summary
make watch # dev loop, live reloadInstall the auxiliary tools once per machine:
make tools # golangci-lint, gotestsum, govulncheck, go-licenses, airmake tools-lint, tools-test, tools-vuln and tools-licenses install one at
a time; that is how CI does it, so each gate pulls only the binary it uses.
Architecture & Module Rules
Layout: A single Go module rooted at the repo. The module path is declared in go.mod; dependency versions are centralized in that one file. Code follows the standard Go layout:
cmd/<binary>/main.go— one directory per executable (package main).internal/<pkg>/— private packages, importable only within this module.pkg/<pkg>/— public packages intended for external import (omit if there are none).
Packages: One package per directory; the directory name matches the package clause. A new package is just a new directory with a package declaration — there is no per-package manifest. Cross-package use is a plain import "<module-path>/internal/<pkg>", with the module path from go.mod. New dependencies are added with go get and land in go.mod/go.sum.
Go version: The minimum language version is the go directive in go.mod (the analog of an MSRV). Do not lower it incidentally. There are no editions, no LTO/codegen profiles, and gofmt is non-configurable by design.
<!-- core/behavior.md · v1.0.1 -->Behavioral guidelines
Maintain the Build: Never leave the codebase in a state where build, lint, or tests fail. Run the relevant commands in Build and test commands to verify your work before concluding a task.
Tradeoff: Bias toward caution over speed. For trivial tasks, use judgment.
1. Think Before Coding
Don't assume. Don't hide confusion. Surface tradeoffs.
- State your assumptions explicitly. If uncertain, stop and ask.
- If multiple interpretations exist, present them - don't pick silently.
- If a simpler approach exists, propose it. Push back when warranted.
2. Simplicity First
Minimum code that solves the problem. Nothing speculative.
- No features beyond what was asked. No abstractions for single-use code.
- No "flexibility" or error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.
3. Surgical Changes
Touch only what you must. Clean up only your own mess.
- Don't "improve" adjacent code, comments, or formatting.
- Match existing style exactly.
- Remove imports/variables/functions that YOUR changes made unused. Don't remove pre-existing dead code unless asked.
4. Goal-Driven Execution
Define success criteria. Loop until verified.
- Transform tasks into verifiable goals (e.g., "Add validation" → "Write tests for invalid inputs, then make them pass").
- For multi-step tasks, state a brief plan and verify each step independently.
<!-- concerns/template/rules.md · v1.0.1 -->Template repository
This repository is a GitHub template: new projects start as a copy of it, and every copy inherits everything here.
- Keep the example code minimal. It demonstrates the conventions and keeps the gates green on a fresh copy; it holds no real business logic.
- Where the template ships placeholder packages, they exist because the
gates fail on an empty module and the
Dockerfileneeds a binary to build. Remove a placeholder only once a real package covers its role, as a change of its own, and point theDockerfileat the real binary in that change. - A project created from this template removes
templatefromconcernsin its.agentprofile.yml.
<!-- agentcfg:index · v1.0.1 -->Extended rules
Read these when they apply; they are not loaded by default.
By activity:
- Any change that ends in a PR: Git flow and Releases
- Creating branches: Branch naming
- Reviewing PRs: Code review and Go code review
- Committing code: Commit message guidelines
- Deciding what to build next / branching strategy: Execution order
- Opening PRs: PR instructions
- Creating new files: Directories and file naming
- Checking your work: Merge gates
- Adding or modifying a package: Adding a package
- Testing/Verifying: Testing instructions
<!-- agentcfg:end -->Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

