AGENTS.md
per repo, replication guides in ~/templates,
and hard-won knowledge in ~/learnings.
Update them as you go."
Navigate with arrow keys or → button
Lives in the repo root. Tells any agent (or new team member) everything they need to know: structure, conventions, build commands, gotchas.
The answer to: "What do I need to know before touching anything here?"
Committed to git. Reviewed before every public change. Skimmable in 60 seconds.
Starts as a template.md in the repo while you're building — capturing the how and why behind architecture decisions. Once patterns solidify, fold it out to ~/templates so it's reusable across projects.
One file per project type. Evolves from in-repo draft to personal library.
Distilled guides from hard-won sessions. That afternoon you spent getting four services running locally with no port conflicts? Consolidate the essential steps into a guide.
Private by default. Access-controlled. Load on demand when the topic comes up.
A monolithic SOUL.md grows into an unwieldy blob — expensive to load and hard to maintain. Splitting by scope gives you:
AGENTS.md — "here's the current state of this repo."
~/templates — "here's how to build this kind of thing from scratch."
~/learnings — "here's what I figured out the hard way."
All three evolve. None is 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:
Agent sessions do not reliably carry every piece of project context forward. AGENTS.md provides durable orientation that is externalized, version-controlled, and reviewable.
Without it, a later session may need to rediscover architecture, conventions, and gotchas. That raises the chance of inconsistent decisions.
With it, each session starts from a tested orientation rather than a blank slate.
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 is visible to everyone. That can help contributors, but every update needs the same review as source code.
$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:
A private companion can hold non-public operational details and organization-specific conventions. Keep credentials out of documentation entirely. Add the file to .gitignore, restrict access, review backup and sync behavior, and document only its existence publicly:
Template files describe architecture patterns and design decisions. Much of that can be useful public documentation, but the file still needs a privacy and security review.
A reviewed template with no sensitive data is a feature of a public repo because it helps contributors understand the project deeply.
Some people use a monolithic SOUL.md to capture personal preferences and knowledge. The problem: it grows into an unwieldy blob that's expensive to load and hard to maintain.
~/learnings gives you fine-grained control — one focused markdown guide per topic, loaded on demand.
After a productive session — maybe you spent an hour getting four services running locally with no port conflicts, writing ./dev-server.sh scripts and tweaking configs — distill the essential steps into a guide.
Strip the false starts and dead ends. Keep only what worked and why. Future you (or your agent) loads just this file and skips straight to the solution.
Unlike AGENTS.md, ~/learnings is private by default, but local does not automatically mean secret. Files can be synced, backed up, read by tools, attached to prompts, captured in screenshots, or committed accidentally.
Keep sensitive values out, control access, and review a guide before sharing it with any agent or person.
Instead of stuffing everything into one file that's always in context, you point the agent to the right guide when the moment comes:
Context stays lean. You load exactly what's relevant to the task at hand.
Three layers, each with a clear scope. No monolith. Load what you need, when you need it.
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.