I Stopped Re-Explaining My Codebase to AI Agents. Here Is What I Built Instead.

I Stopped Re-Explaining My Codebase to AI Agents. Here Is What I Built Instead.

I got tired of typing the exact same project summary every single time I opened a new chat with an AI agent.

Or worse: watching an agent proudly undo a complex architectural decision from yesterday because it had zero memory of why we made that choice in the first place.

AI models are completely stateless between sessions. Every new prompt or model switch drops them right back at square one.

I kept asking myself: why am I fighting this?

Why not just treat the repository itself as the agent's long-term memory?

Instead of pasting context over and over, I turned my codebase into a self-documenting, living knowledge base that forces any AI agent to read where things stand—and update the docs before it finishes its turn.

Now, whether I switch models, open a fresh session, or let a completely new agent loose on the repo, it instantly picks up right where we left off.

Here is how I set it up and how it actually works.

---

The Setup: An Entry Point and a Site Map

The architecture relies on two core pieces inside the repo.

1. Root AGENTS.md

This is the single entry point. Most modern agent tools automatically discover and read AGENTS.md when launched, so it loads for free without me pasting a single line.

It contains:

• A one-paragraph overview of what the project actually is.
• The cardinal project rule (for my setup: all content lives in one data file; agents should prefer editing data over code).
• A concise document map linking to deeper docs.
• A 30-second orientation covering routes, data flow, key commands, and path aliases.
• Golden rules for what to do and what to avoid.
• The Documentation Sync Loop protocol.

Here is a quick look at how the document map and golden rules look inside AGENTS.md:

Document Map

Topic	Document	Purpose
Overview	agent-sitemap/01-project-overview.md	Tech stack, scripts, core goals
Architecture	agent-sitemap/02-architecture.md	Folders, routing, data flow, subsystems
Data Model	agent-sitemap/03-data-management.md	Single-data-file schema & edit rules
Conventions	agent-sitemap/04-conventions.md	Code style, patterns, naming
Workflows	agent-sitemap/05-workflows.md	Dev, build, deployment, caching
Playbook	agent-sitemap/06-agent-playbook.md	Step-by-step recipes & guardrails
Backlog	agent-sitemap/BACKLOG.md	Deferred ideas and raw feature thoughts

Golden Rules

• ALL user-facing content lives in data/content.json. Edit data, not React components.
• Never hardcode strings directly inside UI components.
• Run typechecks and linting before declaring a task complete.
• The agent-sitemap/ Directory To prevent huge context bloat, I split detailed knowledge into modular, numbered Markdown files inside an agent-sitemap/ folder:

README.md – Index, map of all docs, and a quick-facts cheat sheet.

01-project-overview.md – High-level purpose, stack, and npm scripts.

02-architecture.md – Folder structures, routing, data flow, and subsystems.

03-data-management.md – Data model specifics and rules for modifying state.

04-conventions.md – Code style and project patterns.

05-workflows.md – Dev, build, deployment, caching, and SEO protocols.

06-agent-playbook.md – Step-by-step task recipes and guardrails.

BACKLOG.md – Idea dump where agents log deferred work or future improvements.

An agent reads AGENTS.md first, identifies which specific file in agent-sitemap/ it needs for the prompt at hand, and loads only that context.

The Heart of the System: The Documentation Sync Loop
Having documentation is useless if it goes stale. To prevent that, AGENTS.md enforces a strict 4-step protocol that the agent must execute on every single prompt:

The Documentation Sync Loop (Mandatory Protocol)

Run these 4 steps on EVERY prompt:

1. DETECT: Does this prompt introduce new or changed knowledge?

   • New/changed rules, conventions, or user preferences.
   • Design decisions (e.g., "we group items into cards here").
   • Discovered patterns, gotchas, or hardcoded values.
   • Intent behind code changes that future agents must know.

2. ACT: Perform the requested task (edit code, refactor, or update data).

