AI時代のリポジトリ構成 — AGENTS.md と知識ベースの分離This article proposes three design principles for AI-era repositories: a single…

As AI coding agents shift from experimental novelty to an everyday part of the development workflow, the way a repository is organized has become a practical performance factor rather than a matter of taste. A blog post published on Zenn, in the context of tools such as Cursor, argues exactly this point and proposes three design principles for what it calls AI-era repositories. The piece is aimed at people who have AI agents write code on a daily basis, and at anyone who repeatedly agonizes over where configuration files should live.

The first principle is to keep a single source of truth. Rather than duplicating instructions across many tool-specific files, the author recommends designating one canonical document and reducing each tool's own file to a thin pointer that references it. This is where the AGENTS.md convention enters the discussion. AGENTS.md has emerged as an attempt to provide a shared, tool-neutral place for agent instructions, standing in contrast to the proliferation of proprietary formats such as .cursorrules, CLAUDE.md, and Copilot instruction files. The concern the post addresses is a familiar one: when the same guidance is copied into several files, those copies drift out of sync, and the agent may act on stale or contradictory information. Centralizing the content and pointing to it keeps maintenance manageable.

The second principle is progressive disclosure, a term borrowed from information architecture and interface design that here refers to how much context an agent loads at once. Instead of forcing every detail into the agent's view at all times, the structure is designed so that deeper documentation is pulled in only when it is actually needed. This appears to be motivated by the practical limits of context windows and by the observation that overloading an agent with irrelevant material can degrade rather than improve its output. By layering information, a repository can present a concise overview by default and reveal specifics on demand, which is likely to help both cost and accuracy.

The third principle is to separate the repository that handles operations from the repository that holds world knowledge. In the author's framing, one repository is responsible for actions and manipulation, while another carries broader domain or background knowledge. Splitting these concerns is intended to prevent the operational codebase from becoming entangled with reference material that changes on a different cadence and serves a different purpose. This separation also aligns with the growing practice of treating knowledge bases as first-class, independently maintained assets that agents can consult.

The post is explicit about its scope. It concerns the design policy for repository and directory structure and deliberately does not cover the operating procedures of individual tools. In other words, it is a structural and architectural argument rather than a step-by-step configuration guide. The suggested reading order moves from an overall picture to a chapter on the product side and then to a chapter on the agent side, indicating that the author treats the product-facing and agent-facing concerns as distinct layers worth reasoning about separately.

For readers unfamiliar with the surrounding landscape, some background helps explain why these principles are being discussed now. Over the past couple of years, coding assistants and agentic tools have converged on the idea of repository-level instruction files that tell the agent how a project is built, tested, and structured. Because each vendor initially introduced its own file name and format, projects that use more than one tool ended up maintaining overlapping instructions. Efforts like AGENTS.md are a response to that fragmentation, and the design advice in this article can be read as an attempt to bring order to the same problem from the repository side. The broader theme, sometimes described as context engineering, is about deciding what an agent should see, when, and from where.

None of the three principles is presented as a rigid rule, and they are offered as a proposal rather than an established standard. Their value is likely to depend on team size, the number of tools in use, and how heavily an organization relies on agents day to day. Still, the underlying message is consistent with where much of the industry appears to be heading: as agents take on more of the routine coding work, the human effort shifts toward curating clear, well-structured, and non-redundant context for them to consume.