AI Agent Instructions Across the Go Corpus#

Summary#

20 of 51 projects (39%) have committed at least one AI agent instruction file. AGENTS.md is the emerging default format, with CLAUDE.md most often used as a one-line @AGENTS.md redirect rather than a standalone document. The most consequential finding is how sharply depth varies: headscale’s 1,051-line instruction file documents specialized sub-agents, integration test patterns, and an entire architectural subsystem, while a third of adopters have files under 40 lines covering only build commands.

Adoption overview#

Adoption rate: 20/51 projects (39%)

Projects with no instruction files (31/51): kubernetes, moby, etcd, traefik, caddy, fyne, minio, consul, terraform, nomad, k3s, argo-cd, tekton-pipeline, go, gin, buffalo, beego, gorm, viper, cobra, fzf, drone, buildkite-agent, restic, syncthing, rclone, tailscale, wireguard-go, pop, pocketbase, nats-server.

Format taxonomy#

AGENTS.md (tool-agnostic)#

Projects: air, crush, delve, fiber, frp, gh, gitea, gogs, grafana, headscale, helm, hugo, prometheus, temporal

Pattern: Originally associated with OpenAI Codex CLI; now adopted as the de facto tool-agnostic name. Content ranges from brief build/test command lists (frp: 39 lines) to exhaustive architectural documentation (headscale: 1,051 lines). Projects that fully commit to AGENTS.md as the single source of truth (air, gh, headscale, helm) tend to be the most carefully written.

CLAUDE.md (Claude Code specific)#

Projects: cockroach, delve, echo, frp, gitea, gogs, grafana, headscale, hugo, prometheus, sqlc

Note on @-include pattern: Five projects (grafana, headscale, hugo, prometheus, gitea) use CLAUDE.md solely as a one-line @AGENTS.md redirect. This pattern lets AGENTS.md remain the single canonical document while still satisfying Claude Code’s default lookup. It is the cleanest multi-tool strategy in the corpus: write once in AGENTS.md, redirect everywhere else. Three projects (delve, frp, gogs) take a cruder approach: AGENTS.md and CLAUDE.md contain byte-for-byte identical content — copy-paste duplication that will drift over time.

.github/copilot-instructions.md#

Projects: dapr, fiber, istio, temporal, vault

Pattern: Four distinct approaches: dapr and temporal wrote standalone full-content files; fiber wrote a 14-line minimal checklist; istio wrote a project-overview document; vault wrote a 35-line index that delegates to nine domain-specific *.instructions.md files under .github/instructions/generic/. The vault delegating architecture is the most sophisticated Copilot setup in the corpus, using frontmatter applyTo patterns so Go-specific rules apply only to **/*.go files and Ember rules apply only to vault/ui/**/*.

Multi-file / delegating setups#

Vault is the most elaborate multi-file setup: the top-level copilot-instructions.md is purely an index pointing to 9 domain files (golang, golang_tests, ember_general, ember_js, ember_hbs, ember_styles, ember_tests, code_comments, testing) totaling 1,126 lines. This addresses a monorepo problem: a full-stack project (Go backend + Ember.js frontend) cannot use one document for both audiences.

Cockroach uses a different multi-level approach: one top-level CLAUDE.md (145 lines) for general guidance, plus four package-level CLAUDE.md files in high-complexity subsystems (pkg/clusterversion/, pkg/sql/, pkg/sql/logictest/, pkg/sql/schemachanger/). The pkg/clusterversion/CLAUDE.md is the most interesting: it indexes runbooks in a runbooks/ subdirectory and explicitly tells future Claude Code sessions to “prefer QUICK versions when available.” This is a multi-generation instruction design — the human who wrote the runbooks imagined the AI agents that would read them.

Crush places an internal/ui/AGENTS.md (200 lines) alongside the root-level AGENTS.md. The UI file documents the Bubble Tea rendering architecture, interface hierarchy, and tool renderer patterns — knowledge that is only relevant when working in that subdirectory.

Grafana has a root AGENTS.md that explicitly tells agents: “Directory-scoped agent files exist for specialized areas — read them when working in those directories,” then lists docs/AGENTS.md and the alerting squad file. This is a coordination pattern: the root file is a dispatch document, not a content document.

Sqlc has five package-level CLAUDE.md files covering database engine internals (dolphin MySQL parser, AST structure, rewrite passes, named queries, end-to-end test setup). Unlike cockroach’s navigational files, sqlc’s subsystem files are largely operational: how to add test cases, how the TiDB parser is forked, how AST nodes are structured.

