How to write an AGENTS.md file

An AGENTS.md file gives a coding agent the repository instructions it needs before changing code. Start with the commands and boundaries that would stop a new teammate from making an expensive mistake. A short file with working instructions is more useful than a long description of how careful an agent should be.

Factory's AGENTS.md reference describes how Droid discovers project guidance and narrower instructions while inspecting files. The procedure below starts with one root file, verifies it against a real task, and adds more detail only when the repository needs it.

Before editing, identify the repository root, the package manager, and the scripts used by CI. You should be able to run the relevant checks locally. If those commands are broken or undocumented, resolve that uncertainty before telling an agent to depend on them.

Start the AGENTS.md file with verified commands

Open the package manifest, build configuration, and CI workflow. Copy the commands that the project actually uses. Run them from the directory where you expect the agent to work, and record any required package filter or setup step.

Distinguish a focused check from the full gate. A unit test for one package can provide quick feedback, while a shared API change may require tests for its consumers. State when each command is appropriate rather than requiring the slowest possible command after every edit.

For a project that already defines test, typecheck, and lint scripts, a starting file could look like this. These commands and paths are an example, not a template to paste without checking your repository.

# Repository guide
 
## Commands
 
- Install dependencies: `pnpm install --frozen-lockfile`
- Run tests: `pnpm test`
- Run type checks: `pnpm typecheck`
- Run lint: `pnpm lint`
 
## Scope
 
- Keep edits within the requested task.
- Check callers before changing a shared interface.
- Edit generator inputs, then regenerate their outputs.
- Ask before changing production data or deployment settings.
- Never put credentials in source files, logs, or examples.
 
## Completion
 
- Add a regression test when fixing a bug.
- Run the relevant checks and report their actual results.
- Review the diff for unrelated changes.
- Identify any checks that could not run and explain why.

Add the command that starts the application when a task requires a browser or API test. Document required local dependencies without including credentials. Refer to your approved secret-management process instead of embedding a connection string.

The expected result is a file whose commands another engineer can execute without guessing. If a command works only in one person's shell, the instructions are not ready for a clean agent environment.

Put the important boundaries in writing

Add a short repository map only where directory names leave a meaningful ambiguity. Name the source of generated files, the owners of shared interfaces, and the paths that require special approval. Explain the specific behavior a reviewer can check.

“Preserve the design” leaves room for interpretation. “For article changes, do not edit shared page components or global styles” describes a boundary a reviewer can check. “Run the schema generator after changing the API definition” identifies an action and an artifact.

Avoid copying entire architecture documents into the file. Link to the maintained source and explain when the agent should read it. Keep temporary task details in the issue or task request so the standing instructions do not accumulate yesterday's exceptions.

Treat written guidance and enforced controls separately. AGENTS.md helps Droid understand the task, but it does not replace repository permissions, branch protection, or a security policy. Factory's autonomy controls govern which actions can proceed without repeated approval. A sentence in a Markdown file should not be your only protection against a consequential action.

Add nested AGENTS.md files only for real differences

A monorepo may contain packages with different languages, test commands, or generators. Put the shared rules at the root and add a nested AGENTS.md where a subtree genuinely needs different instructions.

Factory documents dynamic discovery when Droid reads files in a directory tree. A session starting at the root can discover narrower guidance later, as it inspects a package. Do not assume every nested file has already been loaded simply because it exists somewhere in the repository.

Keep the nested file focused on the differences. For a service with a different test runner, name that command and its working directory. For generated code, identify the input file and regeneration step. Repeating the entire root policy creates more places for instructions to disagree.

If several coding tools share the repository, verify each tool's official discovery rules. AGENTS.md adoption does not guarantee identical scope or precedence across products. Avoid making a second copy under another compatible filename unless there is a concrete requirement that you have tested.

Test the instructions on a small change

Use a branch or worktree with no unrelated edits. Pick a bounded task whose expected result is clear, such as correcting a small bug with an existing reproduction. Do not make a sensitive migration the first test of new instructions.

1. Ask Droid to identify the applicable instructions, working directory, and validation commands before editing.
2. Review its proposed scope and correct any misunderstanding before it changes files.
3. Let it make the bounded change, then inspect the diff and the recorded check results.
4. Confirm the expected behavior yourself through the relevant test or user-facing flow.

Success means the commands ran in the correct place, the change stayed inside scope, and the completion report matches the evidence. A passing test does not excuse an unrelated refactor, and a confident summary does not substitute for a test result.

When something goes wrong, improve the smallest missing instruction. If Droid edits generated output, name the generator input. If it runs the wrong tests, provide the focused command and working directory. Avoid responding to every failure with another page of general warnings.

Keep guidance aligned with the repository

Review AGENTS.md when package scripts, architecture boundaries, or generation steps change. The instruction update belongs with the code change that made the old rule inaccurate.

If a nested rule is missed, check its filename, directory, and whether the session inspected that subtree. If personal preferences conflict with project rules, rewrite them as defaults rather than repository requirements.

Move long, repeatable procedures into Factory skills when they are needed only for particular tasks. Keep the root file for the durable commands, constraints, and verification requirements that affect everyday work.

Factory's published guidance on linters explains how architectural conventions can become executable checks. Use that approach for rules a tool can reliably enforce. The Markdown explains the intent, while the linter or test provides evidence that the change respects it.

Further reading

• Coding agents in monorepos
• Coding agent task specifications that work
• Agent readiness: fix the repos slowing your rollout