{"slug": "coding-agents-evolved-our-repositories-didnt", "title": "Coding Agents Evolved. Our Repositories Didn’t.", "summary": "A developer argues that large AGENTS.md files waste context, hurt maintainability, and make AI-assisted development harder to scale. The developer proposes a modular repository structure with a small AGENTS.md acting as a bootloader, pointing to a versioned .harness directory containing architecture, environment, validation, and workflow files. This approach aims to reduce context consumption, improve maintainability, and enable mechanical validation.", "body_md": "Why giant `AGENTS.md`\n\nfiles may be wasting context, hurting maintainability, and making AI-assisted development harder to scale.\n\nA few years ago, for many developers, using AI for software development meant copying a small piece of code into a chat window.\n\nWe would ask for a refactoring, copy the response back into the editor, run the tests ourselves, and return to the chat when something failed.\n\nCoding agents changed that workflow.\n\nTools such as Codex, Claude Code, and others can now explore an entire repository, modify multiple files, execute commands, run tests, and iterate on failures.\n\nCoding agents turned code assistants into tools capable of executing multi-step software development tasks.\n\nBut most repositories were not designed for this new kind of contributor.\n\nA coding agent needs much more than source code.\n\nIt may need to understand:\n\nA common solution is to place these instructions inside files such as `AGENTS.md`\n\n, `CLAUDE.md`\n\n, or other agent-specific configuration files.\n\nThis works.\n\nI have been doing something similar in my own projects for a while.\n\nBut as the repository grows, the instruction file grows with it.\n\nEventually, a single file may contain thousands of lines covering unrelated concerns:\n\n```\nArchitecture\nTesting\nEnvironment setup\nCoding standards\nInfrastructure\nUI conventions\nValidation\nRelease workflows\nDefinition of done\n```\n\nAt that point, the file is no longer just a set of agent instructions.\n\nIt has become an informal repository operating manual.\n\nA large `AGENTS.md`\n\nhas an obvious advantage: the agent knows where to find it.\n\nBut it also creates several problems.\n\nThese files are not only for agents.\n\nDevelopers also need to read, review, maintain, and discuss the rules.\n\nSomeone changing a test should not need to navigate through multiplayer architecture, asset conventions, deployment rules, and UI standards.\n\nA small bug in a domain class may not require information about:\n\nWhen a large root instruction file is injected into every task, unrelated guidance may consume context that could otherwise be used for the task, the code, and the relevant documentation.\n\nArchitecture rules may remain stable for months.\n\nBootstrap commands may change after a toolchain update.\n\nValidation rules may evolve every week.\n\nKeeping all of them in one document makes ownership and maintenance harder.\n\nA giant Markdown document is mostly passive guidance.\n\nIt may describe commands that no longer work, paths that no longer exist, or rules that contradict the current codebase.\n\nThis problem is not entirely theoretical.\n\nOpenAI has publicly described moving away from a large `AGENTS.md`\n\nfile because it consumed context, became difficult to maintain, and was hard to validate mechanically.\n\nTheir solution was to use a shorter `AGENTS.md`\n\nas a table of contents for a structured repository knowledge base.\n\nThat experience supports the direction of this experiment, but it leaves an important question open:\n\nCan this approach become a vendor-neutral, reusable, and measurable repository specification?\n\nI agree with the direction OpenAI has described: `AGENTS.md`\n\nshould not contain the repository's entire operating model.\n\nIt should act as an entry point, while the detailed knowledge lives in a modular and versioned repository structure.\n\nA small bootloader.\n\nThe actual repository knowledge could live in a versioned and modular structure:\n\n```\nAGENTS.md\n    ↓\n.harness/\n├── architecture\n├── environment\n├── validation\n├── workflows\n└── manifest\n```\n\nThe `.harness`\n\ndirectory is a proposed convention, not something coding agents currently understand automatically.\n\nIn the first version, `AGENTS.md`\n\nwould remain the supported entry point and instruct the agent how to discover and use the repository harness.\n\nThe exact filenames are intentionally undefined at this stage.\n\nFor example, testing could be part of validation in a small project:\n\n```\nvalidation/\n└── testing rules and commands\n```\n\nA larger project might need a dedicated testing document containing:\n\nThe goal is not to force every repository into the same directory tree.\n\nThe goal is to define capabilities that agents can discover.\n\nWith a modular harness, an agent working on a domain bug might load:\n\n```\nArchitecture\nTesting\nValidation\n```\n\nAn agent preparing the project for the first time might load:\n\n```\nBootstrap\nEnvironment\nValidation\n```\n\nA task involving deployment might load an entirely different set.\n\nThis creates a form of progressive context loading:\n\nProvide the agent with the context required for the current task, rather than the entire repository handbook.\n\nThe approach could potentially improve:\n\nBut this is still a hypothesis.\n\nA useful repository harness should not consist only of Markdown files.\n\nWhenever possible, instructions should point to executable and reproducible operations.\n\nInstead of documenting a long sequence of test commands, the repository could expose:\n\n```\n./scripts/test-unit\n./scripts/test-integration\n./scripts/validate\n```\n\nThe Markdown explains:\n\nThe script defines how the operation is performed.\n\nThis also makes the repository easier to validate through CI and less dependent on an agent correctly reproducing a sequence of commands.\n\nThe same concept could eventually apply before coding begins.\n\nA team using Jira, GitHub Issues, Linear, Azure DevOps, another issue tracker, or an internal product backlog might define a repository-specific Definition of Ready.\n\nBefore a task enters the implementation pipeline, an agent could verify whether:\n\nThe team could also encode its agreed Definition of Done in the repository harness before implementation begins.\n\nDuring and after implementation, the agent could use that definition to determine which tests, validations, reviews, documentation updates, and manual checks are required before considering the task complete.\n\nI am starting an open project called **Repository Harness Specification**.\n\nThe first goal is to compare two versions of the same repository:\n\n```\nAGENTS.md\n```\n\nAll instructions are contained in one large file.\n\n```\nAGENTS.md\n.harness/\n```\n\nThe same information is organized into task-relevant modules that the agent can discover and load as needed.\n\nI plan to evaluate both approaches using the same:\n\nThe experiment will measure more than token consumption.\n\nPossible metrics include:\n\nReducing tokens is not useful if the agent produces worse code.\n\nThe real objective is to determine whether modular repository context can improve efficiency without reducing implementation quality.\n\nThe project will be developed publicly.\n\nThe next steps include:\n\nThe structure presented in this article is not the final specification.\n\nIt is the first experiment.\n\nCoding agents are evolving quickly.\n\nNow we need to understand how repositories should evolve with them.\n\nThe project is available at:\n\n**Repository Harness Specification**\n\n[https://github.com/Repository-Harness-Specification](https://github.com/Repository-Harness-Specification)\n\nFeedback, criticism, and contributions are welcome.", "url": "https://wpnews.pro/news/coding-agents-evolved-our-repositories-didnt", "canonical_source": "https://dev.to/lepsistemas/coding-agents-evolved-our-repositories-didnt-f4", "published_at": "2026-07-17 15:23:00+00:00", "updated_at": "2026-07-17 15:30:34.766468+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "large-language-models", "ai-tools", "mlops"], "entities": ["OpenAI", "Codex", "Claude Code"], "alternates": {"html": "https://wpnews.pro/news/coding-agents-evolved-our-repositories-didnt", "markdown": "https://wpnews.pro/news/coding-agents-evolved-our-repositories-didnt.md", "text": "https://wpnews.pro/news/coding-agents-evolved-our-repositories-didnt.txt", "jsonld": "https://wpnews.pro/news/coding-agents-evolved-our-repositories-didnt.jsonld"}}