Coding agents and AGENTS.md: a practical guide

Direct answer

A coding agent is a software worker with access to a repository and a bounded set of tools. A reliable run follows the same loop a careful engineer uses: inspect the code and instructions, form a plan, make the smallest coherent edit, run the repository's real checks, review the diff, and report what remains uncertain.

AGENTS.md is a repository-owned instruction file for that work. Put project-wide commands and constraints at the repository root. Add nested files only when a subtree genuinely needs different rules. Keep instructions short, testable, and free of secrets. Because support and precedence differ among coding agents, verify the documentation for the tool you use and write scoped files so their intent is clear without relying on ambiguous conflicts.

This guide is platform-neutral. For one editor's features and controls, see the separate Cursor AI complete guide.

What a coding agent actually does

A coding agent combines a model with tools such as file search, file reading, patching, a shell, tests, version control, and sometimes a browser. It does not understand the repository all at once. It builds a working model from the files and outputs it is allowed to inspect.

A typical cycle is:

1. read repository instructions and task context
2. locate relevant files, symbols, callers, and tests
3. inspect configuration and existing conventions
4. state or internally form a change plan
5. edit a bounded set of files
6. run formatting, lint, type checks, tests, or a build
7. inspect failures and revise
8. review the final diff and summarize evidence

The loop matters more than a particular model name. An agent that edits before inspecting is guessing. An agent that edits but never validates is producing a proposal, not a verified change.

Where coding agents help

They are strongest when the repository contains enough evidence to check the work:

• targeted bug fixes with a reproducible failure
• mechanical migrations with clear patterns
• tests for documented behavior
• small features that extend an existing architecture
• refactors protected by types and tests
• documentation tied to real code
• repository exploration and impact analysis

They are weaker when success depends on unstated product decisions, inaccessible systems, subjective visual taste, missing credentials, or knowledge held only by one person.

The inspect–plan–edit–test workflow

1. Inspect before changing

The agent should first find:

• repository-level instructions
• package or build manifests
• the implementation and its callers
• tests and fixtures
• schemas, types, and API contracts
• neighboring modules that establish the pattern
• scripts that perform real validation

A good task names the goal and constraints without dictating an unverified fix. “Checkout returns 500 when the coupon is expired; preserve the API response shape and add a regression test” is better than “change line 42 to catch every error.”

Ask for diagnosis before mutation when the cause is uncertain. The agent should be able to cite the failing path and explain why the proposed edit addresses it.

2. Plan at the right depth

A one-line typo may not need a written plan. A cross-package migration does.

The plan should identify:

• files or subsystems likely to change
• contract or data implications
• validation to run
• risky assumptions
• explicit non-goals

Planning is not a license for broad cleanup. The most maintainable change usually fits the existing architecture and touches the fewest necessary surfaces.

3. Edit in reviewable units

Prefer small patches that preserve public contracts. Reuse existing utilities and patterns. Avoid unrelated formatting, dependency changes, or abstractions unless the task requires them.

After each coherent phase, inspect the changed file and eventually the complete diff. Generated files should be produced by the project's generator rather than hand-edited when the repository says so.

4. Validate with the repository's commands

The agent should read the actual scripts instead of inventing npm test or an equivalent command. Run the narrowest useful checks first, then broader checks proportional to risk:

1. focused test for the failure or component
2. linter and type checker for changed code
3. related test suite
4. build or integration test when contracts or routing changed

Record the command, exit result, and important limitations. “Looks correct” is not validation. Neither is claiming a command passed when it was not run.

5. Review the final diff

Check for:

• unintended files
• debug output and commented experiments
• exposed secrets or private data
• weakened authorization or validation
• stale documentation
• missing error, empty, and loading states
• contract changes not reflected in callers or tests

The final report should distinguish completed work, checks actually run, preserved behavior, and uncertainty.

What AGENTS.md is for

AGENTS.md gives coding agents durable repository context close to the code. Think of it as an operational guide for automated contributors, not a replacement for human documentation.

Good content includes:

• repository layout and which package owns what
• installation, build, lint, type-check, and test commands
• required checks for common change types
• code-generation and migration rules
• architecture boundaries and forbidden dependencies
• naming, API, and error-handling conventions not obvious from code
• security constraints and files that must not be read or changed
• pull-request or reporting expectations

Do not copy a full style guide into it when formatters and linters already enforce the rules. Point to the canonical document or command.

Root scope and nested scope

A root AGENTS.md should contain rules that apply to the whole repository:

# Repository guide

