DEV Community

Pavel Moukhataev
Pavel Moukhataev

Posted on

A low-tech repo context pattern for AI coding agents

#documentation #ai #programming

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.

The problem

When a coding agent starts working in a repository, it needs at least two kinds of context:

  1. where things are in the codebase;
  2. which files belong to the same concept, even when they live in different directories.

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 directory tree layer

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
Enter fullscreen mode Exit fullscreen mode

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.
Enter fullscreen mode Exit fullscreen mode

The cross-cutting layer

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
Enter fullscreen mode Exit fullscreen mode

The same token appears in both code comments and docs.

Example in code:

// @tag:billing-retries
export class RetryPolicy {
  // ...
}
Enter fullscreen mode Exit fullscreen mode

Example in docs:

---
tags: "@tag:billing-retries @tag:payments"
---
Enter fullscreen mode Exit fullscreen mode

Now plain search works:

grep -rn "@tag:billing-retries" .
Enter fullscreen mode Exit fullscreen mode

That gives the agent, or a human, all code and documentation connected to the same concept.

Keep a tag registry

Tags need names and meanings, otherwise they drift.

I keep a simple registry such as:

# Tags

- `@tag:billing-retries` - retry behavior for failed payment operations.
- `@tag:tenant-isolation` - boundaries that prevent cross-tenant data access.
Enter fullscreen mode Exit fullscreen mode

This makes the tag set reviewable and prevents slightly different names for the same idea.

Why not just rely on the IDE index?

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.

The convention

I wrote the full convention here:

https://github.com/mpashka/llm-wiki-tags

The short version:

  • keep AGENTS.md small;
  • use index.md files for directory navigation;
  • use @tag:<slug> tokens for cross-cutting concepts;
  • register tags in docs/tags.md;
  • update docs and tags in the same change as code.

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.

Tradeoffs

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.

What I am still unsure about

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:

  • Do you keep most repo knowledge in AGENTS.md / CLAUDE.md, or in separate docs?
  • Do you have a pattern for concepts that span many directories?
  • Do visible code comments like @tag:... feel useful or noisy?
Enter fullscreen mode Exit fullscreen mode

Top comments (0)