Content depth#

Deep (100+ lines)#

headscale (1,051 lines): Exceptional outlier. Covers architecture, six subsystem interaction flows, a complete integration testing framework, the tags-as-identity data model, logging patterns, database migration rules, and — uniquely — mandates that two specialized agents (headscale-integration-tester, quality-control-enforcer) must be invoked at the end of any quality task. This file reads as a collaborative knowledge system built up across many sessions.

dapr (323 lines): Gold standard for a CNCF infrastructure project. Comprehensive build/test/lint/format/proto-gen commands, DCO sign-off requirement, CI failure causes, devcontainer setup, PR checklist. Heavy on mechanics, light on architecture.

sqlc (269 lines root + 652 in subsystem files): Uniquely detailed on database environment setup — has a custom sqlc-test-setup binary, proxy configuration for CI environments, and recognizes that Claude Code sessions may be running in constrained network environments. The branch naming convention (claude/ prefix) is the only case in the corpus where a project encodes agent-specific git conventions.

vault (1,126 lines across domain files): Most elaborate multi-file system. The Ember-specific files (ember_hbs, ember_js, ember_tests) together exceed the Go files in volume, reflecting vault’s investment in the UI side.

delve (354 lines): Exceptional architecture documentation for a complex systems project. Mandatory TDD rules with UPPERCASE emphasis (“NEVER write implementation code without a failing test first”). Detailed eBPF backend documentation. The architecture section could stand alone as a developer guide.

crush (183 root + 200 UI + 3 stats): The root file documents the full module architecture with directory tree; the UI file documents rendering pipeline, component patterns, interface hierarchy — knowledge specific to Bubble Tea TUI development.

gh (170 lines): Clean and practical. The Options+Factory pattern is documented concretely with file references. JSON output pattern, httpmock usage, IOStreams in tests. Exemplary density-to-usefulness ratio.

air (153 lines): Best example of a medium-project instruction file. Covers goals, project snapshot, repository layout, build/lint/test, code style, error handling, concurrency, tests, config/CLI discipline, documentation, tooling, scope and safety, and an explicit “For AI Coding Agents” section with Codex-specific guidance.

grafana (156 root + 150 docs + 55 e2e): Root AGENTS.md is notable for its table-format architecture section (Go backend package table, frontend feature table) and explicit security reminders (XSS, SQL injection, command injection). Also contains a “Cursor Cloud specific instructions” section with environment prerequisites and testing gotchas — demonstrating that projects are starting to target multiple AI tool environments within a single file.

prometheus (148 lines): Focused entirely on contribution workflow rather than architecture. PR title format examples from real merged PRs, release-notes block format, performance benchmark requirements (benchstat output in PR body), code style references to specific blog posts. Written from deep maintainer review experience.

cockroach root (145 lines): Notable for listing repo-specific Claude Code skills (/commit-helper, /file-crdb-issue, /review-crdb) and for its Interaction Style section (“Be direct and honest. Correct me when I’m wrong”). The custom formatter (crlfmt not gofmt) is called out prominently.

temporal AGENTS.md (104 lines): The most AI-behavior-forward instruction file in the corpus. Has a dedicated “Tone and Style” section telling the agent to “Adopt a professional, direct, and concise tone,” “Aim for fewer than 3 lines of text output per response whenever practical,” and “Avoid conversational filler, preambles.” This is the only case where the file explicitly regulates the agent’s communication style, not just its code.

Medium (30–100 lines)#

echo (98 lines): Architecture and code style; no build commands beyond Makefile targets. Useful architecture section explaining the radix tree router, middleware chain, and Context interface.

fiber AGENTS.md (81 lines): Notable for the startup script pattern — documents tool installation commands but marks them “reference only – do not run,” with a note to check if vendor/ or module cache exists first. Adds a PR title prefix requirement with emoji categories.

helm (88 lines): Clean overview. Notable for explicitly documenting backward compatibility rules (reference to HIP-0004) and branch strategy (main = v4, dev-v3 = v3).

temporal copilot (82 lines): Code review principles document (not a build guide) covering Go naming, testify correctness pitfalls, concurrency safety, and proto design. Very specific — documents exact anti-patterns seen in code review.

istio copilot (69 lines): Summarized from README and wiki; covers coding conventions, logging, performance (sync.Pool guidance), PR process.

Thin / redirects only (<30 lines)#

