An Evolving Context Workflow

AGENTS.md — Per-Repo Orientation

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.

~/templates — Replication Guides

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.

~/learnings — Personal Knowledge Base

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.

Why Three Layers, Not One?

A monolithic SOUL.md grows into an unwieldy blob — expensive to load and hard to maintain. Splitting by scope gives you:

The Relationship

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.

The Core Loop

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.

The Instruction in AGENTS.md

Explicitly tell the agent to maintain the files:

# AGENTS.md
**Remember to update this AGENTS.md
whenever structure, conventions,
or build system changes.**

Why This Works

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.

Scoping AGENTS.md

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.

Applies to Any Project Size

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.

Why a Changelog Matters Here

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.

Structure That Works

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.

Git Hooks: Automate the Reminder

A post-commit hook catches the moment when the changelog is most likely to be forgotten — right after you commit.

Ask the Agent to Write It

You don't have to write changelog entries manually. The agent can read the diff and write the right entries:

"update the changelog for my last commit"

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.

The Feedback Loop

Commit → hook reminds you → agent reads diff → changelog updated → AGENTS.md updated → next session starts with full context. The discipline becomes frictionless.

AGENTS.md on a Public Repo

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.

The Review Habit

Before 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."

Separate Public and Private Context

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:

# AGENTS.md
For internal deployment details, see
AGENTS.private.md (not committed).

template.md Is Usually Safe

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.

Beyond SOUL.md

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.

The Consolidation Habit

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.

Private by Default

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.

Load on Demand

Instead of stuffing everything into one file that's always in context, you point the agent to the right guide when the moment comes:

"Read ~/learnings/local-multi-service-
setup.md — I need to add a 5th service
to this setup without port conflicts"

Context stays lean. You load exactly what's relevant to the task at hand.

The Nimble Triad

Three layers, each with a clear scope. No monolith. Load what you need, when you need it.

Minimal Starting Kit

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.

The Graph Overlay Idea

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 Full Stack of Files

The Meta-Instruction

The most important line in any AGENTS.md — the one that keeps the whole system self-sustaining:

**Remember to update this AGENTS.md
whenever site structure, conventions,
or build system changes.**

One sentence. The agent reads it. The agent follows it. The context stays alive.