{"slug": "a-low-tech-repo-context-pattern-for-ai-coding-agents", "title": "A low-tech repo context pattern for AI coding agents", "summary": "A developer created a low-tech pattern for providing repository context to AI coding agents using Markdown files and text search. The approach uses short index.md files in each directory for navigation and @tag: tokens in code and docs to link cross-cutting concepts. The pattern aims to keep agent instructions small while enabling effective context retrieval without vendor-specific tools.", "body_md": "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.\n\nThe pattern I ended up with is deliberately boring: Markdown plus text search.\n\nAI assistance disclosure: I used an AI assistant to help draft this post, then reviewed and edited it before publishing.\n\nWhen a coding agent starts working in a repository, it needs at least two kinds of context:\n\nA single `AGENTS.md`\n\n, `CLAUDE.md`\n\n, 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.\n\nAt some point it becomes a context dump.\n\nThe first layer is close to Andrej Karpathy's llm-wiki idea: every meaningful directory gets an `index.md`\n\n.\n\nThat 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.\n\nThis helps the agent navigate top-down instead of blindly searching the whole repository.\n\nExample:\n\n```\nsrc/payments/\n  index.md\n  PaymentService.ts\n  RetryPolicy.ts\n  tests/\n    index.md\n```\n\nThe root agent instruction file can then stay small:\n\n```\nBefore editing code, read the nearest index.md files and follow their links.\nAfter changing behavior, update the affected docs and indexes.\n```\n\nDirectory navigation is not enough for concepts that span the tree.\n\nFor example, `tenant isolation`\n\n, `billing retries`\n\n, `auth bootstrap`\n\n, or `audit logging`\n\nmight involve service code, tests, migrations, config, documentation, and deployment scripts.\n\nThose concepts do not fit neatly into one folder.\n\nFor that, I use explicit tags:\n\n```\n@tag:billing-retries\n@tag:tenant-isolation\n@tag:audit-logging\n```\n\nThe same token appears in both code comments and docs.\n\nExample in code:\n\n```\n// @tag:billing-retries\nexport class RetryPolicy {\n  // ...\n}\n```\n\nExample in docs:\n\n```\n---\ntags: \"@tag:billing-retries @tag:payments\"\n---\n```\n\nNow plain search works:\n\n```\ngrep -rn \"@tag:billing-retries\" .\n```\n\nThat gives the agent, or a human, all code and documentation connected to the same concept.\n\nTags need names and meanings, otherwise they drift.\n\nI keep a simple registry such as:\n\n```\n# Tags\n\n- `@tag:billing-retries` - retry behavior for failed payment operations.\n- `@tag:tenant-isolation` - boundaries that prevent cross-tenant data access.\n```\n\nThis makes the tag set reviewable and prevents slightly different names for the same idea.\n\nIDE and agent indexes are useful, but they mostly understand code structure: symbols, files, references, imports, definitions.\n\nThey are weaker at human concepts.\n\nA 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.\n\nI wrote the full convention here:\n\n[https://github.com/mpashka/llm-wiki-tags](https://github.com/mpashka/llm-wiki-tags)\n\nThe short version:\n\n`AGENTS.md`\n\nsmall;`index.md`\n\nfiles for directory navigation;`@tag:<slug>`\n\ntokens for cross-cutting concepts;`docs/tags.md`\n\n;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.\n\nThe obvious risk is stale documentation.\n\nThe 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`\n\n, the relevant page, and any tags affected by the change.\n\nThe other risk is tag noise. I would not tag every function. Tags are useful for stable concepts that cut across the directory tree.\n\nI am still experimenting with where the line should be between useful tags and clutter.\n\nI would be interested in how other people structure persistent context for AI coding agents:\n\n`AGENTS.md`\n\n/ `CLAUDE.md`\n\n, or in separate docs?`@tag:...`\n\nfeel useful or noisy?", "url": "https://wpnews.pro/news/a-low-tech-repo-context-pattern-for-ai-coding-agents", "canonical_source": "https://dev.to/mpashka/a-low-tech-repo-context-pattern-for-ai-coding-agents-4k25", "published_at": "2026-07-08 20:23:42+00:00", "updated_at": "2026-07-08 20:41:20.318684+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "large-language-models"], "entities": ["Andrej Karpathy", "Codex", "Cursor", "Claude Code"], "alternates": {"html": "https://wpnews.pro/news/a-low-tech-repo-context-pattern-for-ai-coding-agents", "markdown": "https://wpnews.pro/news/a-low-tech-repo-context-pattern-for-ai-coding-agents.md", "text": "https://wpnews.pro/news/a-low-tech-repo-context-pattern-for-ai-coding-agents.txt", "jsonld": "https://wpnews.pro/news/a-low-tech-repo-context-pattern-for-ai-coding-agents.jsonld"}}