gitea AGENTS.md (11 lines): Build/lint/format commands only, plus Co-Authored-By attribution requirement and a note never to force-push/amend. Minimal but actionable.

hugo AGENTS.md (17 lines): Terse even by Hugo standards. “Brevity is good” appears twice. Uses the qt test library (not testify). Mentions hdebug.Printf and check.sh. Highly opinionated, no architecture.

frp AGENTS.md (39 lines): Build and test commands only, plus a note that agent runbooks are in doc/agents/. Functional minimum.

gogs AGENTS.md (33 lines): Direct behavioral instructions. Notable for the opening: “Stop telling me ‘You’re right’, it just shows how incompetent you are.” Probably the most honest agent feedback in the corpus. Encodes a real correction pattern.

fiber copilot (14 lines): Thin three-step checklist: format, lint, test; update docs; lint markdown.

vault copilot index (35 lines): Index only — points to the 9 domain files.

Content category analysis#

What topics appear most often#

Ranked by prevalence across instruction files:

1. Build/test commands (17/20 projects): Near-universal. Almost every project that has an instruction file includes at least make build and make test or equivalent. The outliers are gogs (uses task) and vault (delegates to domain files).

2. Code style / formatting conventions (15/20): Most files document which formatter to use (gofmt, gofumpt, crlfmt, goimports), import grouping, and naming conventions.

3. Testing guidance (15/20): Ranges from “run go test ./...” to delve’s TDD manifesto with Red-Green-Refactor cycle, headscale’s EventuallyWithT rules, and temporal’s testify pitfall list.

4. Architecture overview (12/20): Varies from a three-paragraph summary (helm) to a full ASCII directory tree with component descriptions (dapr, delve, crush, headscale).

5. PR/commit workflow (11/20): PR title format, DCO sign-off (dapr, prometheus, helm), commit message format (delve, prometheus, temporal), release notes requirements (prometheus).

6. AI-specific behavior instructions (9/20): See section below.

7. Error handling patterns (9/20): Most name the preferred approach (fmt.Errorf %w, cockroachdb/errors, stdlib errors, gRPC status errors).

8. Linting (14/20): golangci-lint is nearly universal; notable variations: cockroach uses golangci-lint + crlfmt; dapr pins the exact version; grafana runs ESLint separately.

9. Dependency/environment setup (7/20): headscale (Nix), dapr (devcontainer), sqlc (custom DB setup tool), grafana (Node.js version, yarn corepack).

10. Security notes (4/20): grafana (XSS, SQL injection, command injection), fiber (secure-by-default, attack surfaces), dapr (Apache 2.0 license header), vault (implicit through domain files).

What is rarely or never covered#

• Performance guidance: Only istio and prometheus address it explicitly. Prometheus requires benchstat output for PERF PRs. Most projects say nothing about performance-sensitive paths.

• Debugging guidance: Delve ironically has no guidance on how to use Delve to debug itself. Only temporal mentions using debug statements in a self-verification loop.

• Rollback / incident response: Not present anywhere.

• Changelog format: Only prometheus documents the release-notes block format in detail.

• Dependency upgrade policy: Fiber mentions checking if vendor/ exists; temporal forbids introducing new third-party libraries without explicit request. Most projects are silent.

• Documentation site generation: Hugo’s instruction file says nothing about running the Hugo binary to preview the docs it generates. Grafana’s docs/AGENTS.md covers writing style but not the build process.

AI-specific instructions (beyond “here’s how to build”)#

These instructions go beyond build mechanics to address agent behavior directly:

• air (“For AI Coding Agents” section): Maintain an explicit plan, keep edits as single focused patches, briefly state what you’re about to do before running commands, prefer rg for searches.

• gogs (opening principles): Direct behavioral correction — “Do it right on your first try, fact-check and review after changes.” Unusually confrontational tone. Addresses the pattern where agents defer excessively to user corrections.

• headscale (mandatory specialized agents): Any integration test work MUST use headscale-integration-tester agent. Any QA work MUST use quality-control-enforcer agent. This is the only project that defines an agent orchestration policy within its instruction file.

• temporal AGENTS.md (Tone and Style section): Explicit communication style rules — 3 lines max per response, no preambles, no postambles, professional direct tone. Reads like an RLHF preference document embedded in a code repo.

• temporal copilot (Core Mandates): “Do not take significant actions beyond the clear scope of the request without confirming with the user.” “NEVER assume a library/framework is available or appropriate. Verify its established usage within the project.”

