A repo-native context pattern for Codex: AGENTS.md + index.md + searchable tags

Codex
,
1

I’ve been experimenting with a small convention for keeping durable repository context usable by Codex and other coding agents.

The problem I’m trying to solve: AGENTS.md is a good entry point for agent instructions, but it can become too large if we keep adding architecture notes, workflow notes, domain concepts, and “remember this part of the repo” guidance into one file.

The pattern I’m testing is llm-wiki by Andrej Karpathy:

  1. Keep AGENTS.md short. It tells the agent how to navigate the repo context, not every detail of the repo.
  2. Create docs/ directory and put all structured documentation into it. Add rule for the agent to search and read appropriate documents before each task and update when necessary.
  3. Put an index.md in every meaningful docs/ directory. Each index gives short descriptions and links for local files/subdirectories, so the agent can follow the codebase tree intentionally.
  4. Add explicit @tag:<slug> tokens in both docs and code comments for cross-cutting concepts. For example, @tag:auth-bootstrap can appear in a design note, service code, tests, config, and migration docs.
  5. Keep a small docs/tags.md registry so each tag has one clear meaning.

I wrote the convention in github/mpashka/llm-wiki-tags repo.

The goal is intentionally low-tech: Markdown plus text search. It does not depend on a specific IDE, embedding index, or vendor. Codex, Cursor, Claude Code, or a human using grep can all follow the same context layer.

I’m curious how other Codex users handle this:

  • Do you keep long-lived repo knowledge in AGENTS.md, separate docs, or both?
  • Do you have a pattern for concepts that cut across many directories?
  • Would visible @tag: comments in code be useful, or would they feel like noise?