AGENTS.md vs Project Brain: Static Instructions and Live Project State
AGENTS.md and a Project Brain solve different problems. AGENTS.md stores stable, version-controlled instructions. A Project Brain carries shared decisions, active work, code impact, proof, and handoffs across sessions and coding clients.
Keep AGENTS.md for durable repository rules. Add a Project Brain when the agent also needs fresh, shared, source-backed project state before it edits.
AGENTS.md is good at stable instructions
AGENTS.md gives coding agents repository-specific rules they can read before work starts: commands to run, architectural boundaries, naming conventions, and instructions for files below a directory. It is transparent, version-controlled, easy to review, and often enough for a small repository with one primary workflow.
Its strength is also its boundary. The file changes only when someone edits it. It should not be expected to know which task is active, what another agent just decided, which code symbols a change may affect, or whether the evidence supporting an old instruction has gone stale.
A Project Brain carries the changing project state
A Project Brain sits outside any one prompt or instruction file. It combines source-backed context, reviewed decisions, active work, code structure, verification evidence, and handoffs so an authorized agent can ask what changed and what matters now.
The right division of labor is simple: keep stable, deterministic instructions in AGENTS.md; keep changing, source-sensitive project intelligence in a shared layer. One tells the agent how to work in the repository. The other tells it what the repository currently knows and what is in motion.
The practical division of labor
AGENTS.md remains the clearest place for stable commands, scoped rules, and repository conventions that should be reviewed in git.
Use the Project Brain for reviewed decisions, active work, impact, proof, and handoffs that change more often than a policy file should.
Sources, freshness, review status, and local verification keep dynamic context from becoming an untraceable second set of instructions.
AGENTS.md and Project Brain, criterion by criterion
| Criterion | AGENTS.md | Project Brain |
|---|---|---|
| Primary job | Tell an agent how to work in this repository | Tell an agent what changed, why, what it impacts, and what to verify now |
| Freshness | As current as the last committed edit | Retrieved with source, timestamp, review state, and index freshness signals |
| Active work | Not represented unless someone manually rewrites the file | Start Work Briefs, What Changed, phase state, and handoffs |
| Code impact | Can state known architectural rules, but does not compute structural impact | Code graph context and impact plans, verified against current local files and tests |
| Best fit | Stable conventions, commands, and scoped instructions | Multi-session and multi-client continuity on changing repositories |
How Snipara combines both
Snipara is the Project Brain for AI coding agents. Its shared Project Intelligence layer gives Claude Code, Cursor, Codex, and other MCP clients the project's reviewed decisions, active work, code impact, verification evidence, and handoffs before they edit.
Snipara does not overwrite an existing AGENTS.md. Setup keeps generated templates separate for deliberate review, while Hosted MCP serves changing project intelligence. Static instructions remain visible in git; dynamic state remains source-backed, freshness-aware, and project-scoped.
Limitations
- A Project Brain still depends on source quality, review discipline, and fresh indexes.
- AGENTS.md does not become obsolete; removing stable rules from git can make agent behavior less deterministic.
- Dynamic context can surface conflicts and recommendations, but it does not autonomously approve a change.
- Uncommitted edits remain outside a hosted graph until local inspection or a new index includes them.
- Neither approach replaces tests, code review, CI, or security review.
FAQ
Does a Project Brain replace AGENTS.md?
No. AGENTS.md remains the right place for stable, version-controlled instructions. A Project Brain complements it with changing project state that a static file should not try to maintain manually.
When is AGENTS.md alone enough?
For a small repository, one main developer or agent, and conventions that rarely change, a clear AGENTS.md plus normal git history may be enough. Add a shared layer when sessions, tools, people, or in-flight decisions need continuity.
What belongs in AGENTS.md?
Put stable commands, coding standards, architectural constraints, directory-specific rules, and verification requirements there. Avoid turning it into a manually maintained activity log.
What belongs in the Project Brain?
Reviewed decisions, active work, source-backed context, code impact, verification evidence, outcomes, and handoffs — especially information that should be shared across sessions and coding clients.
Can both disagree?
Yes, which is why authority and freshness matter. A stable repository rule may outrank a weak inferred memory, while a reviewed recent decision may show that an old instruction needs a deliberate file update. The conflict should be surfaced, not silently merged.