• cockroach (repo-specific skills): Lists /commit-helper, /file-crdb-issue, /review-crdb as available repo-specific Claude Code skills; tells agents to use /commit-helper when creating commits.

• crush (mock providers): Documents how to configure config.UseMockProviders in tests to avoid API calls — a pattern specific to AI coding assistant development.

• sqlc (branch naming): Feature branches from Claude Code sessions should start with claude/ prefix and end with session ID. A naming convention encoding agent provenance.

• cockroach/pkg/clusterversion/ (runbook integration): “IMPORTANT FOR FUTURE CLAUDE SESSIONS: When the user asks you to perform a release task… Read the appropriate runbook… Prefer QUICK versions when available.” Explicitly addresses future AI sessions in second-person.

• grafana (Cursor Cloud section): Prerequisites specific to the Cursor Cloud remote development environment, including Node.js version and testing gotchas. Demonstrates awareness that agents may run in constrained cloud environments.

Correlations#

Project size vs. instruction depth#

Infrastructure and systems projects have the deepest files: headscale (1,051 lines), vault (1,161 total), cockroach (145 root + ~574 subsystem), dapr (323), temporal (186 total). These are all complex multi-component systems where an agent that misunderstands the architecture can cause hard-to-reverse damage.

Framework projects (echo, fiber, gin family) tend toward thinner files. The API surface is the code — there’s less hidden context to document. Helm (88 lines) is the exception, partly because it documents its branching model in detail.

Small tools (frp, gitea, gogs) have minimal files, often just build commands and a few behavioral notes. The exception is gh (170 lines), which is a CLI tool but has a sophisticated testing pattern worth documenting (httpmock.Registry, IOStreams test setup).

Domain vs. format choice#

• CNCF/foundation-governed projects (dapr, istio, temporal, vault): All use .github/copilot-instructions.md, either standalone or as index. This correlates with GitHub Copilot being the enterprise default in organizations, and with these projects having formal contribution processes that Copilot aligns with.

• Independent/community projects (air, headscale, helm, gh, prometheus, crush): Favor AGENTS.md as the primary format. These projects are either tool-agnostic in philosophy or are targeting a broader contributor base.

• Chinese-origin projects (frp, gogs): Both use AGENTS.md + CLAUDE.md mirrors, suggesting adoption of the AGENTS.md standard while also explicitly targeting Claude Code.

• GitHub-adjacent projects (gh, gitea, gogs): All have instruction files. The GitHub CLI and Gitea/Gogs all have AGENTS.md files, even when thin. Projects that deal with git and code review workflows seem more likely to think carefully about agent behavior.

Project maturity / adoption#

The older, more established projects (kubernetes, moby, etcd, traefik, consul, terraform, nomad, k3s, argo-cd, tekton-pipeline, gin, cobra, viper, fzf) have zero instruction files. This is consistent with a timeline: AGENTS.md as a format emerged around 2024; projects that were already well-established had no urgent need to adopt it, and their contributor bases have existing conventions.

The projects with instruction files skew toward either:

1. Projects with active AI-assisted development (crush, sqlc, cockroach — all show signs of regular agent-assisted commits based on how operational the instruction files read)
2. Projects that explicitly target AI contributors as a workflow strategy (headscale, dapr, temporal)

The correlation between “project has instruction file” and “project is in the depends_on list for this analysis” is near-perfect: 17 of the 20 depends_on projects have instruction files. This is not coincidental — the depends_on list was curated to include projects likely to have interesting examples.

Divergent choices#

Content focus: Some files are purely operational (frp, gitea, fiber copilot — just commands). Others are purely behavioral (gogs — just style rules). Most try to do both but with different emphasis. The most useful files (air, gh, dapr) cover the full range: project context, commands, architecture, style, and explicit agent guidance.

Tone toward the agent: Most files are neutral-professional. Three diverge sharply:

• gogs: confrontational correction (“Stop telling me ‘You’re right’, it just shows how incompetent you are”)
• temporal: formal and constraining (“Aim for fewer than 3 lines of text output per response”)
• cockroach: collaborative (“Be direct and honest. Correct me when I’m wrong and explain why.”)

Architecture documentation: Crush and headscale treat their instruction files partly as architecture documents; the instruction file doubles as a developer onboarding guide. Other projects (dapr, delve) separate architecture sections clearly from agent instructions. Most files omit architecture entirely.

