template.md
up-to-date and an AGENTS.md
to update it as you go."
Navigate with arrow keys or → button
Tells any agent (or new team member) everything they need to know to work in this repo without breaking things. Structure, conventions, build commands, gotchas.
It's the answer to: "What do I need to know before touching anything here?"
AGENTS.md should be skimmable in 60 seconds. If it grows beyond a page or two, split by directory — each subdirectory can have its own AGENTS.md that a scoped agent inherits.
Captures the how and why behind every non-obvious decision so you (or an agent) can recreate the same architecture in a new project.
Think of it as a living ADR (Architecture Decision Record) — updated whenever a pattern solidifies or a gotcha is discovered.
AGENTS.md is for orientation — "here's the current state of the repo."
template.md is for replication — "here's how to build this again from scratch."
Both evolve. Neither is a spec written once and forgotten.
Every time something significant changes — a new pattern solidifies, a gotcha is discovered, a decision is made — update both files. The agent on the next session picks up exactly where you left off.
Explicitly tell the agent to maintain the files:
LLM agents have no persistent memory between sessions. AGENTS.md is that memory — externalized, version-controlled, and always current.
Without it, every session starts from zero. You re-explain architecture, conventions, gotchas. You get inconsistency. The agent makes decisions that contradict earlier ones.
With it, you start at full context every time.
For a monorepo, each major layer can have its own:
Agent tools that support context inheritance will load the appropriate file for the directory they're working in.
A solo weekend side project benefits just as much as a team repo. The cost is low — a few lines updated per session. The payoff compounds every time you come back after a week away.
A changelog isn't just for users — it's context for future agents. "What changed and why" is exactly what an agent needs to understand why the codebase looks the way it does.
A well-maintained changelog is a compressed history of architectural decisions. It makes AGENTS.md shorter by offloading the "why things changed" narrative.
Keep the changelog machine-readable so build scripts can embed it, and human-readable so it's useful at a glance. One source of truth.
A post-commit hook catches the moment when the changelog is most likely to be forgotten — right after you commit.
You don't have to write changelog entries manually. The agent can read the diff and write the right entries:
The agent diffs HEAD~1..HEAD, maps changes to node IDs or components, infers added/changed/removed, and writes meaningful notes based on the actual diff content.
Commit → hook reminds you → agent reads diff → changelog updated → AGENTS.md updated → next session starts with full context. The discipline becomes frictionless.
AGENTS.md is committed to the repo. On a public project, it's visible to everyone. That's mostly fine — it helps contributors — but a few things should never go in.
$STRIPE_SECRET_KEYBefore committing an AGENTS.md update to a public repo, scan it the same way you'd scan any commit: would I be comfortable if anyone on the internet read this?
Ask the agent: "Review this AGENTS.md for anything that shouldn't be public."
If a project spans public and private concerns, split the context:
The private file holds internal URLs, credentials guidance, and org-specific conventions. Add it to .gitignore and document its existence in the public AGENTS.md:
Template files describe architecture patterns and design decisions — most of this is shareable and actually useful as public documentation. Still: no keys, no internal hostnames.
A good template.md with no sensitive data is a feature of a public repo — it's documentation that helps contributors understand the project deeply.
For any new project, create these two files immediately — even before the first commit. They cost 10 minutes to seed and save hours over the project lifetime.
AGENTS.md makes the structure of a project explicit — like a dependency graph. When someone new joins, they read the graph. The delta (Δ) between what they already know and what the file says is exactly what needs to transfer.
Agents work the same way. The AGENTS.md is the overlay. The context gap closes immediately.
The most important line in any AGENTS.md — the one that keeps the whole system self-sustaining:
One sentence. The agent reads it. The agent follows it. The context stays alive.