I have been trying to keep repository context useful for AI coding agents without turning it into a large prompt file or depending on a specific vendor index.
The pattern I ended up with is deliberately boring: Markdown plus text search.
AI assistance disclosure: I used an AI assistant to help draft this post, then reviewed and edited it before publishing.
When a coding agent starts working in a repository, it needs at least two kinds of context:
A single AGENTS.md
, CLAUDE.md
, or project rules file is useful as an entry point, but it does not scale well if we keep adding every architecture note, domain concept, setup detail, and workflow rule to it.
At some point it becomes a context dump.
The first layer is close to Andrej Karpathy's llm-wiki idea: every meaningful directory gets an index.md
.
That file should be short. It describes the files and subdirectories nearby, links to related docs, and tells an agent what to read before changing that part of the code.
This helps the agent navigate top-down instead of blindly searching the whole repository.
Example:
src/payments/
index.md
PaymentService.ts
RetryPolicy.ts
tests/
index.md
The root agent instruction file can then stay small:
Before editing code, read the nearest index.md files and follow their links.
After changing behavior, update the affected docs and indexes.
Directory navigation is not enough for concepts that span the tree.
For example, tenant isolation
, billing retries
, auth bootstrap
, or audit logging
might involve service code, tests, migrations, config, documentation, and deployment scripts.
Those concepts do not fit neatly into one folder.
For that, I use explicit tags:
@tag:billing-retries
@tag:tenant-isolation
@tag:audit-logging
The same token appears in both code comments and docs.
Example in code:
// @tag:billing-retries
export class RetryPolicy {
// ...
}
Example in docs:
---
tags: "@tag:billing-retries @tag:payments"
---
Now plain search works:
grep -rn "@tag:billing-retries" .
That gives the agent, or a human, all code and documentation connected to the same concept.
Tags need names and meanings, otherwise they drift.
I keep a simple registry such as:
- `@tag:billing-retries` - retry behavior for failed payment operations.
- `@tag:tenant-isolation` - boundaries that prevent cross-tenant data access.
This makes the tag set reviewable and prevents slightly different names for the same idea.
IDE and agent indexes are useful, but they mostly understand code structure: symbols, files, references, imports, definitions.
They are weaker at human concepts.
A domain concept can cut across files that do not reference each other directly. A visible tag is a cheap human-maintained signal that says: these things belong together.
I wrote the full convention here:
https://github.com/mpashka/llm-wiki-tags
The short version:
AGENTS.md
small;index.md
files for directory navigation;@tag:<slug>
tokens for cross-cutting concepts;docs/tags.md
;It is not a framework and there is nothing to run. It is just a repo convention that works with Codex, Cursor, Claude Code, or plain grep.
The obvious risk is stale documentation.
The only way I have found to reduce that is to make documentation updates part of the same change as code updates. If a task changes behavior, the agent should update the nearby index.md
, the relevant page, and any tags affected by the change.
The other risk is tag noise. I would not tag every function. Tags are useful for stable concepts that cut across the directory tree.
I am still experimenting with where the line should be between useful tags and clutter.
I would be interested in how other people structure persistent context for AI coding agents:
AGENTS.md
/ CLAUDE.md
, or in separate docs?@tag:...
feel useful or noisy?