AGENTS.md Guide: Practical Examples and a Real Next.js Template

AGENTS.md gives a coding agent the project context it needs to work in your repository: where code belongs, which commands exist, what a change should preserve, and how to report verification.

This guide includes a short generic template and an annotated template based on a real Next.js, TypeScript, and pnpm repository. You will also learn how to check whether your coding tool loaded the file and use a small task to evaluate the resulting behavior.

Documentation checked: November 15, 2026. The repository example is pinned to a specific commit. Its files and scripts were inspected; dependencies, the application build, and coding-agent sessions were not run for this guide. The sample agent response below is explicitly an expected structure.

What is AGENTS.md?

AGENTS.md is a Markdown file containing instructions for coding agents. The official format has no required fields, mandatory headings, or YAML frontmatter. You can begin with a few useful paragraphs and expand them when your project needs more context. Official AGENTS.md guide

For a first version, answer four practical questions:

• Which files or directories matter for common tasks?
• Which setup and verification commands actually work in this repository?
• Which project conventions are easy to miss by looking at one file?
• What should an agent report when it cannot complete a check?

Prefer a fact that changes a decision. “The marketing homepage is app/(dashboard)/page.tsx” helps an agent find the right file. “Write excellent code” gives it little to act on.

AGENTS.md vs README.md, CLAUDE.md, and SKILL.md

These files serve related purposes, but they are maintained and loaded differently.

The AGENTS.md website distinguishes human-oriented project documentation from agent instructions. The Agent Skills specification defines a skill as a directory with a SKILL.md containing required name and description frontmatter; scripts and references can accompany it. AGENTS.md · Agent Skills specification

For example, a repository instruction might say which existing database module to use. A migration skill could provide the reusable procedure for planning and validating a migration. Linking or naming a skill does not, by itself, install it in every coding tool.

For more on the reusable package format, read What Are Agent Skills? and What Is SKILL.md?.

Keep detailed setup documentation in its established location. Add the short, consequential facts an agent needs, with a link to the longer explanation when relevant.

A short generic AGENTS.md template

Save the following as AGENTS.md in your repository root. If a file already exists, merge the useful parts into it after reading the existing instructions.

This starter deliberately avoids assuming your package manager, directory structure, or test commands. Add those facts after inspecting the repository.

Download the generic template. Save or merge it as AGENTS.md; the descriptive download filename is not an automatic-discovery filename.

# AGENTS.md

## Project context

- Use the README for the product overview and setup instructions.
- When setup or validation matters, inspect the current manifest, lockfile,
  relevant configuration, and any CI workflow before choosing commands.
- Keep the package manager already used by this repository.

## Making changes

- Follow the patterns in the files you are changing and nearby examples.
- Keep edits within the requested task. Explain any necessary wider change.
- Reuse existing helpers before introducing another implementation.
- When changing a documented command or directory, update its instructions
  in the same change.

## Validation

- Run the relevant checks that actually exist and fit the change.
- If a check needs unavailable dependencies, credentials, or services,
  report the missing prerequisite.
- If no relevant automated check exists, say so and describe the manual
  inspection performed. Do not invent a script or claim an unrun check passed.
- Use setup, migration, seed, and deployment commands only when that work
  is part of the requested task.

## Handoff

- Summarize the change and name the affected files.
- List checks actually run and their outcomes.
- List checks not run, with the reason and any remaining uncertainty.

The useful next improvement is specificity. Replace discovery work with verified facts where they save repeated effort: the real package manager, a non-obvious entry point, a supported command, or a service prerequisite. Remove any instruction that does not help your project.

Inspect the project before adding commands

For a JavaScript or TypeScript project, use this source map when drafting its instructions:

Treat this as a drafting checklist, not a requirement to reread the whole repository for every edit. A copy change and a database migration need different amounts of context.

Before documenting a command, establish its working directory, prerequisites, purpose, and side effects. Also distinguish three claims:

1. The command is declared in the repository.
2. Someone executed it in a specified environment.
3. It completed successfully in that environment.

Reading package.json supports the first claim. It does not establish the other two.

A real Next.js, TypeScript, and pnpm example

This example uses Next.js SaaS Starter at commit 6e33e58b1e553a41fe22e6b941a7229a002de361.

