Agent-friendly repo conventions: AGENTS.md, structure, tests

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.

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. 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. 2

   Ask the agent to plan the selected change without editing files

3. 3
   Require the plan to name files, reusable helpers, likely tests, and commands it would run.
4. 4

   Compare the plan with the actual implementation and repository conventions

5. 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:

# 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.

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.

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.

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.

Focused check: <exact command for the changed package or test>
Required full check: <exact command expected before review>
CI-only check: <check that cannot run locally, plus the reason>

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.