Anchor — the production-grade AGENTS.md template for AI coding agents.
_{Keep your agents grounded. 77 sections of battle-tested rules distilled from 100+ real-world projects, academic research, and production failures.}

Quick Start · What's Inside · File Structure · Philosophy · Research · Usage Guide · Platforms

---

🚀 Quick Start

# 1. Clone the template
git clone https://github.com/peva3/anchor.git

# 2. Copy AGENTS.md into your project
cp anchor/AGENTS.md ./your-project/AGENTS.md

# 3. Copy the skills library — every section's full rule text lives here.
#    The entry-point links to these files, so without them the doc dangles.
cp anchor/routing.json ./your-project/routing.json

cp -r anchor/skills ./your-project/skills

# 4. Copy supporting agent config files
cp anchor/CLAUDE.md ./your-project/
cp -r anchor/.cursor/rules/ ./your-project/.cursor/
cp anchor/.github/copilot-instructions.md ./your-project/.github/

# 5. Optional — bootstrap an entire new project from scratch
cp anchor/STARTUP.md ./your-new-project/STARTUP.md
# Follow the STARTUP.md phases — it's a step-by-step guide for AI agents

After copying, delete any sections that don't apply to your project. The template is designed to be trimmed — each project should keep only relevant sections, targeting ≤2,000 lines and ≤5,000 tokens (see Section 51.3).

---

📦 What's Inside

77 production-grade sections organized into 9 capability domains:

Code Quality & Safety

Section	Content
1-9	Core principles, commit protocol, shell execution rules, code style, project structure, TODO.md standard, Docker, testing, linting
10-14	Error handling, configuration, API design, security, logging
27	Comprehensive code quality standards — Python idioms, anti-patterns, security constraints, performance patterns, docstring quality, error handling patterns, 19-point checklist

Git, CI/CD & Release Engineering

Section	Content
15	Git workflow — human-sounding commit messages with WHY-focused pattern
33-36	PR size standards (800-line gate), AI anti-pattern detection, PR description template with HUMAN/AGENT disclosure, explicit NEVER list
37-40	Pre-commit hooks, CI/CD pipeline standards (ci/release/deploy), semantic versioning & Keep a Changelog, code coverage enforcement (80% floor)

Production Operations

Section	Content
29-32	Operational patterns (circuit breaker, dead letter queue, middleware stack, semantic cache), health endpoint specification, production security (prompt injection detection, audit logging, key encryption), Docker & Kubernetes
41-44	Observability (structured JSON logging, OpenTelemetry, Prometheus, SLOs), Infrastructure as Code (Terraform), database backup & recovery, secrets management (tiered strategy)

Testing Excellence

Section	Content
45-49	Flaky test management (quarantine mechanism), mutation testing (mutmut + arid nodes), performance benchmarks, contract testing (Pact), chaos engineering (Netflix principles)

AI Agent Guidance

Section	Content
21-26	Agent instruction guidance (from AgentBench/CAMEL), multi-agent cooperation patterns, verification gates, common failure modes, gotchas, getting help
28	Default tech stack playbook — FastAPI, Next.js, Gin, databases, decision tree

Intentional Minimalism

Section	Content
50	Decision ladder (YAGNI→stdlib→native→existing dep→one line→minimum code), structured tradeoff comments, safety carve-outs, output discipline, over-engineering review vocabulary, honesty boundaries, tests-are-not-bloat policy, self-referential governance

Instruction Architecture

Section	Content
51	Trigger-based lazy loading, self-maintaining meta-instructions, context budget awareness, model capability awareness, instruction provenance tracking

Enforcement, Safety & Specialized Testing

Section	Content
52-55	Rule enforcement architecture (advisory → deterministic), project-type patterns for non-web work, MCP guardrails, prompt-injection defenses
56-58	Agent memory and state management (compaction, handoff artifacts), tool-call permissions, supply-chain security and SBOM
59-62	Incident response and runbooks, property-based testing, snapshot/golden-file testing, retries with backoff and idempotency

Workflow & Design

Section	Content
63-66	UI quality and anti-slop guardrails, skill routing and checkpoints, time-boxed delivery, presentation decks
67-68	Requirements elicitation (grilling a design tree to an empty frontier), spec and ticket decomposition into vertical slices
69-70	Bug diagnosis loop (red-capable loop first, then hypotheses), two-axis code review (Standards and Spec, independent)
71-73	Codebase design (deep modules, seams), domain modeling with GLOSSARY.md and ADRs, retrospectives that end in one change
74-75	Design systems and visual craft (surface modes, tokens, refused defaults, PRODUCT/DESIGN docs), security audit loop (coverage ledger, adversarial validation, tri-state verdicts)
76-77	Security reconnaissance and attack classes (architecture map, target-type packs, high-yield classes), finding validation and reporting (fresh reviewer, prior-state handling, findings as data)