## Setup and checks
- Install with: npm ci
- Run lint with: npm run lint
- Run type checks with: npm run typecheck
- Run focused tests before the full suite.

## Boundaries
- Preserve public API response shapes unless the task changes the contract.
- Never edit generated files directly; run the documented generator.
- Do not commit credentials, environment files, or production data.

A nested AGENTS.md belongs near a package or subtree with additional requirements:

repository/
  AGENTS.md
  apps/
    web/
      AGENTS.md
  services/
    billing/
      AGENTS.md

The billing file might require an idempotency test and forbid live payment calls. The web file might name accessibility checks and browser-test commands.

The common convention is that a nested file applies to its directory subtree and more specific instructions refine or override broader ones. However, exact discovery order, supported filenames, precedence, size limits, and handling of conflicts are implementation details. Consult your coding agent's current documentation. Avoid contradictory instructions where possible; explicit, self-contained nested rules are easier to apply across tools.

Write rules an agent can execute

Weak:

> Use best practices and make the code production ready.

Strong:

> API handlers validate request bodies with the existing schema module. Return the established error envelope. Run the route's focused test and npm run typecheck.

Weak:

> Be careful with the database.

Strong:

> Do not run destructive database commands. Schema changes require a migration file and backward-compatibility note. Tests use the disposable local database only.

Each instruction should answer at least one of these:

• what must the agent inspect?
• what may or may not change?
• which existing pattern is canonical?
• what command proves the work?
• when must a human approve?

Use headings and bullets. Keep one source of truth. Delete obsolete instructions when architecture changes.

A practical AGENTS.md template

# Working in this repository

## Scope
- This file applies to the entire repository.
- Read a more specific AGENTS.md before changing a nested package.

## Architecture
- apps/web owns UI and HTTP composition.
- packages/domain owns business rules and has no framework imports.
- packages/data owns persistence adapters.

## Workflow
1. Inspect the implementation, callers, and related tests.
2. Make the smallest change that preserves public contracts.
3. Add or update a regression test for changed behavior.
4. Review the complete diff before reporting.

## Commands
- Install: npm ci
- Lint: npm run lint
- Type check: npm run typecheck
- Tests: npm test
- Build: npm run build

Verify these scripts exist before running them.

## Safety
- Never read, print, edit, or commit .env files or credentials.
- Never call production services from tests.
- Do not run destructive database or version-control commands.
- Ask before adding a dependency or changing a public API.

## Completion report
- List changed files.
- List checks actually run and their results.
- State unresolved assumptions or checks that could not run.

Adapt command names to the repository. A copied template with nonexistent scripts is worse than no command section.

Repository rules beyond AGENTS.md

Keep enforcement in the strongest appropriate layer:

• formatter and linter for style
• type system and schemas for contracts
• tests for behavior
• branch protection and CI for required gates
• filesystem and sandbox permissions for access
• secrets manager for credentials
• AGENTS.md for context, workflow, and decision boundaries

Instructions guide the agent; they do not enforce security. “Do not access production” is useful, but credentials and network access should also make production access impossible.

Avoid duplicated rules across README files, tool-specific configuration, and nested AGENTS.md files. If several coding tools are used, keep shared principles in the portable file and add tool-specific settings only for capabilities unique to that tool.

Permissions and approval boundaries

Start from least privilege. A coding agent usually needs read access to the repository and write access to a worktree. It does not automatically need:

• production credentials
• cloud administration
• package publishing
• deployment rights
• unrestricted network access
• access to unrelated repositories
• permission to merge or delete branches

Separate reading, editing, command execution, network access, and external writes. Require approval for actions with wider or irreversible impact:

• installing or upgrading dependencies
• running migrations
• modifying infrastructure
• changing authentication or authorization
• contacting external services
• publishing packages or content
• deploying or merging

For unattended work, use an isolated branch or worktree, a sandbox, non-production fixtures, bounded execution time, and explicit egress policy.

Secrets and sensitive data

Never place API keys, passwords, access tokens, private certificates, or customer data in AGENTS.md, prompts, committed fixtures, or screenshots.

Safer patterns:

• refer to environment-variable names, not values
• use secret scanning in local hooks and CI
• inject short-lived credentials only into the process that needs them
• redact command output and traces
• use synthetic or anonymized fixtures
• prevent the agent from reading credential directories
• rotate a secret immediately if it enters model context or a commit

An ignore file is not an access control. A file excluded from Git may still be readable by a local process. Enforce permissions and scope the agent's filesystem.

Validation by change type

Define evidence proportionally:

If a check cannot run because a service or credential is unavailable, the agent should report that limitation. It should not weaken tests or silently replace integration evidence with a mock.

