We argue that source repositories are no longer just containers for human-authored code — they are containers and generators of knowledge supporting the interaction of humans with AI agents. Taking this perspective demands that we rethink how we structure projects, write documentation, and more broadly how we rethink the entire software development process. We draw on experience building a verification framework where ~90% of code, documentation, and tests were authored by AI agents under human direction and distill the structural patterns that made this possible.
Moving Beyond “AI-Assisted Coding”
The dominant model for AI in software development is the assistant: a human writes most of the code and occasionally asks a chatbot for help with a function, a regex, or a debugging session. Tools like GitHub Copilot, Cursor, and ChatGPT have made this workflow highly productive.
But a second model is emerging. In agent-driven development, AI agents are not assistants, they are the primary authors and maintainers of code, documentation, and tests. The human’s role shifts from writer to reviewer, from implementer to technical team lead. The agent reads the repository, understands its conventions, generates code that conforms to them, runs the test suite, and submits a pull request. The human sets the direction, reviews the diff, intervenes when things go awry, and is responsible for 360-degree oversight. Andrej Karpathy has described a similar trajectory in his “Software 3.0” vision, where natural language prompts and AI agents become the new programming interface, and the LLM functions as an operating system around which applications must be designed. Our framing of the repository as an interface for such an AI contributor is a natural extension of that vision.
This shift changes what a repository needs to be. When a human onboards to a project, they absorb conventions through code review, pair programming, Slack conversations, and institutional memory. An agent may not have access to these channels and may not be aware of institutional knowledge. As a result, it is important to capture such information directly in files the repository. If a convention isn’t written down in a place the agent can find and parse, the agent won’t have enough context.
This observation — that implicit project knowledge should be explicit and agent-accessible — has implications for how we structure repositories. Repositories have always stored processes, code, data, and documentation. But now the content must be retargeted to support agent consumption. It is, in essence, a knowledge representation problem.
The Knowledge Gap Problem
Consider what happens when an AI agent is asked to add a new component to an unfamiliar codebase. The agent needs to answer a cascade of questions:
- What naming conventions does this project use?
- Where do new components go in the directory structure?
- What’s the error-handling pattern?
- What tests need to be written, and where?
A human developer answers these questions through a combination of README skimming, code browsing, and asking teammates. An agent answers them by reading whatever documentation and instruction files are available in its context window. The gap between what the agent needs to know and what the repository explicitly tells it is the knowledge gap, and it can lead to agents taking incorrect actions, writing bad code, etc.
In our experience building AVA (Agent Verification Architecture)— a pipeline for verifying AI agents, itself built almost entirely by AI agents — we encountered this knowledge gap repeatedly in the early stages. Agents would generate code that was functionally correct but conventionally wrong: right behavior, wrong file location, wrong class naming pattern, wrong error-handling idiom. Each such error required a correction cycle, which in turn required the human to articulate the convention they had been carrying implicitly.
The solution was not to write better prompts. It was to write better repositories.
Structure for Machines, Review for Humans
The core principle we arrived at is deceptively simple: optimize the repository for alignment with AI agents while keeping it human-reviewable. This inverts the traditional priority. Most projects document for humans first and hope machines can figure it out. Agent-driven projects must document for machines first, knowing that humans can still read structured text perfectly well.
What does this look like in practice? Here are some approaches based on our experiences:
| Dimension | Human-Optimized | Agent-Optimized |
| Conventions | Tribal knowledge, code review | Explicit rules in instruction files |
| Documentation | Prose paragraphs | Tables, JSON examples, key-value pairs |
| Architecture | UML diagrams, whiteboards | Formal specs with MUST/SHOULD/MAY |
| Navigation | Folder browsing, IDE search | Dedicated entry-point documents with explicit file paths |
| Validation | Manual code review | Conformance tests tied to specs |
None of this makes the repository worse for humans. A table of conventions is at least as useful to a new human developer as it is to an agent. The difference is that for humans it’s a convenience that can be worked around through other information sources.
The recommendation to include an AI instruction file in a repository is now widespread. Tens of thousands of open-source projects have adopted AGENTS.md or similar files, and the Linux kernel has an RFC proposing a standardized AI_INSTRUCTIONS file with symlinks shared across AI tools. GitHub’s own analysis of over 2,500 such files found that effective ones enumerate commands, outline project structure, and specify coding style concretely — while vague ones provide little benefit. What we describe here goes further: not just what to include, but how to layer and scope the information so the agent encounters the right conventions at the right time.
A Documentation Hierarchy for Agents
We found that agents consume documentation in a predictable order and structuring it as a hierarchy improves first-attempt success rates.
| Level | File / Artifact | Purpose / Notes |
| 0 | AGENTS.md | Injected into every agent session automatically |
| 1 | agent-reference.md | Architecture overview, schemas, skills, commands |
| 2 | specs/*.md | Formal component contracts (RFC 2119) |
| 3 | Source code + tests | Ground truth |
Level 0 is the thin dispatcher — build commands, lint commands, pointers to deeper documents, and universal conventions. It must be concise because it is injected into every context window. Think of it as the header file for your project.
Level 1 is where an agent goes for orientation. It contains the architecture overview, data structure schemas with concrete JSON examples, CLI syntax, etc. This is the single document an agent reads before starting any task.
Level 2 contains formal specifications using RFC 2119 language (MUST, SHOULD, MAY). Each spec defines an interface contract, input/output schemas, conformance test scenarios, error-handling requirements, etc. When an agent is asked to implement a new component, the spec is its complete, unambiguous target.
The most important rule governing this hierarchy: each fact lives in exactly one document. All other references are links. The moment the same table appears in both Level 0 and Level 1, you’ve introduced a stale duplicate — the most common failure mode in agent-driven development. The documents will drift apart, the agent will read whichever one fits in its context window, and it will act on outdated information. One of us (Don Syme) calls this “the burden of actualisation”: the more elaboration stages you expose, the more cached intermediates must be reconciled under change. Our single-source-of-truth discipline attempts to address this problem — it minimizes the surface area that must be kept consistent.
Unfortunately, more documentation is not automatically better. A 2026 study by Gloaguen et al. found that coding agents given lengthy, boilerplate context files sometimes performed worse than those with no context at all. The takeaway is not that context files are useless, but that they must be concise and high-impact: build commands, naming conventions, domain-specific invariants — facts the agent cannot infer from reading the code. Our hierarchy enforces this by keeping Level 0 thin and pushing detail into deeper levels that the agent retrieves only when relevant. In effect, the repository’s four-level documentation structure essentially transforms it into a hierarchical knowledge base.
Scoped Instructions: Convention as Code
Modern AI coding tools support pattern-scoped instruction files — files that are automatically injected into the agent’s context only when it touches matching file paths. This mechanism turns conventions into something resembling code: they are version-controlled, scoped to specific directories, and enforced through the agent’s own behavior.
For example, the AVA project uses multiple scoped instruction files:
tests.instructions.md (applied when editing tests/**):
- Tests must work with and without LLM access
- CLI tests must accept both exit codes 0 and 1
- Import from ava.pipeline directly, not sample entry points
docs.instructions.md (applied when editing docs/**):
- Every document must include audience frontmatter
- Never duplicate content — link to the single source of truth
These scoped instructions solve a problem that comments and README files cannot: they inject the right conventions at the right time, without consuming context window space when the agent is working elsewhere in the codebase. They are, in effect, region-specific type annotations for your project’s implicit contracts.
Specs Before Code: The Agent-Era Development Loop
Perhaps the most significant shift we discovered is in the development workflow itself. When a human implements a feature, they often start with code, iterate toward correctness, and document afterward. When an agent implements a feature, this workflow produces mediocre results — the agent infers requirements from surrounding code, which may be incomplete or inconsistent.
In our work, we found that a reliable pattern is:
Specification → Conformance Tests → Implementation → Validation
Write the spec first, in formal language. Translate the spec’s conformance scenarios into deterministic test functions. Then ask the agent to implement. With a clear spec and failing tests, the agent’s task is well-defined and mechanically verifiable. We used this loop for all 11 pipeline components in AVA, producing 115+ conformance tests that validate spec compliance without requiring an LLM.
This approach has deep roots. Bertrand Meyer’s Design by Contract methodology established the principle of writing formal interface contracts before implementation. Amazon’s use of TLA+ specifications has shown that formal methods catch ambiguities that, left implicit, confuse both human and AI developers. As mentioned, Don Syme has developed a framework of Intent/Actualisation Toolchains, which provides a useful theoretical lens: the spec-first loop is an instance of his observation that reliable toolchains interpose elaboration stages (Spec → Test → Code) between user intent and actualization. What’s new is the audience: the “contract” is no longer just between human-authored modules — it is between the human architect and the AI agent implementing the code. As some of us have previously argued in “Prompts Are Programs,” treating prompts and specifications as engineered, maintainable artifacts (rather than throwaway text) dramatically improves reliability. Our specs extend this principle beyond a single prompt to the entire project knowledge base.
To illustrate: one of our specifications states, “The validator MUST reject any trace event with a tool_name on the destructive-commands blocklist.” The conformance test creates a trace containing “rm -rf /”, passes it to the validator, and asserts a violation is raised. When the agent implemented the validator, it read this spec, saw the failing test, and produced a correct implementation on the first attempt — no iteration required.
This is not test-driven development as traditionally practiced. TDD tests exercise implementation behavior. Conformance tests validate interface contracts. The distinction matters because agents are better at implementing to a spec than they are at reverse-engineering a spec from tests.
Anti-Patterns in Agent-Driven Repositories
Through trial and error, we identified recurring failure modes:
Inaccessible Knowledge. A convention exists only in one developer’s head. The agent violates it, the human corrects it but doesn’t write it down. The next agent session repeats the violation. Fix: every convention goes in an instruction file.
Stale Duplicate. The same architecture diagram appears in the README and in the design doc. One gets updated. The agent reads the wrong one. This issue relates to the known “Strawberry Problem” that highlights how models have trouble tracking duplication. Fix: single source of truth with links.
Monolithic Prompt. A human gives the agent a sprawling task with no decomposition. The agent loses context halfway through and produces inconsistent results. Fix: break tasks into independent subtasks with explicit dependencies. Research on Chain-of-Thought prompting and the ReAct framework has shown that prompting LLMs to reason and act in steps dramatically improves accuracy on complex tasks compared to one-shot prompts.
Unchecked Assumption. The agent makes a reasonable-seeming architectural choice silently. Weeks later, the human discovers it chose a suboptimal approach. Fix: require agents to surface design decisions for human review.
Stale Dependent. A source file is updated but its derived artifacts are not. For example, a workflow definition is edited but the compiled lock file isn’t regenerated. The system silently uses the outdated artifact causing failures to surface later in CI or production. This differs from the stale duplicate: duplicates are about content appearing in two places, while stale dependents are about derived artifacts not being regenerated from their sources. Fix: maintain a declarative file-dependency manifest.
Premature Knowledge Optimization. Akin to “Premature Optimization”. The human might, for example, commit to using Node, and spend hours writing the perfect prompt to guide Node development. But the assumptions of the project might change, and the project could switch to another framework. Fix: anticipate that in working with agents decisions can rapidly evolve, leading to a different trade-off between planning and execution.
Each of these anti-patterns has an analog in traditional software engineering, but the consequences are more severe with agents because agents lack the social feedback mechanisms (code review discussions, hallway conversations) that catch these problems early in human teams. As the OpenSSF’s Security Best Practices guide for AI-assisted coding emphasizes: “You remain in full control of the code; critically review and test AI contributions just as you would those from a human”.
Implications for the Community
If prompts are programs — as we argued in a prior blog post — then repositories are the runtime environment in which those programs execute. The quality of the runtime determines the quality of the execution. This observation has several implications worth exploring:
For tooling. We need repository linters that detect agent-hostile patterns: missing instruction files, duplicated content across documents, undocumented naming conventions, specs without corresponding tests. Just as we lint code for style and correctness, we should lint repositories for agent-readiness. Beyond linters, targeted autofix-assists that act on the output of linters complete the automation cycle.
For language design. Scoped instruction files are a nascent form of behavioral typing — declaring invariants that hold within a region of the codebase. Can we formalize this? What would a type system for repository conventions look like?
For software engineering research. The spec-first development loop is not new — it echoes design-by-contract, formal methods, and specification-driven development. But AI agents may be the forcing function that finally makes these practices mainstream, because agents genuinely perform better with formal specs in ways that human developers historically resisted.
For teams. Agent-driven development doesn’t eliminate the need for human expertise — it redistributes it. Humans spend less time writing code and more time goal setting, elaborating constraints, shaping specifications, reviewing code changes, and designing the knowledge base that informs agent action in the repository. This is architectural work, and it requires taste, judgment, and domain knowledge that agents don’t possess.
Conclusion
We began this project with a goal of building a verification framework and at the same time were interested in learning how to build an agent-first repository. We found that making a repository agent-friendly is not a matter of adding a README section or configuring a tool. It requires rethinking the repository as a source and generator of knowledge — one consumed primarily by machines, reviewed by humans, and optimized for a very specific kind of comprehension.
The patterns we’ve described — documentation hierarchies, scoped instruction files, formal specifications, single-source-of-truth discipline, and conformance testing — are not exotic. They are well-understood software engineering practices applied to a new audience. What’s new is the urgency: when your primary developer is an AI agent, every implicit convention is a latent bug, lost project velocity, or wasted time.
Repositories have always been artifacts that communicate intent and guide forward progress. In the age of AI agents, that communication must become precise, structured, and aligned with the agent’s capabilities and ability to interpret. We are just starting to understand the best ways to evolve human/agent collaboration and we share this perspective based on our specific experience. We hope it provides insights and stimulates conversations that help the whole community evolve that understanding.
The patterns described in this post were developed while building AVA, an agent verification framework where ~90% of code, documentation, specs, and tests were authored by AI agents (GitHub Copilot CLI) under human architectural direction. The repository itself serves as a worked example of the conventions described here.
Peli de Halleux is a Principal Research Software Developer Engineer in Redmond, Washington working in the Research in Software Engineering (RiSE) group. His research interests include empowering individuals to build LLM-powered applications more efficiently.
Don Syme is a Principal Researcher with GitHub Next and Visiting Professor at Kings College London working on AI-assisted software development. He’s the creator of the F# language, is the co-inventor of language integrated async/await programming and played a key role in the design of generics in C# and the .NET platform. His current work focuses on Continuous AI and repository automation.
Ben Zorn is a Partner Researcher at Microsoft Research in Redmond, Washington working in (and previously having co-managed) the Research in Software Engineering (RiSE) group. His research interests include programming language design and implementation, end-user programing, and empowering individuals with responsible uses of artificial intelligence.
Disclaimer: These posts are written by individual contributors to share their thoughts on the SIGPLAN blog for the benefit of the community. Any views or opinions represented in this blog are personal, belong solely to the blog author and do not represent those of ACM SIGPLAN or its parent organization, ACM.