---

🎯 Why This Exists

Problem: AI coding agents receive instructions from scattered, inconsistent sources. Most AGENTS.md files are 80-line checklists written in 10 minutes. They miss critical patterns around testing, security, CI/CD, multi-agent coordination, observability, and production operations.

Result: Agents make the same mistakes repeatedly — skipping tests, writing unreviewable PRs, ignoring security, creating untracked technical debt.

Solution: This template was built by systematically analyzing 100+ real-world AGENTS.md files, 14 TODO.md files, 22 research papers (AgentBench, CAMEL, MetaGPT), and production codebases. Every section addresses a specific, observed failure mode.

Guarantee: No section exists "for completeness." Every rule eliminates a real failure mode observed in the wild. The file is self-governing — Section 50.8 requires agents editing AGENTS.md to follow every rule within it.

Comparison

	Typical AGENTS.md	This Template
Sections	5-15	77 (entry-point + skills)
Testing depth	"Write tests"	Flaky management, mutation testing, contract testing, chaos engineering, coverage enforcement
Security	"No secrets in code"	Prompt injection detection, audit logging, key encryption, IP whitelisting, 6-category NEVER list
Production	Basic Docker	Circuit breaker, DLQ, middleware stack, health endpoints, structured logging, OpenTelemetry, SLOs
Multi-agent	Not covered	Sequential/hierarchical/collaborative patterns, role templates, termination criteria
Code quality	Ruff/mypy mention	19-point checklist, anti-pattern catalog, bloat detection, AI-specific laziness/uncertainty signals
Git workflow	"Descriptive commits"	WHY-focused format, human-sounding messages, conventional commits, PR templates, size gates
Self-governance	None	AGENTS.md governs its own maintenance — self-referential rules prevent staleness

---

📁 File Structure

anchor/
├── AGENTS.md                  # ⭐ The main template — high-level entry point, 77 sections (full text in skills/), copy this into your project
├── routing.json               # 🧭 Task type → skills to load (deterministic map, Section 64)
├── skills/                    # 📂 Full rule text — 77 skill files (NN-name.md), lazy-loaded by task
├── STARTUP.md                 # 🚀 AI agent bootstrap guide — builds a project from scratch in 4 phases
├── README.md                  # 📖 This file
├── .gitignore                 # 🔒 Ignore generated artifacts — tests/ itself is committed
│
├── CLAUDE.md                  # 🤖 Anthropic Claude agent config (references AGENTS.md)
├── CLAUDE.desktop.md          # 💻 Anthropic Claude desktop app config
│
├── .github/
│   └── copilot-instructions.md  # 🔵 GitHub Copilot instructions
│
├── .cursor/                   # 🟣 Cursor IDE agent rules
│   └── rules/
│       └── project-rules.mdc
│
├── .windsurf/                 # 🟠 Windsurf IDE agent config
│   └── config.md
│
├── .continue/                 # 🟢 Continue.dev agent config
│   └── config.md
│
├── .claude/                   # ⚙️ Claude config (JSON)
│   └── config.json
│
├── docs/                      # 📚 Supporting documentation
│   └── SKILL_MAP.md           # 🗺️ Visual overview of the routing map and skill set
│   └── AGENT_INSTRUCTIONS.md  # Universal fallback agent instructions
│
├── research/                  # 🔬 Academic research backing all sections
│   ├── index.md               # Research catalog
│   ├── papers/                # AgentBench, CAMEL, MetaGPT, Voyager, HuggingGPT
│   └── whitepapers/           # Agentic AI best practices

---

🔬 Research Foundation

Every section is backed by peer-reviewed research or production experience:

Source	Type	Applied To
AgentBench (arXiv:2308.03688)	ICLR 2024 Paper	Failure modes (IF/IA/TLE/CLE), instruction following evaluation
CAMEL (arXiv:2303.17760)	NeurIPS 2023 Paper	Multi-agent cooperation patterns, role assignment, termination criteria
MetaGPT (arXiv:2308.00352)	ICLR 2024 Paper	Sequential handoff patterns, verification gates, SOPs
PEP 8 / Google Style Guide	Standards	Code quality, docstring format, type annotations
Google Testing Blog	Industry	Flaky test management, mutation testing, test isolation
Netflix Chaos Engineering	Industry	Chaos experiment design, steady-state hypothesis, blast radius
Keep a Changelog / SemVer	Community Standards	Versioning, changelog format, release automation
Microsoft C4W Checklist	Industry	CI/CD, coverage thresholds, observability, security scanning
Production Codebase Analysis	Empirical	Circuit breaker, DLQ, middleware stack, health endpoints, audit logging, prompt injection detection

