--- title: "Agent-friendly repo conventions: AGENTS.md, structure, tests" source: https://www.taim.io/agentic-coding/agent-friendly-repo-conventions published: Sat May 09 2026 10:51:18 GMT+0000 (Coordinated Universal Time) updated: Thu Jul 23 2026 05:28:33 GMT+0000 (Coordinated Universal Time) description: "Set up AGENTS.md, predictable paths, and verifiable commands so coding agents can navigate your repository, test changes, and retry with useful feedback." --- # Agent-friendly repo conventions: AGENTS.md, structure, tests An agent-friendly repository does not need more documentation. It needs better evidence: exact commands, predictable paths, visible boundaries, and tests that clearly pass or fail. An agent-friendly repository does not need more documentation. It needs better evidence: exact commands, predictable paths, visible boundaries, and tests that clearly pass or fail. ## What you will learn - How to write AGENTS.md instructions that guide real work - How repository structure can reduce wrong file and pattern choices - How to test an agent's understanding, inspect the feedback, and retry - How to align local validation with the checks enforced in CI ## Find your starting level Before adding files or reorganizing directories, test whether a new collaborator can answer three questions: where should this change go, which existing pattern should it follow, and how should it be verified? Use the table to identify the first constraint worth fixing. Starting level What you observe First move Unmapped Build or test commands live in memory, chat, or old pull requests Record the commands that work now Documented but ambiguous A README exists, but contributors still choose inconsistent paths or helpers Add exact paths, boundaries, and named patterns Structured Root instructions work, but subprojects require different commands or conventions Add narrowly scoped nested instructions Verifiable Local commands and CI checks are clear and repeatable Test instructions against real tasks and remove stale guidance Do not begin by documenting the entire architecture. Begin with the smallest task that exposes whether the repository can guide an unfamiliar contributor. ## Make a first attempt in 25 minutes Choose a recently completed change that touched no more than a few files. Your first attempt is not to reproduce the change. It is to see whether an agent can locate the right path and propose a valid verification plan. 1. Create a draft root `AGENTS.md` with a project map, setup command, focused test command, full validation command, one important boundary, and one named pattern. 2. Ask the agent to plan the selected change without editing files. 3. Require the plan to name files, reusable helpers, likely tests, and commands it would run. 4. Compare the plan with the actual implementation and repository conventions. 5. Record each wrong assumption as an instruction problem, a structure problem, or an agent reasoning problem. A useful prompt is concrete: `Plan this change without editing files. Name the files you expect to touch, the existing pattern you will copy, and the commands you will run to verify the result.` This constraint makes feedback visible. A vague request such as `review the repo` produces a broad summary that tells you little about whether the setup can support real work. ## Write AGENTS.md for decisions, not background AGENTS.md is an open Markdown format for giving coding agents project context and instructions. Useful content includes a project overview, build and test commands, code style, testing instructions, and security considerations. Start with executable facts. A compact draft can look like this: Markdown `# Project map - app/: application entry points - lib/server/: server-only modules - tests/: integration tests # Commands - Install: npm ci - Focused test: npm test -- path/to/test - Full validation: npm run check # Boundaries - Browser code must not import from lib/server/. - Database access goes through lib/server/db.ts. # Change pattern - Build article URLs with articlePath(). Do not concatenate paths. ` Replace every example command and path with values verified in your repository. If the repository uses another package manager, runtime, or test runner, document that reality instead of copying familiar commands. Include Skip Commands a contributor can run Architectural history with no effect on the task Exact directories and ownership boundaries Third-party documentation copied into the repository Named helpers or reference implementations Style rules already enforced automatically Required validation and security constraints Aspirational conventions the codebase does not follow There is no source-backed universal line limit for this file. Keep it focused enough that every instruction can affect a file choice, implementation choice, or validation step. ## Use nested instructions only when scope changes Large repositories often contain subprojects with different commands or constraints. Nested `AGENTS.md` files can provide subproject-specific instructions, with the closest applicable file taking precedence. GitHub supports repository-wide instructions, path-specific instructions, and agent instruction files; for AGENTS.md, the nearest file in the directory tree takes precedence. That makes nested files useful, but it also makes contradictions expensive. A root file should contain shared facts such as repository shape, common commands, and global safety rules. Add a nested file only when a subtree has a different runtime, test command, generated-code policy, ownership boundary, or implementation pattern. For example, `packages/mobile/AGENTS.md` might replace the root validation command with the mobile package's command. It should not restate every shared convention. Duplication creates two places that can drift. ## Make the structure answer common questions A coding agent learns repository conventions from paths, imports, tests, configuration, and instructions. Your directory structure should make the common path easy to infer without pretending that one layout fits every framework. Question Strong repository signal Weak repository signal Where does a new feature go? Similar features share a recognizable location and shape Related files are scattered without a documented mapping Which helper should be reused? A public module exports the preferred helper Several local helpers perform nearly the same task Where is runtime-specific code? Paths or module boundaries make the runtime visible Server and browser imports are mixed until a build fails Where are tests? Tests are co-located or follow one documented mapping Each package uses an unexplained convention Who owns a cross-cutting concern? Logging, auth, and data access have named entry points Contributors copy the nearest implementation Co-located tests are one valid choice, not a universal requirement. A centralized test directory works when its mapping to production code is consistent and documented. The same caveat applies to `lib/server/` and `lib/client/`. These are useful examples, not standards. Preserve framework conventions when they already communicate the boundary clearly. ## Read feedback as evidence, then retry After the planning attempt, ignore how polished the answer sounds. Inspect whether the agent chose the right files, found the preferred helper, respected boundaries, and proposed commands that actually exist. > Use the Two-Failure Rule for repository guidance. One wrong choice may come from a difficult task; the same wrong choice twice exposes durable ambiguity. Fix that ambiguity with one exact path, command, or reference example, then rerun the same task and compare the evidence. Feedback signal What it means Retry adjustment Correct files and commands The map and validation guidance are usable Keep the instruction and test a different task Correct area, wrong helper The repository exposes competing patterns Name the preferred helper and a reference file Wrong subtree Scope or ownership is unclear Add a directory map or nested instructions Invented command Validation guidance is missing or stale Copy the verified local or CI command exactly Claimed success without output Completion criteria are weak Require command, exit status, and failure summary A weak first attempt does not call for a longer document by default. Make the smallest correction that addresses the observed error, then submit the same prompt again. The retry succeeds when the agent changes the relevant decision. If it merely produces a more detailed explanation while keeping the wrong files or commands, the feedback loop has not improved. ## Let tests and CI define completion Do not impose universal speed targets on unit, integration, or end-to-end suites. Runtime, hardware, test isolation, repository size, and external dependencies all affect duration. Measure the repository's current commands and optimize the checks that block the most frequent work. Give the agent at least one focused check for the changed area and one broader command that matches the repository's completion standard. Record the actual command rather than labels such as `run the tests`. Text `Focused check: Required full check: CI-only check: ` GitHub Actions workflows are YAML files in `.github/workflows`; they use events, jobs, and steps to run scripts or reusable actions. Workflows can build and test pull requests, so they provide a useful place to inspect what the repository actually enforces. Compare local instructions with CI rather than assuming they match. If CI runs formatting, type checks, generated-file checks, or package-specific tests, either expose equivalent local commands or state clearly which evidence appears only after the workflow runs. Fast feedback still matters, but the actionable target is repository-specific: improve the command used after ordinary edits, track its measured duration in your environment, and watch for regressions. Do not teach an agent to skip required checks merely because they are slow. ### Agent-friendly repo field reference #### Root AGENTS.md Start with 5 sections: project map, setup, focused validation, full validation, and boundaries. Include at least 1 exact path and 1 named reference implementation. There is no universal line limit; remove content that cannot change a coding or verification decision. #### Nested AGENTS.md Add one only when a subtree changes at least 1 material rule, such as runtime, command, generated-code policy, or implementation pattern. The closest applicable file takes precedence, so keep shared rules in the root and avoid copied text. #### Project map Describe each major directory in 1 sentence. For every common change type, a contributor should be able to identify one likely starting directory without searching the full repository. #### Validation commands Record 3 categories where available: a focused check, the required full check, and any CI-only check. Copy commands from working scripts or workflow configuration, then run them before publishing the instructions. #### Runtime boundaries Name the restricted path, the allowed importer, and the preferred alternative. Treat paths such as lib/server/ as examples only; use the conventions of your framework and repository. #### Feedback review Check 4 outputs from every trial: selected files, reused patterns, proposed commands, and reported evidence. A confident summary without command output or explicit uncertainty is poor verification. #### Two-Failure Rule After the same wrong assumption appears in 2 comparable attempts, add one exact instruction or reference example. Rerun the original task and keep the change only if it improves the relevant decision. #### CI alignment Compare local instructions against every required pull-request workflow. Record missing local equivalents and identify checks that can only run in CI instead of implying that local success proves full completion. ### Common questions #### How often should I update AGENTS.md? Update it when a command, path, boundary, or preferred pattern changes. Also update it when comparable tasks reveal the same wrong assumption twice. Do not add every isolated mistake, since that turns the file into a log of edge cases. After each edit, rerun the task that exposed the problem and confirm that the new instruction changes the agent's decision. #### Should AGENTS.md be checked into the repository? Yes, when it describes shared repository facts and team expectations. Version control lets contributors review instruction changes alongside code and keeps the file available in fresh checkouts. Do not place personal preferences, local secrets, credentials, or machine-specific paths in it. If a tool needs private local guidance, keep that material in the tool's supported local configuration instead. #### What belongs in lint configuration instead of AGENTS.md? Put mechanically detectable rules in formatters, linters, type systems, tests, or policy checks when practical. Examples include import restrictions, formatting, forbidden dependencies, and filename patterns supported by your tooling. Use AGENTS.md to explain decisions that require context, such as which public helper to prefer or which validation command applies to a package. If the document says a rule is mandatory but no check enforces it, state how a reviewer should verify it. #### How should I introduce a new repository-wide pattern? Implement one clear reference example before documenting the pattern as established practice. Point AGENTS.md to that file, name the old pattern being replaced, and add automated enforcement only when the rule can be checked reliably. Migrate touched code first unless the repository needs an immediate coordinated change. Test the instruction with a small task and verify that the agent copies the intended pattern rather than merely repeating its name. ### Make the repository prove the path **The best agent-friendly repo setup is not the one with the longest instruction file.** It is the one that helps an unfamiliar contributor choose the right location, reuse the right pattern, and produce evidence that the change works. Start with a bounded task. Watch where the agent guesses. Correct recurring ambiguity with an exact command, path, boundary, or reference file, then retry the same task. That practice loop turns repository guidance into tested infrastructure rather than passive documentation. ### Try this in your repository - Draft or audit one root AGENTS.md. Verify every command and remove any paragraph that cannot affect a real decision. - Run the 25-minute planning attempt on a small completed change. Record wrong assumptions under instructions, structure, or reasoning. - Fix the smallest recurring ambiguity, rerun the same prompt, and compare file choices, reused patterns, commands, and evidence. - Inspect required CI workflows and reconcile them with the validation commands documented for local work. ### Sources and further reading 1. [AGENTS.md](https://agents.md/) Agentic AI Foundation AGENTS.md is an open Markdown format for giving coding agents project context and instructions. Useful content includes a project overview, build and test commands, code style, testing instructions, and security considerations. 2. [Adding repository custom instructions for GitHub Copilot](https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions) GitHub Docs GitHub supports repository-wide instructions, path-specific instructions, and agent instruction files; for AGENTS.md, the nearest file in the directory tree takes precedence. 3. [Workflows](https://docs.github.com/en/actions/concepts/workflows-and-actions/workflows) GitHub Docs GitHub Actions workflows are YAML files in .github/workflows; they use events, jobs, and steps to run scripts or reusable actions.