147 lines
5.4 KiB
Markdown
147 lines
5.4 KiB
Markdown
---
|
|
description: Set up or optimize the current repository for agent-first development (AGENTS.md, docs structure, progressive disclosure)
|
|
---
|
|
|
|
Set up or optimize the current repository for agent-first development. Based on principles from OpenAI's harness engineering and HumanLayer's CLAUDE.md guide.
|
|
|
|
Additional user context and constraints:
|
|
$ARGUMENTS
|
|
|
|
Before changing anything:
|
|
1. Inspect the repository state first.
|
|
2. Compare the repo against the checklist below.
|
|
3. Prefer minimal, high-leverage, versioned changes.
|
|
4. Preserve useful project-specific guidance instead of replacing it blindly.
|
|
|
|
## When to Use
|
|
- Setting up a new repo for agent-driven development
|
|
- Optimizing an existing repo's AGENTS.md / CLAUDE.md
|
|
- Restructuring docs for agent legibility
|
|
|
|
## Core Principles
|
|
|
|
### 1. AGENTS.md = Table of Contents, Not Encyclopedia
|
|
- **Max ~100 lines.** Short, stable entry point.
|
|
- Only universally applicable instructions (applies to EVERY task).
|
|
- Points to deeper sources of truth — doesn't contain them.
|
|
- Domain-specific rules go in sub-files (`docs/`, skills, or scoped AGENTS.md in subdirs).
|
|
|
|
### 2. Progressive Disclosure
|
|
- Agent starts with a small map and is taught where to look next.
|
|
- Use nested AGENTS.md files in subdirectories for scoped context.
|
|
- Skills for domain-specific workflows (loaded on demand, not always).
|
|
- Don't frontload — let the agent discover context as needed.
|
|
|
|
### 3. Repository = System of Record
|
|
- If it's not in the repo, it doesn't exist to the agent.
|
|
- Push decisions, architecture, plans, conventions INTO the repo as versioned artifacts.
|
|
- No tribal knowledge in Slack, Google Docs, or people's heads.
|
|
- Docs are code — they get reviewed, updated, and maintained.
|
|
|
|
### 4. Agent Legibility First
|
|
- Optimize for agent comprehension, not just human readability.
|
|
- Favor "boring" tech — composable, stable APIs, well-represented in training data.
|
|
- Make the app inspectable: logs, metrics, test output should be agent-parseable.
|
|
- Structured formats (JSON, markdown with clear headers) > prose walls.
|
|
|
|
### 5. Enforce, Don't Instruct
|
|
- Invariants via CI/linters > instructions in AGENTS.md.
|
|
- Type checks, tests, formatting rules catch mistakes mechanically.
|
|
- Agent can run verification itself (`make check`, `npm test`, etc.).
|
|
- Instructions the agent can't verify will eventually be ignored.
|
|
|
|
### 6. Less Instructions = Better Compliance
|
|
- LLMs reliably follow ~150-200 instructions max (frontier thinking models).
|
|
- Agent harnesses already consume ~50 instructions in system prompt.
|
|
- Every instruction in AGENTS.md competes for attention budget.
|
|
- When everything is "important," nothing is.
|
|
|
|
## AGENTS.md Template
|
|
|
|
```markdown
|
|
# AGENTS.md
|
|
|
|
## Project
|
|
<1-2 sentences: what this project is and does>
|
|
|
|
## Stack
|
|
<bullet list of key tech: language, framework, DB, infra>
|
|
|
|
## Structure
|
|
<brief map of key directories and what they contain>
|
|
|
|
## Development
|
|
<how to build, run, test — the essential commands>
|
|
|
|
## Docs
|
|
Detailed documentation lives in `docs/`:
|
|
- `docs/ARCHITECTURE.md` — system design, package layering, domain map
|
|
- `docs/CONVENTIONS.md` — code style, patterns, naming
|
|
- `docs/PLANS.md` — active execution plans and progress
|
|
- `docs/DECISIONS.md` — architecture decision records (ADRs)
|
|
|
|
## Verification
|
|
<how to verify changes: test commands, type checks, linters>
|
|
|
|
## Rules
|
|
<only universal, always-applicable rules — keep to <10 items>
|
|
```
|
|
|
|
## docs/ Structure
|
|
|
|
```
|
|
docs/
|
|
├── ARCHITECTURE.md # System design, domain map, package layering
|
|
├── CONVENTIONS.md # Code style, patterns, naming conventions
|
|
├── DECISIONS.md # Architecture Decision Records (ADRs)
|
|
├── PLANS.md # Active plans, completed plans, tech debt
|
|
└── <domain>/ # Domain-specific deep docs as needed
|
|
```
|
|
|
|
## AGENTS.md ↔ CLAUDE.md Symlink
|
|
|
|
Always ensure both files exist so the repo works with any agent harness (Claude Code, OpenCode, Codex, etc.).
|
|
|
|
**Rules:**
|
|
- `AGENTS.md` is the source of truth (canonical file).
|
|
- `CLAUDE.md` is a symlink to `AGENTS.md`.
|
|
- If only `CLAUDE.md` exists, rename it to `AGENTS.md` and create the symlink.
|
|
- If both exist as separate files, merge into `AGENTS.md` and replace `CLAUDE.md` with symlink.
|
|
- Add `CLAUDE.md` symlink to git (git tracks symlinks fine).
|
|
|
|
**Commands:**
|
|
```bash
|
|
# If AGENTS.md exists but no CLAUDE.md
|
|
ln -s AGENTS.md CLAUDE.md
|
|
|
|
# If only CLAUDE.md exists
|
|
mv CLAUDE.md AGENTS.md
|
|
ln -s AGENTS.md CLAUDE.md
|
|
|
|
# Verify
|
|
ls -la CLAUDE.md # should show -> AGENTS.md
|
|
```
|
|
|
|
## Checklist
|
|
|
|
When initializing or optimizing a repo:
|
|
|
|
- [ ] AGENTS.md exists and is <100 lines
|
|
- [ ] CLAUDE.md is symlinked to AGENTS.md (or vice versa)
|
|
- [ ] AGENTS.md contains: project summary, stack, structure map, dev commands, verification
|
|
- [ ] Domain-specific instructions are NOT in root AGENTS.md
|
|
- [ ] `docs/` directory exists with at minimum ARCHITECTURE.md
|
|
- [ ] Verification commands are documented and runnable by agent
|
|
- [ ] CI/linters enforce key invariants (not just documented)
|
|
- [ ] No critical knowledge lives only outside the repo
|
|
|
|
## Anti-Patterns
|
|
- ❌ Stuffing every possible command into AGENTS.md
|
|
- ❌ Adding "hotfix" instructions for one-off behavior issues
|
|
- ❌ Instructions that aren't verifiable or enforceable
|
|
- ❌ Monolithic instruction files that rot over time
|
|
- ❌ Architecture decisions living in chat/docs outside repo
|
|
|
|
## Sources
|
|
- OpenAI: https://openai.com/index/harness-engineering/
|
|
- HumanLayer: https://www.humanlayer.dev/blog/writing-a-good-claude-md
|