Full research catalog: research/index.md

---

🛠 How to Use

For an existing project:

# Copy the core template
cp anchor/AGENTS.md ./my-project/AGENTS.md

# Copy the skills library (full rule text lives here)
cp anchor/routing.json ./my-project/routing.json

cp -r anchor/skills ./my-project/skills

# Trim to fit — keep only relevant skills and inline them if needed
# Target: ≤2,000 lines for project-specific use (Section 51.3)

For a new project:

# Copy STARTUP.md and follow its 4-phase bootstrap
cp anchor/STARTUP.md ./my-new-project/
# Phase 1: Directory structure
# Phase 2: All agent config files
# Phase 3: .gitignore, .env.example, README.md, TODO.md, DEEPDIVE.md
# Phase 4: git init and commit

Customization checklist:

• Delete inapplicable sections (keep only what matches your tech stack)
• Update tech stack defaults (Section 28) to match your choices
• Set your own branch protection rules (Section 38.6)
• Configure your own CI/CD templates (Section 38)
• Add project-specific gotchas to Section 25
• Fill in DEEPDIVE.md with your architecture narrative (Section 5)

---

🤖 Supported AI Agent Platforms

The template ships with config files for 8+ AI coding agent platforms. All reference AGENTS.md as the single source of truth:

Platform	Config File	Format
Claude Code (Anthropic)	CLAUDE.md	Markdown
Claude Desktop	CLAUDE.desktop.md	Markdown
GitHub Copilot	.github/copilot-instructions.md	Markdown
Cursor	.cursor/rules/project-rules.mdc	MDC
Windsurf	.windsurf/config.md	Markdown
Continue.dev	.continue/config.md	Markdown
OpenCode	AGENTS.md (primary)	Markdown
Any agent	docs/AGENT_INSTRUCTIONS.md	Markdown (universal fallback)

---

🧪 Quality Validation

The template is validated structurally: the entry-point links to all 77 skill files, and the skills hold the full rule text. Two local scripts enforce this:

• Section structure (scripts/check_structure.py) — All 77 sections present, sequentially numbered; each has a skill file, and every index entry resolves
• Heading integrity — No duplicate ### N.M subsection numbers across files
• Routing integrity — Every task type references existing skills, stays within the active-skill budget, owns unique triggers, and reaches every section (no dead guidance)
• Core drift — Every rule kept inline in AGENTS.md also exists in its skill file
• Benchmark alignment — tests/routing-benchmark.json covers every task type and its expectations match routing.json
• Link validity (scripts/check_links.py) — No broken skills/ links or missing files
• Size & density — Entry-point stays lean (417 lines, ~6,500 tokens) so constrained-context models can follow it

Status: check_structure.py passes — 77 sections, 21 task types, every link resolves.

---

📊 Stats

Metric	Value
Sections	77
Entry-point	~417 lines / ~6,500 tokens (always loaded, measured)
Full rule text	77 skill files in skills/ (lazy-loaded by task)
Python code blocks	77
Research sources	22 (12 papers, 10 projects)
Agent platforms supported	8+
DOCKER/K8s templates	4
CI/CD workflow templates	3
Security patterns	9
Testing patterns	12
Anti-patterns documented	24

---

🤝 Contributing

This template follows its own rules. Before contributing:

1. Read Section 50.8 — AGENTS.md governs itself. Agents editing it must follow all rules herein.
2. Read Section 51.2 — Propose additions when you encounter a failure mode not yet covered.
3. Verify the structure — All 77 sections must stay linked from the entry-point with their skill file present. Where the local tooling is present, run python3 scripts/check_structure.py; it checks the Section Index has 77 rows and each link resolves to a file in skills/. Without it, verify those two facts manually.
4. Follow Section 33 — PRs must stay under 800 lines.
5. Follow Section 15 — Commit messages must be human-sounding, WHY-focused.
6. Follow Section 35 — Use the PR template, including the Review Assistance Notes section (review aids only — never authorship attribution, per Sections 2 and 36.5).

What to contribute:

• Rules that eliminate a specific, observed failure mode
• Research backing for existing or new rules
• Cross-references between related sections
• Test examples demonstrating correct behavior

What NOT to contribute:

• Rules without a demonstrated failure mode they prevent
• "Nice to have" sections that duplicate existing coverage
• Tool-version-specific trivia (pin those in config files, not AGENTS.md)
• General advice already covered by PEP 8 or standard style guides

---

📜 License

MIT — use it, modify it, ship it. Attribution appreciated.

---

_{Anchor — keep your agents grounded. 77 sections. 0 filler. Built from 100+ real-world AGENTS.md files, 22 research papers, and production codebases.}