Multi-file strategy: Vault, cockroach, sqlc, crush, and grafana all use multiple files. The strategies differ: vault’s is domain-scoped by tech stack; cockroach’s is subsystem-scoped by operational complexity; sqlc’s is domain-scoped by database engine; crush’s is scoped by UI architecture; grafana’s is scoped by contributor squad.

Recommendations for practitioners#

Based on the best examples in this corpus:

1. Use AGENTS.md as the primary file with CLAUDE.md as a one-line @AGENTS.md redirect. This is the cleanest multi-tool strategy. It works today for Claude Code, Codex CLI, Cursor, and any future tool that adopts the AGENTS.md convention.

2. Lead with build/test commands. Every project with a good instruction file opens with the three commands an agent needs to verify work: build, test, lint. Use exact flags, not just make test.

3. Document the architecture context an agent needs to not break things. The highest-value content is context that’s not in the README: which package is performance-critical, what the database migration rules are, what invariants must be preserved. Air’s “Project Snapshot” section is a minimal good example; headscale’s subsystem documentation is the maximum.

4. Add an explicit AI-specific section. Air’s “For AI Coding Agents (Codex CLI)” section is the right instinct — it gives agents guidance about task approach (maintain a plan, keep patches focused) that is irrelevant to human contributors. Separating human contributor guidance from agent guidance prevents the file from becoming too long.

5. Use subdirectory instruction files for complex subsystems. Cockroach, sqlc, and crush all demonstrate this correctly. The subsystem file should focus on what makes that area surprising or dangerous — not repeat the top-level file.

6. Document behavioral corrections explicitly. Gogs is harsh in tone but right in principle: if agents repeatedly make the same mistake (over-validation, unnecessary sycophancy, overwriting external changes), encode the correction in the file. Future sessions benefit.

7. Pin tool versions when they matter. Dapr pins golangci-lint to v2.10.1. This prevents false CI failures from version drift. Any project that CI fails due to linter version mismatch should add this.

Exemplars#

headscale is the most complete instruction file in the corpus. It is the best study for teams running complex infrastructure projects with multiple agents — the mandatory specialized-agent pattern, the EventuallyWithT rules, the database migration rules, and the tags-as-identity architecture section together represent what a mature agent instruction system looks like at the high end. Length (1,051 lines) may be too much for most projects; the key insight is that headscale treats the file as a living knowledge system, not a one-time document.

air is the best single-file example for a medium-tier project. At 153 lines, it covers every category — project snapshot, layout, commands, code style, error handling, concurrency, tests, scope and safety — and closes with an explicit AI agent section. The density-to-usefulness ratio is the highest in the corpus. Projects starting their first instruction file should use air as a template.

vault is the best example for a full-stack monorepo or organization-managed project. The multi-file system with domain-scoped applyTo frontmatter is the correct solution for repos that mix multiple tech stacks. The pattern is underused in the corpus and will likely become more common as monorepos and multi-language projects adopt AI tooling.

Book angle#

The 39% adoption rate is higher than most practitioners would expect — nearly 2-in-5 major Go OSS projects have formalized instructions for AI agents. But the distribution is bimodal: either no file at all, or a file that reflects serious investment in the format. There are almost no casual or minimal adoptions; when projects commit to instruction files, they usually have real things to say.

The most interesting story for the book is not adoption rate but who adopts and why: the projects with instruction files are disproportionately infrastructure projects (headscale, cockroach, dapr, vault, temporal) and developer tools (delve, air, gh, sqlc, crush). These are projects where agent mistakes have high cost — a misunderstood database migration rule or a broken eBPF backend could waste hours. The instruction file is risk management.

The counter-story is equally interesting: Kubernetes, Terraform, Consul, ArgoCD — projects with extremely sophisticated contribution processes, detailed CONTRIBUTING.md files, and large active contributor bases — have zero instruction files. Either these projects haven’t prioritized AI contribution workflows, or their CONTRIBUTING.md already handles the context-setting that AGENTS.md provides for smaller projects.

The headscale case — a single developer building a complex systems project and documenting the specialized agents that must handle specific types of work — is the most forward-looking example. It treats AGENTS.md not just as context for an agent, but as an orchestration layer that routes agent types to problem domains. As agent coordination becomes more common, this pattern will scale.

Three concrete chapter opportunities emerge from this data:

1. “What to put in your AGENTS.md”: the air/gh/dapr tier as templates
2. “Subsystem instruction files”: the cockroach/sqlc/crush multi-level approach
3. “The @-include pattern and tool-agnostic instruction files”: AGENTS.md as the single source of truth with redirects for tool-specific lookups