3. RECORD: In the SAME turn, write that knowledge into the correct doc.

   • Rule → 04-conventions.md
   • Data rule → 03-data-management.md
   • Architecture / design logic → 02-architecture.md
   • Workflow → 05-workflows.md
   • Repeatable procedure → 06-agent-playbook.md
   • Deferred idea → BACKLOG.md
   • Always capture the WHY behind decisions, not just the what.

4. CONFIRM: End your final response by listing which docs were updated.

Guardrails:

• Record ONLY durable, project-level knowledge (no transient debugging or secrets).
• When a rule changes, EDIT the stale line—never append duplicate or conflicting rules.
• Keep the document map updated if files are added or removed. What This Looks Like in Practice I was working on a dashboard component and told the agent:

"For this section, let's group items into interactive cards instead of a standard list view."

Here is what happened next:

ACT: The agent refactored the UI list into card components.

RECORD: In the very same turn, it opened agent-sitemap/02-architecture.md and appended the decision along with the reasoning behind it.

CONFIRM: It reported back that the UI was updated and logged the change in 02-architecture.md.

Here is the actual diff snippet added to 02-architecture.md:

Markdown

Dashboard Item Presentation

• Decision: Display dashboard entries using interactive grid cards rather than a unified list view.
• Rationale: Interactive cards provide clearer visual boundaries for actions per item and scale better on mobile viewports.
• Note for future agents: Do not refactor this back into a list without explicit user approval. Three sessions later—on a completely different AI model—I asked for a layout update on that page.

The new model read 02-architecture.md, saw the note, kept the card layout intact, and built on top of it seamlessly. No re-explaining required.

The Real Problems This Solves
Context Loss on Session Switches: Your repo holds the context. Switching models or starting a new chat stops feeling like onboarding a fresh intern every hour.

Repeated Mistakes: When an agent makes a mistake or learns a project preference, it writes down the rule. "Never make the same wrong call twice."

Converging to Your Preferences: As decisions accumulate in agent-sitemap/, the agent's style slowly converges with how you like to write code.

Zero Onboarding Friction: A new agent (or even a human developer) opens the repo and becomes productive immediately.

No More Stale Docs: Documentation usually rots because updating it is a separate chore. Making doc updates a per-prompt rule keeps them aligned with the actual code.

Best Practices That Make It Work
One canonical entry point: Keep AGENTS.md at the root and link everything else from it.

Modular, small docs: Avoid massive single-file dumps. Small files reduce context window usage.

Record the WHY: Knowing why a decision was made prevents future agents from "fixing" intended behavior.

Edit, don't just append: Stale guidance leads to conflicting instructions. Edit old lines when rules change.

Strict routing table: Tell the agent precisely where each type of decision belongs so files don't become messy.

Guardrails against noise: Explicitly forbid logging transient bugs, conversation history, or sensitive credentials.

Prefer data over hardcoding: Keeping content in structured data files makes agent edits far lower-risk.

Challenges (And How to Handle Them)
This isn't magic, and it requires a few practical guardrails:

Agent Skipping the Loop: Sometimes an agent forgets to update docs. Adding the CONFIRM step forces it to account for documentation explicitly in its final output.

Context Bloat: If your knowledge base grows too large, modularize. Let the agent read AGENTS.md and pull in only the relevant agent-sitemap/ file for the current task.

Trusting Agent Edits: This doesn't remove the need to review code. A quick git diff lets you review what the agent wrote to your docs before committing.

Secrets and Credentials: Put explicit instructions in AGENTS.md prohibiting the logging of keys, passwords, or personal data.

What Changed for Me Day-to-Day
I spend significantly less time writing long, detailed prompts.

My prompts went from three-paragraph setup essays to simple one-liners:

"Add a filter option for active items."

The agent checks AGENTS.md, loads the data management rules, writes the code according to our project conventions, records the new filter state pattern in the architecture doc, and confirms what was updated.

It doesn't completely eliminate hallucinations or the need for code review, but it kills the most frustrating part of working with AI agents: amnesia.

Try dropping an AGENTS.md file with a basic sync loop into your next side project.

That's Umang, signing off!