#AGENTS.md Project Instructions

AGENTS.md is an open standard shared by Codex, Cursor, Gemini CLI, and others. It injects persistent, version-controlled project rules before a task starts.

#Why AGENTS.md?

Problems with chat-only prompts:

• Every session repeats “run eslint” and “tests are pnpm test”
• Team rules never go through code review
• Agents mis-navigate large monorepos

AGENTS.md turns new-hire onboarding docs into default agent context.

#Discovery and merge rules

#Load order

1. Global ~/.codex/AGENTS.override.md or ~/.codex/AGENTS.md
2. Project from Git root → current working directory, at most one file per level:
   • AGENTS.override.md > AGENTS.md > custom fallback names
3. Merge: root first, subdirectories later → closer to CWD = higher priority

#Size limit

Default merged cap 32 KiB (project_doc_max_bytes). Overflow is truncated—by design, to keep rules concise.

#What to include (and avoid)

Good content:

• Build / test / lint commands (one copy-paste line each)
• Directory layout (“business logic in internal/, do not edit vendor/”)
• PR and commit conventions
• Security red lines (no secrets in commits, no git push --force to main)

Poor content:

• Full design docs (put them in docs/; link from AGENTS.md)
• Temporary task notes that change daily
• Long prose unrelated to code

#Example: root AGENTS.md

# AGENTS.md

## Repository overview
- Node 20 + pnpm monorepo
- App code in `apps/web`, shared libs in `packages/`

## Required commands
- Install: `pnpm install`
- Test: `pnpm test`
- Lint: `pnpm lint`

## Change principles
- Write tests before implementation (except pure error-handling fixes)
- Public API changes must update `packages/core/README.md`
- Do not edit `pnpm-lock.yaml` unless dependencies actually changed

#Nested directory override

In services/payments/AGENTS.override.md:

# services/payments/AGENTS.override.md

## Payments service
- Tests: `make test-payments`, not root `pnpm test`
- API key rotation requires #security channel approval first

Launch from that directory:

codex --cd services/payments "Fix idempotency bug in refund endpoint"

Loads: global → root AGENTS.md → payments override.

#Global personal preferences

Example ~/.codex/AGENTS.md:

# ~/.codex/AGENTS.md

## Communication
- Share a plan before executing
- List modified files when done

## Tool preferences
- Default package manager: pnpm
- Python projects: prefer uv

#Custom fallback filenames

If the team already uses TEAM_GUIDE.md:

# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

#Feedback loop (important)

When Codex repeats the same mistake:

1. Correct it in the conversation
2. Say explicitly: “Add this rule to AGENTS.md”
3. Merge via code review

On GitHub PRs you can delegate: @codex add this to AGENTS.md.

Pair with pre-commit, lint, and typecheck to turn soft rules into hard checks.

#Verify what loaded

codex --ask-for-approval never "List instruction sources currently loaded and summarize them"

Or enable logging:

codex -c log_dir=./.codex-log
# Inspect .codex-log/codex-tui.log

#Troubleshooting

#Next steps

• Agent Skills: reusable SOPs
• Architecture & Runtime: instruction chain in the agent loop