Template and checklistUpdated Jul 19, 2026By Editorial Automation Desk

AGENTS.md Template for Codex and Monorepos

Build, audit, copy, and download concise AGENTS.md starters for Codex, Node.js, Python, and monorepos with commands, boundaries, and review checks.

Best for: Developers setting up Codex-compatible agents, team leads standardizing repo instructions, and maintainers cleaning stale agent rules.
Use this guide to: Developers want a copyable AGENTS.md template instead of another explanation of what instruction files are.

Quick Answer

A useful AGENTS.md template gives Codex copyable repo instructions: project purpose, install command, test command, safe edit boundaries, forbidden files, and review expectations. Start with one root file, then add nested AGENTS.md files only for Node.js, Python, or monorepo packages that need different commands, ownership, or safety boundaries.

Browser-only builder

Build a concise AGENTS.md starter

Choose a stack, replace every example command, then audit the file before committing it.

Project nameRepository typeInstall commandTest commandLint commandBuild commandPreferred edit pathsRestricted paths

The builder uses fixed rules and never reads your repository. Verify every command and delete guidance already enforced elsewhere.

Rule-based starter check100/100 · Strong27 lines · 124 words

# AGENTS.md

## Project

- My project is a Node.js repository.
- These instructions apply to the entire repository unless a nearer AGENTS.md overrides them.

## Setup

- Install dependencies with `npm ci`.

## Verification

- Run `npm test` after changing behavior.
- Run `npm run lint` before handoff.
- Run `npm run build` when the change affects packaging or production output.

## Safe edit boundaries

- Prefer edits in src/, tests/.
- Do not read or modify secret files or .env*, node_modules/, dist/ without explicit approval.
- Never expose credentials, delete data, or write to production systems.

## Definition of done

- Keep the change scoped and follow the nearest repository instructions.
- Report changed files, checks run, skipped checks, and remaining risks.

Download AGENTS.md Open the full instruction checker

Starter files

AGENTS.md template previews

Copy the root template first, then choose the Node.js, Python, or monorepo edition that matches the repository.

Repository AGENTS.md

Give coding agents repository-wide setup, change, and verification rules.

# Repository instructions

## Scope
- These instructions apply to the whole repository.
- Read a nearer AGENTS.md before editing files in a nested directory.

## Setup
- Install dependencies with `npm ci`.
- Start local development with `npm run dev`.

## Change rules
- Follow existing module boundaries and naming conventions.
- Do not change generated files or lockfiles unless the task requires it.
- Keep user-facing behavior backward compatible unless the request says otherwise.

## Verification
- Run `npm run lint`.
- Run `npm test`.
- Run `npm run build` for production-facing changes.

## Delivery
- Summarize changed files and verification results.
- Report skipped checks and remaining risks explicitly.

Cautions

Replace commands with commands that actually exist in the repository.
Put directory-specific exceptions in a nested AGENTS.md instead of expanding the root file.

Download AGENTS.md

Node.js AGENTS.md

Give Codex concrete Node.js setup, lint, test, build, safety, and delivery rules.

# Node.js repository instructions

## Scope
- These instructions apply to the whole Node.js repository.
- Read a nearer AGENTS.md before editing a nested package.

## Setup
- Install the locked dependency graph with `npm ci`.
- Start local development with `npm run dev`.

## Project map
- Application code: `src/`
- Tests: `tests/` or colocated `*.test.*` files
- Generated output: `dist/`, `.next/`, and coverage folders

## Change rules
- Reuse existing modules before adding a production dependency.
- Do not edit generated output or dependency lockfiles unless the task requires it.
- Keep public APIs backward compatible unless the request explicitly changes them.
- Never expose secrets, tokens, or customer data in code, fixtures, logs, or output.

## Verification
- Run `npm run lint`.
- Run `npm test`.
- Run `npm run build` for production-facing changes.

## Delivery
- Summarize changed files and observable behavior.
- Report exact verification results, skipped checks, and remaining risks.

Cautions

Keep only commands that exist in package.json and work from a clean checkout.
Replace paths and generated folders with the repository's real layout.

Download AGENTS.node.md

Python AGENTS.md

Give Codex explicit Python environment, test, formatting, migration, and secret-handling rules.

# Python repository instructions

## Scope
- These instructions apply to the Python service in this repository.
- Follow a nearer AGENTS.md when a package has different commands or ownership.

## Setup
- Create a virtual environment with `python -m venv .venv`.
- Install dependencies with `.venv/bin/python -m pip install -r requirements.txt`.

## Project map
- Application code: `src/` or the documented package directory
- Tests: `tests/`
- Migrations: the repository's migration directory

## Change rules
- Use the project virtual environment for commands and tests.
- Do not edit migrations, lockfiles, generated clients, or production data without approval.
- Keep secrets out of source, fixtures, snapshots, logs, and prompts.
- Preserve public function and API behavior unless the request explicitly changes it.

## Verification
- Run `.venv/bin/python -m pytest`.
- Run the repository's configured formatter and linter.
- Run type checking when the project configures it.