The inspected snapshot uses Next.js 15.6.0-canary.59, TypeScript, PostgreSQL with Drizzle, Stripe, and Tailwind CSS. Its README uses pnpm and it includes pnpm-lock.yaml, but its manifest does not pin a pnpm version with a packageManager field. This is a fixed repository example for learning how to write instructions; check your own revision before adopting its details. package.json · README · Lockfile

Three details materially change what the instructions should say:

• The homepage has a non-obvious location. It lives at app/(dashboard)/page.tsx. Guessing app/page.tsx would point to the wrong location. Homepage source
• The manifest declares no lint, typecheck, or test script. The example must not instruct an agent to run those script names as if they exist. Declared scripts
• Setup commands have meaningful effects. The environment example requires .env unless configuration changes. The seed script writes database records and creates Stripe products and prices. These are setup operations, not a substitute for checking a small code edit. Environment example · Seed implementation

Complete annotated template

Place this file at the root of that repository as AGENTS.md. The comments explain the evidence behind each section. This is an original teaching template; it is not an instruction file published by the repository maintainers.

Download the annotated Next.js template. Pinned commit: 6e33e58b1e553a41fe22e6b941a7229a002de361. Recheck paths, commands, and prerequisites before using another revision. Save or merge the adapted file as AGENTS.md.

# AGENTS.md

<!-- Original teaching template for nextjs/saas-starter, not an upstream file.
     Source snapshot: 6e33e58b1e553a41fe22e6b941a7229a002de361.
     Repository facts were inspected on 2026-11-15.
     Recheck the facts below before using this with another revision. -->

## Project context

- This is a Next.js App Router application using TypeScript, PostgreSQL,
  Drizzle, Stripe, and Tailwind CSS.
- Follow the existing pnpm workflow and retain `pnpm-lock.yaml`.
- The inspected manifest uses Next.js `15.6.0-canary.59`. It has no
  `packageManager` field; do not claim an exact pnpm version is pinned.

<!-- Directory facts come from the Git tree. Names alone can be misleading:
     the marketing homepage is inside the (dashboard) route group. -->

## Where changes belong

- Marketing homepage: `app/(dashboard)/page.tsx`.
- Pricing: `app/(dashboard)/pricing/`.
- Signed-in dashboard: `app/(dashboard)/dashboard/`.
- Sign-in, sign-up, and related actions: `app/(login)/`.
- HTTP route handlers: `app/api/`.
- Reusable UI primitives: `components/ui/`.
- Authentication and session helpers: `lib/auth/`.
- Database schema, queries, and migrations: `lib/db/`.
- Stripe integration and payment actions: `lib/payments/`.
- Global styles: `app/globals.css`.

<!-- These are suggested working rules for this tutorial, not claims about
     the upstream maintainers' existing policy. -->

## Change conventions

- Follow nearby components and reuse existing UI and library helpers.
- Preserve the strict TypeScript configuration in `tsconfig.json`.
- The `@/*` alias maps to the repository root; follow existing imports.
- Keep copy and styling tasks scoped to their relevant pages/components.
- For schema changes, use `lib/db/schema.ts` and the migration output
  directory `lib/db/migrations`, as configured in `drizzle.config.ts`.
- Update this file when its commands, paths, or prerequisites change.

<!-- Installation follows the README. The development and database script
     names below come from package.json in the pinned snapshot.
     Listing a command does not mean it was run or will pass. -->

## Development and build commands

- Install dependencies: `pnpm install`, as documented in the README.
- Development server: `pnpm dev` (`next dev --turbopack`).
- Production build: `pnpm build` (`next build`).
- Serve a completed production build: `pnpm start` (`next start`).
- There are no `lint`, `typecheck`, or `test` scripts in this snapshot.
  Do not run `pnpm lint`, `pnpm typecheck`, or `pnpm test` as if they exist.

## Environment and database work

- Follow `.env.example`; this project expects `.env`, not `.env.local`
  unless its environment-loading configuration is changed.