Safe task specification

Give the agent a concise contract:

Goal:
Fix duplicate invoice creation when a retry follows a timeout.

Constraints:
- Preserve the POST response schema.
- Do not contact the live payment provider.
- Use the existing idempotency module.
- Do not change unrelated billing code.

Acceptance:
- A regression test reproduces the retry.
- Exactly one invoice is created.
- Billing tests, lint, and type checks pass.

Approval:
Ask before changing the database schema or adding a dependency.

This tells the agent what success means while leaving room to discover the correct implementation.

When coding agents fail

Missing context

The relevant contract lives in a ticket, production dashboard, or engineer's memory. The agent fills the gap with a plausible assumption.

Response: provide the source, state the unknown, or ask the agent to stop after investigation.

Weak or contradictory instructions

One file says to use a service layer; a nested guide says handlers call the database directly.

Response: resolve the conflict in the repository. Do not rely on the model to guess which policy is current.

Overbroad tasks

“Modernize the backend” has no measurable terminal state and invites unrelated rewrites.

Response: split work by contract and give each task acceptance criteria.

Poor observability

The failure occurs only in production and there are no logs, traces, fixtures, or reproduction steps.

Response: instrument or capture a safe reproduction before asking for a fix.

Inadequate tests

The agent changes behavior and the existing suite stays green because it never covers the path.

Response: require a failing regression test or explicit manual evidence before the implementation.

Environment mismatch

The local toolchain, operating system, database, or dependency versions differ from CI.

Response: pin versions, use reproducible setup, and run CI before treating the change as complete.

Excessive permissions

A mistaken command or injected instruction can reach production, secrets, or destructive tools.

Response: reduce capability structurally. Instructions alone are not a sandbox.

Validation theater

The agent runs one easy check, ignores warnings, or reports success despite skipped tests.

Response: define required commands and inspect the actual output and diff.

Unreviewable change size

A large generated diff hides a subtle contract or security regression.

Response: constrain scope, split commits, and require targeted review by subsystem owners.

Review an agent's work

Review the output as if it came from a new contributor:

1. Does the diff solve the stated failure?
2. Is the root cause supported by evidence?
3. Did public contracts or data assumptions change?
4. Are authorization and validation still server-side?
5. Do tests fail without the fix and pass with it?
6. Were the real repository commands run?
7. Are there unrelated edits, dependencies, or generated artifacts?
8. What remains unverified?

Never merge because the explanation sounds confident. The repository, test output, and diff are the evidence.

Adoption workflow

Day 1: choose a bounded task

Use a low-risk bug or documentation drift with clear acceptance criteria. Keep production access unavailable.

Day 2: write the root guide

Document architecture boundaries, actual commands, safety constraints, and completion evidence. Keep it under review with the code.

Day 3: run and observe

Watch where the agent searches, what it misunderstands, and which checks it misses. Fix repository documentation only for lessons likely to recur.

Day 4: add one scoped guide if needed

Create a nested file only if a package has genuinely distinct commands or risk controls.

Day 5: automate gates

Move enforceable rules into lint, tests, CI, permissions, and secret scanning. Leave contextual judgment in AGENTS.md.

Completion checklist

• [ ] Root AGENTS.md contains real, current commands
• [ ] Architecture and public-contract boundaries are explicit
• [ ] Nested instructions exist only for distinct subtrees
• [ ] Tool-specific nesting and precedence have been verified
• [ ] Permissions are least-privilege and production is isolated
• [ ] Secrets are excluded by access controls, not only instructions
• [ ] Tasks define goal, constraints, acceptance, and approvals
• [ ] Agent inspects before editing and reviews the final diff
• [ ] Validation matches the change risk
• [ ] Reports distinguish passed checks from unverified work

Continue learning

• AI agents explained ? the architecture behind coding agents
• Agent Skills guide ? package repeatable repository workflows
• AI agent security ? control tools, secrets and approvals

Official sources

• AGENTS.md project: Open format and examples
• OpenAI Codex: Custom instructions with AGENTS.md
• GitHub: Customizing the development environment for Copilot coding agent and Adding repository custom instructions

Takeaways

Coding agents work best as constrained contributors inside a repository that exposes its architecture, commands, and checks. They should inspect, plan, edit, test, and review—not jump from prompt to patch.

AGENTS.md makes durable instructions portable and close to the code, while permissions, schemas, tests, and CI enforce the boundaries that prose cannot. Keep the file scoped, current, and specific; then judge every agent change by the diff and validation evidence.