## Delivery
- Summarize changed modules and behavior.
- Report exact test results, skipped checks, migration impact, and remaining risks.

Cautions

Replace the virtual-environment, package, migration, lint, and type-check commands with project-specific values.
Do not add a new formatter or type checker merely because the template mentions those checks.

Download AGENTS.python.md

Monorepo AGENTS.md

Define root policy, workspace commands, nested overrides, and cross-package boundaries for a monorepo.

# Monorepo instructions

## Scope and precedence
- This root AGENTS.md defines shared policy for every workspace.
- Read the nearest nested AGENTS.md before editing a package.
- A nested file should override only commands, paths, or ownership that differ locally.

## Setup
- Install the full workspace from the repository root with `npm ci`.
- Do not run a second package manager inside a workspace.

## Workspace map
- Applications: `apps/`
- Shared packages: `packages/`
- Generated artifacts: `generated/`, `dist/`, and build-cache folders

## Change rules
- Keep package-specific edits inside the owning workspace when possible.
- Coordinate public API changes with every consuming workspace and its tests.
- Do not edit generated artifacts, deployment manifests, migrations, or lockfiles without task-specific justification.
- Never expose repository, CI, or production credentials.

## Verification
- Run root lint and unit tests.
- Run the affected workspace's focused tests and build.
- Run cross-workspace integration checks when a shared package changes.

## Delivery
- List affected workspaces, changed public APIs, and generated outputs.
- Report focused and root verification results, skipped checks, and rollout risks.

Cautions

Replace npm commands with the repository's actual workspace runner and package filters.
Create nested AGENTS.md files only where commands or ownership differ; avoid duplicating the root policy.

Download AGENTS.monorepo.md

Codex precedence

How AGENTS.md loading priority works

Verified against OpenAI's AGENTS.md documentation on July 19, 2026.

1
Global defaults~/.codex/AGENTS.override.md → AGENTS.md
Codex uses the first non-empty file at the global level.
2
Repository rootAGENTS.override.md → AGENTS.md → configured fallback
At most one instruction file is included for each directory.
3
Nested directorynearest AGENTS.override.md or AGENTS.md
Files closer to the working directory appear later and override earlier guidance.

Codex builds this chain once per run, skips empty files, and stops when the combined instruction size reaches the configured limit. Keep shared policy near the root and local exceptions near the code they govern.

Evidence reviewed

Build, audit, copy, and download concise AGENTS.md starters for Codex, Node.js, Python, and monorepos with commands, boundaries, and review checks. Evidence reviewed for this template and checklist: OpenAI Codex AGENTS.md documentation; GitHub Copilot custom instructions; Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?. Decision scope: Developers want a copyable AGENTS.md template instead of another explanation of what instruction files are. Product behavior after Jul 19, 2026 and any benchmark result not shown on this page remain unverified.

Best next step

Check the CLAUDE.md vs Copilot Instructions support matrix. Use the template only after you know which file each coding tool actually reads.

Methodology and disclosure

KyenAI writes this guide as an independent editorial reference, not as an endorsement page for any third-party tool. The comparison, checklist, or workflow advice is based on visible source material from OpenAI, GitHub, arXiv, plus the operational constraints named on the page. Product behavior, pricing, availability, and enterprise controls can change after the listed update date, so vendor-specific claims should be rechecked against the linked sources before procurement, migration, or production rollout.

Copyable starter templates

Use one root template for the shared policy: project purpose, package manager, install command, development command, test command, build command, formatting command, safe edit boundaries, files to avoid, review expectations, and known failure notes.

For React or Vue apps, name the frontend package path, generated build folders, UI test command, and screenshot or accessibility check. For Python services, name the virtual environment command, test runner, migration boundary, and formatting command. For monorepos, keep root AGENTS.md short and place nested AGENTS.md files only where commands or ownership really differ.

For teams, add one security section: no secrets in prompts, no production writes without approval, no migration edits without owner review, and no generated code merge without tests or human diff review.

Should you generate AGENTS.md automatically?

Use automation only to assemble repository facts you have verified: exact commands, scope, forbidden paths, and the definition of done. The browser builder on this page is deterministic and does not inspect your repository or ask a model to invent guidance. Replace every default, run each command, remove redundant rules, and review the result before committing it.

A 2026 AGENTS.md evaluation preprint found that context files generally increased steps and inference cost without a statistically significant accuracy gain; developer-written files performed better than model-generated files in its comparison. A separate repository-mining preprint found configuration smells in 91 of 100 sampled repositories, including redundant lint rules and conflicting instructions. These are bounded studies, not universal laws, but they support keeping the starter concise and repo-specific.

Root vs nested AGENTS.md inheritance

Put repo-wide rules in the root AGENTS.md: install commands, global test commands, style rules, forbidden files, and review expectations. Put package-specific exceptions in a nested AGENTS.md, such as apps/web/AGENTS.md or packages/api/AGENTS.md, when that folder has different commands or risk boundaries.

