agentleFS
ninoverseninoverse/claude-mit-go-template/AGENTS.md

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.

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
  1. Distinctive:

    Maintain the Build: Never leave the codebase in a state where build, lint, or tests fail.

    line 51
  2. Distinctive:

    If multiple interpretations exist, present them - don't pick silently.

    line 62
  3. Distinctive:

    If a simpler approach exists, propose it.

    line 63
  4. Distinctive:

    No features beyond what was asked.

    line 69
  5. Distinctive:

    If you write 200 lines and it could be 50, rewrite it.

    line 71
  6. Distinctive:

    Don't "improve" adjacent code, comments, or formatting.

    line 77
  7. Very specific:

    Remove imports/variables/functions that YOUR changes made unused.

    line 79
  8. Distinctive:

    Keep the example code minimal.

    line 94
  9. Distinctive:

    Read these when they apply.

    line 107

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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 reload

Install the auxiliary tools once per machine:

make tools      # golangci-lint, gotestsum, govulncheck, go-licenses, air

make 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 Dockerfile needs a binary to build. Remove a placeholder only once a real package covers its role, as a change of its own, and point the Dockerfile at the real binary in that change.
  • A project created from this template removes template from concerns in 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 -->

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.