- Required variable names documented there are `POSTGRES_URL`,
  `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, `BASE_URL`, and `AUTH_SECRET`.
  Keep secret values out of committed files and task reports.
- `pnpm db:setup` runs an interactive setup that writes `.env`, uses the
  Stripe CLI, and can create/start a local Docker database.
- `pnpm db:generate` generates database migration files.
- `pnpm db:migrate` applies migrations to the configured database.
- `pnpm db:seed` writes database records and creates Stripe products/prices.
- `pnpm db:studio` opens the database management interface.
- Run these setup/database commands only for requested environment or
  database work, using the intended development/test services.

<!-- Validation should describe observed evidence. A build command's
     existence is not evidence of a passing build or a test suite. -->

## Validation and handoff

- Inspect the diff for the requested scope and check the relevant code.
- For application changes, run `pnpm build` when dependencies and the
  required environment are available and the check fits the task.
- If build prerequisites are missing, identify them and mark the build
  as not run. If the build fails, report the actual failure.
- Do not run migrations or seed services merely to complete a code review.
- Report changed files, checks actually run, their results, and checks
  not run. State explicitly when no applicable automated test is configured.

The directory map was checked against the complete Git tree. The strict TypeScript setting and import alias come from tsconfig.json; the migration paths come from drizzle.config.ts. Setup behavior comes from lib/db/setup.ts.

The comments make this version useful for learning. When adapting it, retain the verified project facts and working rules you want, and shorten the explanatory notes. Update the snapshot information to reflect what you actually checked.

What about a TypeScript check?

The absence of a typecheck script does not mean TypeScript cannot be checked. It means the project has not declared that named workflow. If you introduce a direct compiler command or a new script, document it as a new project decision and validate it before presenting it as an established check.

Likewise, a successful build should be reported as a successful build. Do not turn it into a claim that a nonexistent test suite passed.

Try the template with a small task

You can inspect the pinned example without installing dependencies or configuring its services. If you want a separate tutorial checkout, use a new directory:

git clone https://github.com/nextjs/saas-starter.git agents-md-saas-example
cd agents-md-saas-example
git checkout --detach 6e33e58b1e553a41fe22e6b941a7229a002de361

Copy the annotated template into that directory as AGENTS.md. Start a fresh coding-agent session there and use the platform-specific loading checks in the next section.

Then send this task:

Find the marketing homepage's main heading and propose a clearer alternative.
Do not edit files, install dependencies, or configure services.
Identify the file and current wording, explain the scope of the proposed
change, and report which validation commands this repository actually has.
Separate checks you performed from checks you did not run.

Expected response structure

This is an expected example, not an executed agent transcript. The path, existing heading, and script inventory were verified in the repository. The suggested replacement is editorial.

File
app/(dashboard)/page.tsx

Current heading
Build Your SaaS
Faster Than Ever

Suggested heading
Launch Your Next SaaS
With the Essentials in Place

Scope
A proposed text-only change to the existing h1 and its span.
No files edited.

Repository commands
dev, build, start, db:setup, db:seed, db:generate, db:migrate, db:studio.
No lint, typecheck, or test script is declared in package.json.

Available validation candidate
pnpm build, when dependencies and the required environment are available.
dev/start are runtime commands; db:* commands are environment/database
operations and were not needed for this source-reading task.

Checks performed
Read the homepage source and package.json.
Compared the proposed edit with the existing heading structure.

Checks not run
Dependency installation, build, browser inspection, database commands,
and Stripe operations. This was a source-reading and proposal task.

Remaining uncertainty
The proposed text has not been checked in the rendered page layout.

Evaluate the observed response against the task: did the agent find the actual file, distinguish declared scripts from performed checks, and keep setup operations outside the task? A correct answer is evidence of useful behavior. It does not, by itself, establish how the instruction file entered the context.

How to check whether your coding tool loaded AGENTS.md

Check both instruction discovery and behavior on a relevant task. A file's existence, an assistant's claim that it read it, and compliance with every instruction are different kinds of evidence.

The following guidance is based on official documentation checked on November 15, 2026. Product versions and modes matter.

Codex

Codex builds its instruction chain at session start. It combines global guidance with files from the project root down to the working directory; deeper guidance takes precedence. Within each directory, AGENTS.override.md is checked before AGENTS.md. The default combined project-document limit is 32 KiB.

Start from the intended directory and ask:

Summarize the project instructions already available to this session.
Identify their source paths where possible. Do not modify files.

For stronger discovery evidence, the official guide documents an opt-in TUI log:

codex -c log_dir=./.codex-log

Inspect .codex-log/codex-tui.log for loaded instruction sources. Restart after changing instructions; use the relevant subdirectory as the working directory when checking nested discovery. Codex AGENTS.md documentation

Claude Code

Direct AGENTS.md loading requires v2.1.277 or later. By default, project CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in the working directory or ancestors takes priority; otherwise AGENTS.md loads. User-level and managed instructions do not trigger that exclusion.

To load both, select claude-md-and-agents-md under /config → Project instructions. Alternatively, add this to a neighboring CLAUDE.md:

@AGENTS.md

Check the loaded path with /memory. Before v2.1.280, directly loaded AGENTS.md files were absent from that list; before v2.1.281, some sessions also lacked direct-loading support. Update older versions and check whether the built-in AGENTS.md plugin is disabled. Claude does not directly load AGENTS.override.md. Claude Code memory documentation

GitHub Copilot CLI

Copilot CLI discovers AGENTS.md in supported repository and working paths. Run /instructions to inspect discovered files and their enabled status. Its documented behavior combines applicable instruction files without defining a general precedence order between them, so avoid conflicting rules. This guidance is specific to the CLI; check support separately for other Copilot surfaces. Copilot CLI custom instructions

A useful secondary diagnostic

Ask the agent to distinguish instructions supplied automatically from files it explicitly opens during your diagnostic. If it reads AGENTS.md only after you request it, you have confirmed file access, but not automatic discovery.

For an optional experiment, temporarily add a unique marker to the file:

When asked for an instruction-loading diagnostic, include the marker
`cobalt-maple-42` in the diagnostic report.

Start a new session and ask for that diagnostic without putting the marker in your prompt. Seeing it is evidence that the content was available in the session. Combine this with the platform's discovery evidence and remove the marker afterward. It does not prove that every rule will be followed.

Root and nested AGENTS.md files

Begin with one root file. Add a nested file when a directory needs substantial, different guidance. Put shared facts in the root and local additions near the relevant code.

For this example, lib/db/AGENTS.md could eventually explain a verified migration workflow. Avoid copying the whole root document into it: duplicated facts create multiple places to update.

The AGENTS.md website describes a closest-file convention, but loading and conflict behavior are implemented by each host. Test the exact directory and product mode you use. Prefer compatible additions over contradictory instructions that depend on one tool's precedence rules. AGENTS.md usage guidance

Common mistakes and better instructions

For example, replace:

Be careful when changing the database.

with a project-specific instruction:

For schema changes, inspect lib/db/schema.ts and drizzle.config.ts.
Keep generated migrations in lib/db/migrations.
Report any migration you generated or applied and the target environment.

That instruction tells the agent where to look and what evidence to return. Your team can further refine the workflow after verifying it in its development environment.

Keep the file accurate as the project changes

Review the corresponding instructions when a change affects package scripts, directory names, setup requirements, CI checks, or supported coding tools. Keep that update in the same change whenever practical.

A focused review asks:

• Does every referenced path still exist?
• Is every documented script still declared, and is its purpose accurate?
• Are prerequisites and side effects still described correctly?
• Do local and shared rules agree?
• Can a rule be removed because it is obvious, redundant, or no longer useful?
• Have we checked discovery in the product and mode we actually use?

If a check must be enforced, implement it in the relevant tool, permissions, or CI configuration. Instruction text can guide an agent, but it does not replace an enforcement mechanism.

Frequently asked questions

Does AGENTS.md need YAML frontmatter?

No. The official format is ordinary Markdown without required fields. The headings in these templates are editorial choices. A quality check should assess useful, accurate instructions rather than impose an invented schema. Official FAQ

Should I copy the Next.js template into every Next.js project?

Use it as a method and starting point. First replace its source snapshot, paths, scripts, package-manager assumptions, environment details, and working rules with facts and decisions from your repository.

What should I write if my project has no test script?

State that directly. Describe existing validation and honest reporting expectations. If you add tests later, update the instructions once the new workflow exists and has been checked.

Should every reusable workflow live in AGENTS.md?

Keep the shared repository guidance compact. A repeatable procedure with its own examples or supporting files may belong in a skill; a long architecture explanation may belong in project documentation. Point to those resources when they are relevant.

Does a link guarantee that another file is loaded?

No. An ordinary Markdown link can point readers to a file, while automatic imports depend on the host. Check its documented import mechanism and loaded context instead of assuming that a link expands the target.

Can I treat a correct answer as proof of loading?

A correct answer may also come from reading the source code. Use the host's instruction listing or logs to investigate discovery, and use a controlled task to evaluate the behavior you care about.