Nested files should override only what changes. If the web app uses npm test and the API uses pytest, write that difference in the nested file instead of duplicating the whole root policy.

What every template must say

Every useful AGENTS.md should declare the test command, completion standard, allowed edit scope, forbidden files, generated folders, secret policy, and review expectation. These are the controls an agent can actually follow during a coding task.

Avoid vague rules like 'write clean code' unless the repo has a command or reviewer habit that checks the rule. Replace vague style advice with concrete commands, file paths, and approval boundaries.

What not to put in it

Do not paste secrets, access tokens, private customer data, or vague motivational rules. Avoid rules like 'write clean code' unless you explain what command or reviewer checks that rule.

Do not copy the same paragraph into every instruction file. Keep one source of truth and link tool-specific files back to it when possible.

Recommended play

Create a root AGENTS.md first, then add nested files only when a folder has different commands or ownership.
Keep every command copy-pasteable from a clean checkout.
Review AGENTS.md whenever CI, package managers, test commands, or security boundaries change.

AGENTS.md template blocks

Use these blocks as a practical template. Delete anything that is not true for the repo.

Area	What to write	Example	Keep it out when
Repo purpose	One sentence on what the project does	Next.js marketing site with a FastAPI admin backend	The repo is private and purpose details reveal sensitive plans
Commands	Install, dev, test, build, lint	npm run test; npm run build	The command is stale or only works on one developer machine
Safe boundaries	Allowed files, risky files, generated files	Do not edit migrations without approval	The team has not agreed on ownership yet
Review rule	How to prove the change is done	Show changed files, test result, and known risk	The rule is only style preference and not checked anywhere
Nested scope	Package-specific commands and boundaries	apps/web/AGENTS.md uses npm test; packages/api/AGENTS.md uses pytest	The folder does not actually differ from the root policy

Execution steps

Write the root file

Start with the project purpose, commands, safe boundaries, and review expectations.

Test every command

Run the listed commands once so the agent does not inherit broken instructions.

Add folder-specific notes only when needed

Use nested AGENTS.md files for monorepo packages, generated folders, or high-risk areas with different rules.

Add a drift owner

Name the person or team that updates instructions when CI, package managers, or release flow changes.

Common pitfalls

Writing a policy novel

Keep the file practical: commands, boundaries, and review steps beat long philosophy.

Listing commands nobody runs

Only include commands that work from a clean checkout or explain the required setup.

Hiding secrets in instructions

Describe environment variable names and access boundaries, never credential values.

Implementation checklist

Explain what the repo does in one sentence.
List install, test, build, and lint commands.
Name files or folders the agent should not edit without approval.
Explain how to verify a completed task.
Keep secrets and customer data out of the file.
Review the file when CI or package managers change.

Questions this guide answers

What should an AGENTS.md template include?

A useful AGENTS.md template gives Codex copyable repo instructions: project purpose, install command, test command, safe edit boundaries, forbidden files, and review expectations. Start with one root file, then add nested AGENTS.md files only for packages that need different commands, ownership, or safety boundaries.

When should you add a nested AGENTS.md file?

Add a nested AGENTS.md only when a folder genuinely needs different guidance, such as package-specific test commands, generated-file boundaries, ownership rules, or risk limits. Keep the root file for shared repo policy and the nested file for local exceptions.

Who is this AGENTS.md template for?

Developers setting up Codex-compatible agents, team leads standardizing repo instructions, and maintainers cleaning stale agent rules across Node.js, Python, and monorepo layouts.

Should you generate AGENTS.md automatically?

Use a generator only as a starter for repository facts you verify yourself: exact setup and test commands, scope, restricted paths, and completion rules. Do not let a model invent a long repository overview. Run every generated command, delete redundant guidance, and audit the final file before committing it.

AGENTS.md Template for Codex and Monorepos

Quick Answer

Build a concise AGENTS.md starter

AGENTS.md template previews

Repository AGENTS.md

Node.js AGENTS.md

Python AGENTS.md

Monorepo AGENTS.md

How AGENTS.md loading priority works

Evidence reviewed

Best next step

Methodology and disclosure

Copyable starter templates

Should you generate AGENTS.md automatically?

Root vs nested AGENTS.md inheritance

What every template must say

What not to put in it

Recommended play

AGENTS.md template blocks

Execution steps

Write the root file

Test every command

Add folder-specific notes only when needed

Add a drift owner

Common pitfalls

Writing a policy novel

Listing commands nobody runs

Hiding secrets in instructions

Implementation checklist

Questions this guide answers

What should an AGENTS.md template include?

When should you add a nested AGENTS.md file?

Who is this AGENTS.md template for?

Should you generate AGENTS.md automatically?

Next guides

AGENTS.md examples for Node.js, Python, and monorepos

AGENTS.md vs CLAUDE.md comparison

Codex vs Claude Code

agent governance checklist

loop engineering for AI coding agents

Related evidence updates

GitHub Copilot SDK Reaches General Availability

OpenAI Expands Codex into Plugins, Sites, and Annotations