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. Public-safe. 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. Never committed. 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:
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.
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 (committed to the repo, often public), ~/learnings stays on your machine. Internal URLs, org-specific workflows, personal tooling quirks — all fine here. No sanitization needed.
This is your private knowledge layer. AGENTS.md is the public one.
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.