AGENTS.md & CLAUDE.md

Why Agent Context Files Matter: From Chaos to Consistency

Imagine you've just joined a new engineering team. On day one, a senior developer hands you a stack of sticky notes instead of a README. "This is how we work," they say. "Just... remember it." That's essentially what most teams are doing today with AI agents — and free flashcards are embedded throughout this lesson to help you lock in the core ideas. The problem isn't that developers are careless. It's that nobody handed them a better model. That better model has a name: agent context files, most commonly seen as AGENTS.md and CLAUDE.md. Understanding why these files exist — and why they matter deeply — is the foundation of everything else in this lesson.

The Core Problem: Agents Don't Remember You

Every time you start a new session with an AI coding agent, you're talking to a system with no memory of yesterday. The brilliant conversation you had last Tuesday where you carefully explained your team's testing philosophy, your monorepo structure, your code review conventions, and your security constraints? Gone. You're starting from zero.

This is called the stateless session problem, and it's a fundamental characteristic of how large language model-based agents work today. Each session is, by default, an amnesiac fresh start. The agent is capable and intelligent, but it has no persistent context about your project unless you provide it.

The result is context bootstrapping — the repetitive, error-prone process of re-explaining your project's ground rules every time you open a new chat. Developers handle this in different ways:

🧠 Some paste long system prompts they keep in a notes file 📚 Some re-explain conventions mid-conversation when the agent gets something wrong 🔧 Some just accept inconsistent output and fix it manually 🎯 Some give up on using agents for anything nuanced

None of these are solutions. They're coping mechanisms.

💡 Mental Model: Think of an AI agent session like hiring a brilliant contractor who shows up with no memory of the last job. Every morning, you can either spend an hour briefing them from scratch — or you can hand them a well-written project spec on day one and let the spec do the talking.

How Ad-Hoc Prompting Breaks Down at Scale

When you're a solo developer experimenting with an AI agent, ad-hoc prompting in a chat interface is manageable, if tedious. But watch what happens when you zoom out.

Your team now has five developers. Each one interacts with the AI agent slightly differently. Alice always tells the agent to write tests in Pytest with fixtures. Bob doesn't mention tests at all. Carlos pastes in a custom prompt he wrote six months ago that references an old folder structure. The agent, being a highly capable pattern-matcher, produces wildly different outputs for each of them — sometimes correct, sometimes subtly wrong in ways that only surface in code review.

Now add time. Six months from now, new team members join. The conventions in Carol's private prompt file aren't documented anywhere. The agent gives new developers guidance that contradicts how the codebase actually works. Onboarding slows down. Trust in the AI tooling erodes.

🎯 Key Principle: Agent behavior is a team contract. Contracts belong in shared, versioned artifacts — not in individual chat windows.

This is the breakdown point for ad-hoc prompting: it doesn't compose, it doesn't version, it doesn't onboard, and it doesn't audit. It's the sticky-note stack all over again.

⚠️ Common Mistake — Mistake 1: Storing important agent instructions only in personal prompt libraries or local files. When that developer leaves or switches machines, the institutional knowledge walks out with them.

The Shift in Mental Model: Instructions Are Source Code

Here is the insight that changes everything: agent instructions should be treated as source code artifacts, not ephemeral chat messages.

Source code artifacts have properties that chat messages don't:

• ✅ They live in version control alongside the code they describe
• ✅ They are reviewed, approved, and merged through pull requests
• ✅ They are readable by every team member and every tool that checks out the repo
• ✅ They have a history — you can see who changed what, and why
• ✅ They are authoritative — there's one canonical version, not ten private copies

This is the foundational mental model behind AGENTS.md and CLAUDE.md. Instead of telling an agent how your project works every session, you write that knowledge down once, commit it to your repository, and let the agent read it automatically.

❌ Wrong thinking: "I'll just tell the AI what I need each time. It only takes a minute."

✅ Correct thinking: "My project's conventions are a persistent asset. I'll encode them once, version them, and let every session — and every teammate — benefit from that single source of truth."

This mental shift is analogous to the evolution from manual server configuration to infrastructure-as-code. You could SSH into a server and configure it by hand every time. But once you've written a Terraform file or an Ansible playbook, you've turned a human ritual into a reproducible, auditable process. Agent context files do the same thing for AI-assisted development workflows.

AGENTS.md and CLAUDE.md: The Conventions Explained

Two filenames have emerged as the de facto standards for encoding agent context, each associated with a specific tooling ecosystem:

AGENTS.md is the convention used by OpenAI's Codex and the broader family of tools built around it, including many open-source agent frameworks. When an agent in this ecosystem begins a session in a repository, it automatically reads AGENTS.md files to understand the project's rules, conventions, and behavioral constraints.

CLAUDE.md is the convention used by Anthropic's Claude and its associated tooling, particularly the Claude Code CLI and related developer workflows. Claude will automatically discover and incorporate CLAUDE.md when it's present in the working directory or parent directories.

🤔 Did you know? Both AGENTS.md and CLAUDE.md support hierarchical placement — you can have a root-level file that applies to the entire repo, and subdirectory-level files that add or override context for specific modules. This makes them powerful tools for monorepos where different packages have different conventions.

Here's a minimal but functional example of what a CLAUDE.md file might look like for a Python web service project:

## Claude Context for payments-service

### Project Overview
This is a FastAPI-based microservice handling payment processing.
It must comply with PCI-DSS Level 1 requirements at all times.

### Development Conventions
- Python 3.11+ only. Never suggest features from earlier versions.
- All database access goes through the repository pattern in `src/repositories/`.
- Never write raw SQL. Use SQLAlchemy ORM exclusively.
- Test framework: pytest with the fixtures defined in `tests/conftest.py`.

### Security Rules
- Never log payment card data, CVVs, or full PANs under any circumstances.
- All external API calls must go through `src/clients/` — never use `requests` directly.
- Secrets are loaded via environment variables only. No hardcoded credentials.

### Running the Project
```bash
## Install dependencies
uv sync

## Run tests
pytest tests/ -v

## Start dev server
uvicorn src.main:app --reload

Notice what this file does: it gives the agent a mental map of the project's architecture, a rulebook for its conventions, and hard constraints around security-sensitive behavior. An agent reading this file before starting work is dramatically better equipped than one starting cold.

Here's what an AGENTS.md file might look like for a TypeScript monorepo:

```markdown
## Agent Context — acme-platform monorepo

### Repo Structure
- `packages/api` — Express REST API (Node 20)
- `packages/web` — Next.js 14 frontend
- `packages/shared` — Shared types and utilities (consumed by both above)

### Code Style
- TypeScript strict mode is enabled everywhere. No `any` types.
- ESLint and Prettier run on pre-commit hooks. Always produce lint-clean code.
- Imports: use path aliases defined in each package's `tsconfig.json`.

### Testing
- Unit tests: Vitest for all packages.
- E2E tests: Playwright, located in `packages/web/e2e/`.
- Coverage threshold: 80% line coverage enforced in CI.

### PR Conventions
- Branch names: `feat/`, `fix/`, `chore/` prefixes.
- Commits follow Conventional Commits specification.
- Every PR must include or update relevant tests.

This file acts like an always-present senior engineer whispering context to the agent at the start of every session.

The Business Case: Repeatability, Onboarding, and Auditability

Let's ground this in outcomes that engineering leaders and teams genuinely care about.

Repeatability means that when your CI pipeline runs an AI agent to generate boilerplate, review code, or update documentation, it produces consistent output every time — not output that varies based on whoever happened to write the best prompt that day. Agent context files make AI behavior a deterministic function of your project's current state, not a lottery.

Onboarding speed is dramatically improved when a new developer can read a single file and understand not just how to work with the codebase, but how to work with the AI agent on that codebase. The agent context file becomes a living orientation document.

Auditability is increasingly important as AI-assisted development enters regulated industries. If an auditor asks "how did you ensure the AI didn't suggest insecure patterns?" you can point to a versioned CLAUDE.md that explicitly encodes the security rules — and to the git history showing when those rules were added and by whom.

📋 Quick Reference Card:

	📌 Without Context Files	✅ With Context Files
🔧 Session Start	Manual re-briefing required	Agent reads file automatically
👥 Team Consistency	Varies by individual	Enforced by shared artifact
📚 Onboarding	Tribal knowledge transfer	Self-documenting via file
🔒 Security Rules	Easy to forget, inconsistent	Encoded once, always present
🎯 Auditability	"We told the AI verbally"	Versioned, reviewable history
🚀 CI/CD Integration	Fragile, prompt-dependent	Reproducible, file-driven

💡 Real-World Example: A fintech team adopted CLAUDE.md after noticing that their AI agent kept suggesting console.log statements in code paths that handled user financial data — a compliance violation. They added a single line to their context file: "Never log objects that may contain user financial data. Use structured logging with explicit field allowlists." The problem stopped immediately, for every developer, in every session, forever.

🧠 Mnemonic: Think VCAR — Versioned, Consistent, Auditable, Repeatable. These are the four properties that agent context files give you, and the four properties that ad-hoc prompting can never reliably deliver.

The sections that follow will take you from understanding why these files matter to knowing exactly how to write them well — what to put in them, how to structure them for complex projects, and how to avoid the pitfalls that trip up even experienced teams. But everything builds on this foundation: agent instructions are code. They belong in your repository. And once you've made that shift, the quality and consistency of your AI-assisted development workflow will never look the same.

Anatomy of an Agent Context File: Structure, Scope, and Semantics

Understanding what goes into an agent context file is only half the battle. The other half is understanding how it gets structured, where it lives, and how an AI agent actually reads and interprets it. A file filled with good intentions but poor organization is nearly as useless as no file at all. This section gives you the blueprint.

The Five Core Content Categories

A well-designed agent context file isn't a free-form dump of notes. It organizes information into distinct categories, each serving a different cognitive function for the agent. Think of it like briefing a new contractor: you tell them what the project is, how the team works, what the codebase looks like, what tools they're allowed to use, and what workflows they must follow.

🎯 Key Principle: Every piece of information in your context file should answer one of five questions — What is this project? How is it structured? How do we write code here? What tools and commands matter? What processes must be followed?

Here's how those five categories map to concrete file sections:

Category	Purpose	Example Content
🎯 Project Overview	Orients the agent to the domain and goals	App purpose, tech stack, deployment targets
🏗️ Architecture Decisions	Explains non-obvious structural choices	Monorepo layout, module boundaries, DB schema philosophy
📐 Coding Conventions	Defines style and quality expectations	Naming patterns, file structure, test coverage rules
🔧 Tool Usage Constraints	Controls which tools the agent may use	Allowed CLI commands, forbidden packages, env variables
🔄 Workflow Rules	Governs how tasks get executed	Branch naming, PR requirements, migration procedures

These categories aren't just organizational niceties. They correspond to distinct reasoning modes the agent applies at different moments: understanding context, generating code, selecting tools, and sequencing actions.

---

File Placement and Hierarchical Scope

One of the most powerful and underused features of agent context files is hierarchical scope. You don't have to put everything in one file. You can — and often should — distribute context across multiple files placed at different levels of the directory tree.

my-project/
├── AGENTS.md              ← root-level: applies to entire project
├── apps/
│   ├── api/
│   │   ├── AGENTS.md      ← subtree-level: applies only to apps/api/
│   │   └── src/
│   └── web/
│       ├── AGENTS.md      ← subtree-level: applies only to apps/web/
│       └── src/
└── packages/
    └── shared/
        └── AGENTS.md      ← subtree-level: applies only to packages/shared/

Root-level files establish project-wide ground rules. They're the non-negotiables — the conventions and constraints that apply everywhere regardless of which part of the codebase the agent is working in. Subdirectory-level files narrow or extend those rules for a specific domain.

🎯 Key Principle: Subdirectory context files add specificity; they don't replace root rules. Agents merge context from all applicable files, walking from the root down to the file being edited.

When an agent is working on apps/api/src/routes/users.ts, it reads:

1. /AGENTS.md (project-wide rules)
2. /apps/api/AGENTS.md (API-specific rules)

If there's a conflict — say, the root file says "use 2-space indentation" but the API file says "use 4-space indentation" — the more specific (deeper) file wins. This mirrors how CSS specificity works, which is a useful mental model.

🧠 Mnemonic: Think "deeper wins, root persists" — closer to the file beats further away, but deeper rules only override on explicit conflicts, not on topics the deeper file doesn't mention.

⚠️ Common Mistake: Teams write contradictory instructions at different levels without realizing it. If your root file says "never use console.log" and your web app's subdirectory file says "use console.log for debugging during development," the agent will apply the subdirectory rule inside that folder — which may surprise developers who assumed the root rule was absolute. Make root-level prohibitions explicit about their absoluteness if needed.

---

How Agents Consume These Files

Understanding the mechanics of how an agent reads your context file prevents a lot of confusion. Codex (OpenAI's coding agent) reads AGENTS.md at session initialization, before any task prompt is processed. Claude reads CLAUDE.md similarly — the file contents are injected into the system prompt context at the start of a session.

This has one critical implication: the agent doesn't re-read the file mid-task. The context is loaded once and held in the working context window. Instructions that require dynamic re-evaluation during a task (like "check if the database is running before running migrations") need to be written as imperative steps the agent follows sequentially, not as ambient reminders.

💡 Mental Model: Imagine handing a contractor a printed briefing document at 9am. They read it, internalize it, and then work all day. They're not consulting it every five minutes. Your AGENTS.md is that briefing document — it needs to be self-contained and front-loaded with the most critical guidance.

Another important nuance: agents prioritize explicit, specific instructions over general ones, and later instructions over earlier ones when both are applicable. This means you should put your most important rules early in the file to establish framing, but put specific override rules close to the relevant section where they'll be encountered in the correct context.

🤔 Did you know? When Claude encounters a CLAUDE.md file in a project opened via Claude Code, it treats the file's contents with elevated trust relative to conversational input — meaning explicit project-level instructions tend to override ad-hoc user requests that conflict with them. This makes your context file a policy document, not just a suggestion list.

---

Writing Instructions That Agents Actually Follow

This is where most teams go wrong. There's a massive difference between instructions an agent can act on and instructions that read well to humans but dissolve into vagueness when an AI tries to execute them.

❌ Wrong thinking: "Write clean, idiomatic TypeScript that follows best practices and is easy to maintain."

✅ Correct thinking: "All TypeScript must be strictly typed with no any types. Use named exports, never default exports. Every exported function must have a JSDoc comment describing its parameters and return value."

The first example sounds professional but provides no actionable guidance — "best practices" and "clean" are undefined relative to any specific codebase. The second example gives the agent three concrete, verifiable rules.

Imperative language is your tool here. Use command verbs: use, avoid, always, never, run, check, prefer. Avoid hedged language like try to, generally, when possible — agents interpret these as optional and will de-prioritize them when making tradeoffs.

---

Annotated Example: A Full-Stack TypeScript Project

Here's a well-structured AGENTS.md for a full-stack TypeScript monorepo. Each section is annotated with the rationale for its content and phrasing choices.

## Project: Meridian — AGENTS.md

### Project Overview
Meridian is a B2B SaaS invoicing platform. The backend is a REST API built with
Fastify and Prisma on Node.js 20. The frontend is a React 18 SPA using Vite.
Both apps live in this monorepo under `apps/`. Shared utilities are in `packages/`.
Deployment target is AWS (ECS for API, S3/CloudFront for frontend).

## WHY THIS MATTERS: Orients the agent to the domain so it doesn't suggest
## solutions appropriate for a different type of project (e.g., a CLI tool).

### Architecture Decisions
- The API and frontend communicate ONLY via the REST API. Never add direct
  DB calls in frontend code.
- Prisma is the ONLY database access layer. Never use raw SQL or any other ORM.
- All inter-package imports must go through the package's public index.ts.
  Never import from internal subpaths like `packages/shared/src/internal/utils`.

## WHY THIS MATTERS: These are non-obvious choices that an agent would otherwise
## violate by applying generic "best practices."

### Coding Conventions
- Language: TypeScript strict mode everywhere. No `any`, no `ts-ignore`.
- Exports: Named exports only. No default exports in any file.
- Naming: React components use PascalCase. All other functions use camelCase.
  Database models use PascalCase. Database columns use snake_case.
- Tests: Every new function in `packages/` must have a corresponding test
  in the `__tests__` directory adjacent to the source file. Use Vitest.
- Error handling: Never swallow errors silently. All caught errors must
  either be re-thrown or logged via the `logger` utility from `packages/logger`.

### Tool Usage Constraints
- Package manager: pnpm only. Never use npm or yarn.
- Install command: `pnpm install` from the monorepo root.
- Running tests: `pnpm test` from root runs all tests. `pnpm test --filter=api`
  runs only API tests.
- Database migrations: Run `pnpm prisma migrate dev` from `apps/api/`. Never
  run migrations in production manually — that is handled by CI/CD.
- Forbidden packages: Never install `moment`. Use `date-fns` instead.

### Workflow Rules
- Before editing any database schema in `schema.prisma`, summarize the
  planned change and ask for confirmation.
- After modifying any file in `packages/shared/`, run
  `pnpm build --filter=shared` to verify the build succeeds.
- Do not commit changes to `.env` files under any circumstances.

Now let's look at what a subdirectory-level file might look like for just the API package, adding specificity without duplicating root-level rules:

## apps/api — AGENTS.md

### API-Specific Conventions
- All route handlers live in `src/routes/`. Each resource gets its own file
  (e.g., `invoices.ts`, `users.ts`). Never put multiple resources in one file.
- Input validation uses Fastify's built-in JSON schema validation. Never use
  Zod or Yup for request validation at the route level.
- Authentication middleware is in `src/middleware/auth.ts`. All routes except
  `/health` and `/auth/*` must apply this middleware.
- HTTP status codes: Use 422 for validation errors, 409 for conflicts,
  404 for missing resources. Never use 400 as a catch-all.

### Database Rules (API only)
- All Prisma queries must be wrapped in a service function in `src/services/`.
  Route handlers call service functions — they never call Prisma directly.
- Long-running queries (>100ms estimated) must use Prisma's `$transaction` API.

This subdirectory file adds API-specific constraints — HTTP status codes, route structure, validation library choices — that would be irrelevant noise in the root file. The root file handles the universal concerns; the subdirectory file handles the domain-specific ones.

💡 Pro Tip: Use a comment syntax (like # WHY THIS MATTERS:) to annotate non-obvious rules with rationale. The agent doesn't need this explanation to follow the rule, but your teammates do — and it helps during code review when someone asks "why does our AGENTS.md forbid default exports?"

---

The Semantics of Scope: What Agents Actually Prioritize

Beyond file hierarchy, there's a semantic hierarchy within a single file. Not all instructions carry equal weight in an agent's reasoning. Rules tied to concrete, verifiable outcomes ("run pnpm test and confirm zero failures before finishing") are acted on more reliably than rules tied to subjective quality ("make sure the code is readable").

📋 Quick Reference Card: Instruction Strength

💪 Stronger	🤷 Weaker
🎯 "Never use any types"	❓ "Avoid type unsafety"
🔧 "Run pnpm lint before finishing"	❓ "Make sure the code passes lint"
🔒 "Use named exports only"	❓ "Prefer named exports"
📐 "Files must not exceed 200 lines"	❓ "Keep files reasonably short"

The left column gives agents a binary pass/fail test they can apply mechanically. The right column requires judgment about what "unsafe" or "reasonable" means — and agents will apply their own defaults, which may not match yours.

This principle — make the success condition explicit and verifiable — is the single most impactful thing you can do to improve agent instruction quality. Every rule in your context file should have a clear answer to "how would I know if this rule was violated?"

With this anatomy in place, you now have the foundation to understand not just what goes in a context file, but why it's structured the way it is. The next section puts these principles into practice with patterns drawn from real project types.

Practical Patterns: Writing Context Files for Real Projects

Understanding the theory behind agent context files is one thing — knowing how to write them for the messy, real-world projects you actually work on is another. This section moves from concept to craft, walking through four essential patterns that cover the most common situations teams face. By the end, you'll have concrete templates and mental models you can apply immediately.

Pattern 1 — Encoding Tech Stack and Toolchain Rules

One of the most immediately valuable things you can encode in an AGENTS.md file is your project's toolchain contract: the specific commands, package managers, and scripts an agent must use rather than guess at. Agents are trained on millions of projects and will default to common conventions — but your project may not follow common conventions, and even when it does, ambiguity wastes cycles and introduces errors.

🎯 Key Principle: Every time an agent has to infer which test runner or package manager to use, it's a moment where it might be wrong. Remove the inference entirely.

Consider a TypeScript monorepo that uses pnpm instead of npm, vitest instead of Jest, and biome instead of ESLint. Without explicit guidance, an agent might run npm install, fail silently, and spend three tool calls diagnosing a lockfile conflict that shouldn't have happened. With a clear toolchain section, that problem never occurs:

### Toolchain

#### Package Management
- ALWAYS use `pnpm` — never `npm` or `yarn`
- Install dependencies: `pnpm install`
- Add a dependency: `pnpm add <package>`
- Add a dev dependency: `pnpm add -D <package>`

#### Testing
- Test runner: `vitest`
- Run all tests: `pnpm test`
- Run tests for a single file: `pnpm vitest run src/path/to/file.test.ts`
- Watch mode: `pnpm vitest`

#### Linting & Formatting
- Linter/formatter: `biome` (NOT eslint, NOT prettier)
- Check: `pnpm biome check .`
- Fix automatically: `pnpm biome check --apply .`

#### Build
- Production build: `pnpm build`
- Type check only: `pnpm tsc --noEmit`

This block is unambiguous, scannable, and directly executable. The agent doesn't need to read package.json to discover script names — the context file tells it directly. Notice the use of negative constraints ("NOT eslint, NOT prettier") alongside positive ones. Agents benefit from knowing not just what to do, but what not to do, especially when the wrong tool might silently succeed while producing incorrect output.

💡 Pro Tip: Keep command strings copy-pasteable and exact. If the real command is pnpm run test:unit -- --reporter=verbose, write that exactly. Paraphrasing introduces drift.

Pattern 2 — Defining Task Boundaries

A task boundary declaration tells an agent which parts of the codebase are in-scope, out-of-scope, or entirely off-limits for modification. This is especially important in projects with generated files, infrastructure-as-code, or sensitive configurations that should only be touched through deliberate human action.

### File and Directory Boundaries

#### DO NOT MODIFY (read-only for agents)
- `dist/` — generated build output; never edit directly
- `generated/` — GraphQL types auto-generated by `pnpm codegen`
- `.env.production` — production secrets; treat as read-only
- `infrastructure/terraform/` — infrastructure changes require human review
- `CHANGELOG.md` — only updated via `pnpm release` (see Workflow section)

#### RESTRICTED (modify only when explicitly instructed)
- `src/db/migrations/` — new migration files require explicit task instruction
- `package.json` — dependency changes must be confirmed before execution

#### SAFE TO MODIFY
- `src/` (excluding subdirectories listed above)
- `tests/`
- `docs/`
- Configuration files: `biome.json`, `vitest.config.ts`, `tsconfig.json`

⚠️ Common Mistake: Teams often list what agents can do but forget to enumerate what they cannot. Agents are biased toward being helpful and completing tasks — without explicit constraints, they may "helpfully" regenerate a file that was supposed to stay untouched.

The three-tier structure above (DO NOT MODIFY / RESTRICTED / SAFE) gives agents a clear mental hierarchy. It also serves as documentation for human developers onboarding to the project — a dual-use benefit that makes the investment in writing these files even more worthwhile.

Pattern 3 — Workflow Choreography

Workflow choreography is the practice of encoding multi-step procedures as explicit, ordered instructions rather than leaving agents to construct the sequence themselves. This is where context files move from passive reference material to active behavioral scripts.

Consider a team that requires a specific release flow: tests must pass, the changelog must be updated, and a version bump must happen before any commit reaches the main branch. Without encoding this, an agent asked to "fix this bug and commit" might skip all three steps.

### Workflows

#### Before Every Commit
Execute these steps IN ORDER. Do not skip steps, even if they seem unnecessary.

1. Run the full test suite: `pnpm test`
   - If any tests fail, fix them before proceeding
   - Do NOT commit with failing tests under any circumstances
2. Run the linter with auto-fix: `pnpm biome check --apply .`
3. Run the type checker: `pnpm tsc --noEmit`
   - Resolve all type errors before proceeding
4. Stage changes: `git add -p` (review hunks interactively) OR `git add <specific files>`
5. Write a conventional commit message: `<type>(<scope>): <description>`
   - Types: feat, fix, docs, refactor, test, chore
   - Example: `fix(auth): handle expired JWT tokens gracefully`

#### When Adding a New Feature
1. Create a branch: `git checkout -b feat/<short-description>`
2. Implement the feature with accompanying tests
3. Update `docs/api.md` if public API surface changes
4. Follow the pre-commit workflow above
5. Do NOT merge to main — open a PR and stop

#### When Updating Dependencies
1. Make the change: `pnpm add <package>` or `pnpm update <package>`
2. Run `pnpm test` — dependency changes can break things subtly
3. Check for peer dependency warnings in the output
4. Commit both `package.json` AND `pnpm-lock.yaml`

The critical insight here is ordering with rationale. Humans understand why you run tests before committing — agents benefit from the explicit sequence and, where helpful, a brief note on why. The instruction "Do NOT commit with failing tests under any circumstances" removes any ambiguity about what to do when a step fails.

🤔 Did you know? Agents that encounter ambiguous multi-step tasks tend to optimistically assume earlier steps succeeded. Encoding explicit checkpoints ("if any tests fail, fix them before proceeding") directly counteracts this tendency.

Pattern 4 — Persona and Communication Style for CLAUDE.md

While AGENTS.md primarily governs what an agent does, CLAUDE.md (Claude's project-level memory file) is also an excellent place to encode how an agent communicates with your team. This matters more than it might seem: a team of senior engineers working at high velocity doesn't want verbose pedagogical explanations on every response, while a team of juniors learning a new stack might need the opposite.

Communication style directives belong in a dedicated section and should be specific rather than vague:

### Communication Style

#### Response Format
- Default to concise responses — this team is senior-level, skip basic explanations
- Use bullet points for lists of changes or steps; use prose for explanations of *why*
- When showing code changes, always use unified diff format rather than full file rewrites
  unless the full file is <50 lines
- For multi-file changes, summarize the overall change first, then show files

#### Verbosity Settings
- Code review feedback: detailed, with line-level comments and rationale
- Bug fixes: brief summary of root cause + fix, no tutorial-style explanation
- Architecture discussions: thorough, consider tradeoffs explicitly
- Routine tasks (renaming, formatting): one-line confirmation only

#### Output Expectations
- Always include a TL;DR at the top of responses longer than ~200 words
- When uncertain, say so explicitly rather than hedging throughout the response
- Prefer showing code over describing code

💡 Real-World Example: A platform team at a mid-sized SaaS company added a ## Communication Style section after noticing that their agent was writing multi-paragraph explanations for simple bash script fixes. After encoding "this team is senior-level — skip foundational explanations," their average response length for routine tasks dropped by roughly 60%, making the agent feel dramatically faster to work with.

Monorepo Strategy: Nested Context Files

Monorepos present a unique challenge: different services or packages within the same repository may have radically different tech stacks, testing approaches, and ownership rules. The solution is hierarchical context composition — a root-level AGENTS.md that establishes global rules, overridden by nested AGENTS.md files scoped to specific packages or services.

Here's how the structure looks in practice:

my-monorepo/
├── AGENTS.md                    ← Global rules (all agents, all packages)
├── packages/
│   ├── shared-ui/
│   │   ├── AGENTS.md            ← UI-specific overrides
│   │   └── src/
│   ├── api-gateway/
│   │   ├── AGENTS.md            ← Backend/security overrides
│   │   └── src/
│   └── data-pipeline/
│       ├── AGENTS.md            ← Data engineering overrides
│       └── src/
└── infrastructure/
    └── AGENTS.md                ← Infrastructure: most restrictive rules

The root AGENTS.md establishes the baseline that applies everywhere: the package manager, the global git workflow, the commit message convention, and any company-wide security rules.

A nested AGENTS.md in packages/api-gateway/ might look like this:

## AGENTS.md — api-gateway

<!-- Extends root AGENTS.md. Rules here override root rules for this package only. -->

### Overrides

#### Testing
- Test runner: `jest` (NOT vitest — this package predates the migration)
- Run tests: `pnpm --filter api-gateway test`
- Integration tests require a running DB: `docker-compose up -d db` first

#### Security Constraints
- NEVER log request bodies — they may contain PII or credentials
- Authentication middleware lives in `src/middleware/auth.ts` — treat as high-risk
  and flag any changes to this file for human review before committing
- Do not add new environment variables without updating `docs/env-vars.md`

#### File Boundaries (additive to root)
- `src/generated/openapi/` — generated from `openapi.yaml`, do not edit directly
- To regenerate: `pnpm --filter api-gateway generate:openapi`

Notice the comment at the top: <!-- Extends root AGENTS.md. Rules here override root rules for this package only. -->. This is a human-readable breadcrumb that makes the inheritance relationship explicit for both agents and developers. Some teams also add a ## Inherited Rules section that briefly summarizes which root rules apply, making the nested file self-documenting.

🎯 Key Principle: In a monorepo, the working directory at the time an agent is invoked determines which nested AGENTS.md takes precedence. This is why agents that support hierarchical context loading (like Claude with project-level memory) are particularly well-suited to monorepo workflows — the context adapts automatically as the agent's scope narrows.

⚠️ Common Mistake: Teams often put security-sensitive rules only in the root file, assuming they'll propagate. But if a nested file contains an override that contradicts a security rule, the nested rule may win. Critical security constraints — especially "never log X" or "never commit Y" — should be repeated in every nested file where they apply, not just at the root.

Rule Precedence in Nested AGENTS.md Files:

Root AGENTS.md
│  global rules, company-wide standards
│
├─► packages/api-gateway/AGENTS.md
│     overrides: test runner, security rules (additive)
│     inherits: package manager, commit conventions
│
└─► packages/shared-ui/AGENTS.md
      overrides: component testing patterns
      inherits: package manager, commit conventions

[More specific file wins on conflict]
[Security rules: repeat in nested files, don't assume inheritance]

Pulling It Together

These four patterns — toolchain contracts, task boundaries, workflow choreography, and communication style — aren't independent checklists. They compose. A well-written AGENTS.md for a real project will weave all four together: specifying commands, constraining scope, sequencing steps, and setting the tone for how the agent communicates about its work. When you layer in monorepo nesting, you get a system where context is precise at every level of the codebase, without requiring a single massive file that's impossible to maintain.

💡 Mental Model: Think of your context files as a contract between your team and the agent — one that gets versioned, reviewed, and refined just like any other piece of infrastructure. The time you invest in writing clear, concrete patterns directly translates into fewer hallucinated commands, fewer unwanted file modifications, and more predictable agent behavior across every session and every team member.

Common Pitfalls: What Goes Wrong and Why

Even well-intentioned teams that commit to maintaining agent context files eventually run into trouble. The mistakes are rarely dramatic — they accumulate quietly, like technical debt. One week the file is crisp and useful; three months later, it's a sprawling document full of contradictions, stale references, and forgotten context that makes the agent less reliable than if no file existed at all. Understanding the failure modes before you hit them is the fastest way to build context files that stay healthy over time.

---

Pitfall 1 — Instruction Bloat

Instruction bloat happens when teams treat AGENTS.md like a knowledge dump: every onboarding doc, architectural decision record, style preference, and edge case gets appended until the file balloons into hundreds of lines. The impulse is understandable — if the agent knows more, surely it performs better? In practice, the opposite happens.

Large language models process context files as part of their input window. When a file is dense with low-signal details, the high-value directives get diluted. The agent may technically "read" the rule about never using var in JavaScript, but that rule is now buried beneath forty lines about your internal Jira workflow, three paragraphs about the history of the codebase, and a list of every team member's timezone.

❌ Wrong thinking: "More instructions = better behavior." ✅ Correct thinking: "Fewer, clearer, higher-signal instructions = better behavior."

Here is what a bloated file looks like versus a pruned one:

## BEFORE: Bloated AGENTS.md (excerpt)

### About This Project
This project was started in Q2 2021 by the platform team after a
reorganization. The original stack used Flask but we migrated to FastAPI
in late 2022. The migration was led by Sarah and took about 4 months.
We still have some legacy Flask-style patterns in the /v1 routes.
The database was originally MySQL but we moved to PostgreSQL in 2023.
For historical context, the old MySQL schemas are archived in /docs/legacy.

### Code Style
We mostly use Black for formatting. Usually try to keep lines under 88 chars
if possible. We prefer type hints where it makes sense.

The paragraph above tells the agent things it cannot act on (project history, who led a migration) and uses hedging language (mostly, usually, where it makes sense) that produces inconsistent behavior. Compare it to a pruned version:

## AFTER: Pruned AGENTS.md (same coverage, higher signal)

### Code Conventions
- Formatter: Black (line length 88). Run before every commit.
- All functions and methods require type hints. No exceptions.
- All new routes go in /v2. Do not modify /v1 routes without explicit
  instruction — they are legacy and have downstream consumers.

### Stack
- Web framework: FastAPI (not Flask)
- Database: PostgreSQL 15 (not MySQL)

The pruned version is shorter, uses imperative language, and removes everything the agent can't operationalize. A useful pruning heuristic: if a line doesn't change how the agent writes, reviews, or tests code, cut it.

💡 Pro Tip: Set a soft line-count budget for your AGENTS.md — something like 150 lines for a mid-size project. When you approach the limit, you're forced to decide what's truly load-bearing before adding new content.

---

Pitfall 2 — Stale Context Drift

Stale context drift is what happens when the world moves on but AGENTS.md doesn't. A dependency gets upgraded and its API changes; a linting rule gets swapped out; a pattern that was idiomatic six months ago is now actively discouraged — but the context file still references the old way. The agent dutifully follows these stale instructions, generating code that breaks builds or introduces patterns your team is actively trying to retire.

The insidious part is that stale drift is invisible. The file still looks authoritative. There's no error message. The agent isn't confused — it's confidently wrong.

DRIFT TIMELINE (typical failure pattern)

Month 0    AGENTS.md created ──────────────────────────┐
                                                        │
Month 2    Lodash removed from project                  │  AGENTS.md still says
           (package.json updated)                       │  "prefer lodash utilities"
                                                        │
Month 4    ESLint config migrated to flat config        │  AGENTS.md still references
           (eslint.config.js replaces .eslintrc)        │  .eslintrc patterns
                                                        │
Month 6    Agent generates code using lodash + old      ◀┘
           ESLint syntax. Breaks in CI. Team confused.

The fix is structural: AGENTS.md must be treated as a dependency of the project's tooling decisions, not just documentation. The most effective teams enforce this with a PR check. Any pull request that touches package.json, CI configuration, framework versions, or architectural patterns should include a review step that asks: does this change invalidate anything in AGENTS.md?

💡 Real-World Example: A team migrating from Moment.js to date-fns updated every import in the codebase but forgot to update AGENTS.md, which still instructed the agent to use moment().format() for date formatting. For weeks afterward, the agent introduced Moment.js back into new files, which passed code review because reviewers assumed the agent was following the new standard. The drift wasn't caught until a bundle-size audit surfaced the dependency.

🎯 Key Principle: The freshness of AGENTS.md is a proxy for the reliability of your agent. Treat staleness as a bug, not a minor inconvenience.

---

Pitfall 3 — Ambiguous or Conflicting Rules

Rule ambiguity is perhaps the most common pitfall because it's the hardest to see from inside the team. When you write the file, every instruction makes sense to you — you have the context. But the agent (and new teammates) don't share that context, and vague qualifiers create wiggle room that produces inconsistent output.

The classic offenders are: usually, if possible, prefer, try to, when appropriate, and in most cases. Each of these turns a directive into a suggestion, and agents — like developers — will interpret suggestions differently depending on what else is in context.

Rule conflicts are a related problem. They often emerge when multiple people contribute to AGENTS.md over time without a unified review. Consider this example:

## CONFLICTING RULES — actual example from a real codebase

### Testing
- Always write unit tests for utility functions.
- Keep PRs small and focused; avoid scope creep.

### Refactoring
- When touching a file, improve test coverage if coverage is below 80%.

These three rules can directly conflict. A small PR that touches a utility function in a low-coverage file now has three competing directives pulling in different directions. The agent has no way to resolve the conflict deterministically — it will make a choice, and that choice will vary.

The fix is to make rules specific, imperative, and mutually exclusive where they overlap:

## FIXED: Unambiguous, non-conflicting rules

### Testing
- Every new utility function in /src/utils must have a corresponding
  unit test file. This is required, not optional.
- Do not add tests to existing files unless the PR's explicit goal
  is a test coverage improvement. Keep PR scope tight.

Now the scope boundaries are clear. New functions get tests. Existing functions don't get tests added unless that's the PR's stated purpose. No conflict, no ambiguity.

⚠️ Common Mistake: Mistake 3 ⚠️ Writing prefer X over Y without specifying when Y is acceptable. If Y is never acceptable, say "use X, never Y." If Y is sometimes acceptable, specify the exact conditions.

---

Pitfall 4 — Treating AGENTS.md as a Secrets File

This pitfall is the most dangerous, and it's entirely avoidable. AGENTS.md lives in version control. That means it's in your repository history, visible to every contributor, potentially mirrored to external services, and — if the repository is public or ever becomes public — readable by anyone.

Despite this, teams regularly commit sensitive information to these files:

🔧 Internal service URLs and staging endpoints 🔒 API keys and access tokens ("use this key for the dev environment") 📚 Internal architectural details that reveal attack surface 🎯 Credentials encoded as "example" values that are actually real

The temptation makes sense. The agent needs to know how to talk to your internal services. It needs environment-specific configuration. But the solution is indirection through environment variables and external secrets references, never inline values.

## ❌ WRONG — never do this

### Internal Services
- Internal metrics API: https://metrics-internal.corp.example.com/v2
- Auth token for dev: sk_dev_a3f9b2c1d4e5f6a7b8c9d0e1f2a3b4c5
- Staging DB connection: postgres://admin:hunter2@db.staging.internal/app


## ✅ CORRECT — use references, not values

### Internal Services
- Internal metrics API URL is in the METRICS_API_URL environment variable.
  In dev, this is set in .env.local (not committed). Ask a team member
  for the current value or check the team secrets manager (1Password vault:
  "Engineering / Dev Environment").
- Never hardcode service URLs or credentials in source files or context files.

The correct version tells the agent how to find the information without embedding the information itself. It also directs human readers to the right place to get values securely.

⚠️ Common Mistake: Mistake 4 ⚠️ Running git log or git blame on AGENTS.md after cleaning up a secrets leak — remember that version history preserves everything. If credentials were committed, rotate them immediately even after removing them from the file. Use git filter-repo to scrub history if necessary.

🤔 Did you know? Several major credential leaks in open-source projects have been traced to configuration and documentation files — not source code — because these files are often reviewed less carefully by security tooling. AGENTS.md files represent a new surface area in this threat landscape.

---

Pitfall 5 — No Ownership Model

The slowest-burning pitfall is also the most common: AGENTS.md has no owner. It gets created enthusiastically during a sprint planning session, receives a flurry of contributions in week one, and then silently rots. Nobody is responsible for keeping it accurate, so nobody does.

TYPICAL OWNERSHIP FAILURE PATTERN

  Week 1      Week 4      Month 3     Month 6     Month 9
    │           │           │           │           │
  Created    Active      Forgotten   Stale       Actively
  with care  updates     by most     by all      misleading
             by a few
             ──────────────────────────────────────────▶
                        Gradual decay, no single incident

The solution is to make ownership explicit and process-enforced rather than relying on goodwill. There are two practical mechanisms:

1. CODEOWNERS assignment. Add AGENTS.md (and CLAUDE.md) to your repository's CODEOWNERS file, assigning it to a specific team or individual. This requires a review from the owner on any PR that modifies the file.

## .github/CODEOWNERS

## Agent context files require platform team review
AGENTS.md        @your-org/platform-team
CLAUDE.md        @your-org/platform-team
**/AGENTS.md     @your-org/platform-team

2. Architectural PR checklist. Create a PR template that includes a checkbox specifically for agent context file review whenever architectural changes are involved:

## .github/pull_request_template.md

### Checklist
- [ ] Tests added or updated
- [ ] Documentation updated
- [ ] If this PR changes dependencies, tooling, or architectural patterns:
      have you reviewed AGENTS.md and CLAUDE.md for stale references?

This embeds the review habit directly into the workflow rather than relying on anyone remembering to do it separately.

💡 Pro Tip: Assign a quarterly "context file health check" as a recurring ticket in your project management tool. Fifteen minutes per quarter to read AGENTS.md against current reality catches drift before it compounds.

📋 Quick Reference Card: Pitfall Summary

	Pitfall	Root Cause	Key Fix
🧠	Instruction Bloat	Everything gets added, nothing removed	Line-count budget + pruning heuristic
🔧	Stale Context Drift	No link between code changes and doc updates	PR checklist for architectural changes
🎯	Ambiguous Rules	Vague qualifiers, no conflict resolution	Imperative language, explicit scope
🔒	Secrets in Context Files	Convenience over security hygiene	Indirection via env vars and secrets managers
📚	No Ownership Model	Diffuse responsibility = no responsibility	CODEOWNERS + recurring health check

These five pitfalls share a common thread: they all stem from treating AGENTS.md as a document rather than as operational infrastructure. Documentation tolerates neglect and ambiguity. Infrastructure does not. When you start holding your context files to the same standards you hold your CI configuration — versioned, reviewed, owned, and accurate — the pitfalls become much easier to avoid.

Key Takeaways and Team Adoption Checklist

You started this lesson facing a familiar frustration: two developers, the same AI agent, wildly different results. By now you understand why that happens and, more importantly, how to fix it permanently. Agent context files — whether named AGENTS.md, CLAUDE.md, or scoped per-subdirectory — are the mechanism that transforms an agent from an unpredictable collaborator into a reliable team member with documented, reviewable, and evolvable behavior.

This final section distills everything into principles you can act on today, a checklist you can run against any existing project, and a clear view of where this practice fits inside the broader discipline of context engineering.

---

Core Principle Recap: The Contract Metaphor

🎯 Key Principle: An agent context file is not configuration — it is a contract. It encodes the agreement between your team's intentions and the agent's runtime behavior. Like any good contract, it must be explicit, maintained, and jointly understood.

This framing matters because it shifts how teams treat the file. Configuration can drift and be patched silently. Contracts require deliberate amendment. When you think of AGENTS.md as a contract, three behaviors follow naturally:

• 📝 Changes go through review. A pull request that modifies AGENTS.md is as consequential as one that modifies a core library.
• 🔍 Ambiguity is a defect. If a clause could be interpreted two ways, it will be — by different agents, on different days. Clarify it.
• 📅 Expiry is expected. Projects evolve. A context file written at project inception should be audited at every major milestone.

🧠 Mnemonic: Think CARE — Context files must be Clear, Attributable, Reviewable, and Evolvable.

---

The Versioning Advantage in Practice

Storing agent context files in your repository's version control gives you capabilities that no external configuration dashboard can match. Every change carries a commit message, an author, a timestamp, and a diff. This creates a behavioral audit trail — you can answer the question "why did the agent start doing X on Tuesday?" by running git log -p AGENTS.md.

The example below shows a meaningful commit workflow for context file maintenance:

## Auditing recent changes to agent context files across the repo
git log --all --oneline -- '**/AGENTS.md' '**/CLAUDE.md'

## Example output:
## a3f91c2 fix(agents): tighten test-writing constraints after flaky spec incident
## 88d04b1 feat(agents): add API subdirectory context for rate-limit awareness
## 3c120e0 docs(agents): initial project-level AGENTS.md — establishes baseline

## Viewing exactly what changed in the most recent update
git show a3f91c2

This command sequence gives any team member — including someone onboarding months later — a complete history of how the team's agent contract has evolved and why. That institutional memory is one of the highest-leverage benefits of treating context files as code.

💡 Pro Tip: Add a changelog block at the top of your AGENTS.md with brief human-readable entries. Git history captures what changed; the changelog captures why. Together they make the file self-documenting.

---

Minimum Viable Context File Checklist

Before running any agent session on a project that doesn't yet have a context file, use this checklist to build one that covers the essential surface area. A file that addresses all seven areas is ready for team use; a file that skips any of them will produce inconsistent results.

## AGENTS.md — Minimum Viable Template

### 1. Project Identity
## What is this codebase? One paragraph, plain language.
## What problem does it solve? Who uses it?

### 2. Tech Stack Snapshot
## Language versions, primary frameworks, package manager.
## Example: Python 3.12, FastAPI 0.111, managed with uv

### 3. Repository Layout
## Where does source code live? Tests? Generated files?
## Call out any non-obvious directory purposes.

### 4. Workflow Commands
## How does the agent run tests? Lint? Build?
## Prefer exact commands over descriptions.
## Example:
## - Test: pytest tests/ -x -q
## - Lint: ruff check . && mypy src/
## - Build: docker build -t app:local .

### 5. Coding Conventions
## Style rules that aren't enforced by linters.
## Naming patterns, comment expectations, docstring format.

### 6. Constraints and Boundaries
## What must the agent NEVER do?
## Examples: never commit secrets, never modify migration files,
## never auto-merge, always request human review for auth changes.

### 7. Output and Communication Style
## How should the agent respond? Concise or detailed?
## Should it explain its reasoning? Use a specific PR template?

This template is intentionally spare. A minimum viable file should fit on one screen. Resist the urge to document every edge case upfront — the file will grow organically as the team encounters gaps.

⚠️ Common Mistake — Mistake 1: Writing a context file so exhaustively on day one that it becomes stale within a sprint. Start minimal, iterate often.

---

Governance: When and How to Split Into Scoped Files

A single root-level AGENTS.md is the right starting point for most projects. As complexity grows, however, a monolithic file creates its own problems: it loads irrelevant context for focused tasks, it becomes a merge conflict magnet, and it tempts teams to stop reading it carefully.

The decision to split follows a simple heuristic:

Split when a subdirectory has ALL THREE of the following:
  ✅ A distinct tech stack or toolchain from the root
  ✅ Different workflow commands or deployment targets
  ✅ Constraints that would actively conflict with root-level guidance

Do NOT split just because a directory is large or important.

When you do split, use this inheritance model:

project-root/
├── AGENTS.md              ← Global contract: applies everywhere
├── src/
│   └── AGENTS.md          ← Extends root; adds frontend-specific rules
├── api/
│   └── AGENTS.md          ← Extends root; overrides test command for API
└── infra/
    └── AGENTS.md          ← Extends root; adds Terraform-specific constraints
                              and STRONGLY restricts agent autonomy

Each subdirectory file should open with an explicit inheritance declaration:

## api/AGENTS.md

> **Scope:** This file applies to the `api/` directory only.
> It extends and partially overrides `../AGENTS.md`.
> Read the root file first.

### Overrides
- **Test command:** `cd api && cargo test -- --nocapture`
  (replaces root-level pytest invocation)

### Additions
- All external HTTP calls must use the internal service mesh client, never raw `reqwest`.
- Rate-limit headers must be propagated on every response. Do not omit them.

💡 Mental Model: Think of scoped files the way CSS thinks about specificity. The root file sets defaults; subdirectory files add specificity. The most local rule wins, but it must explicitly acknowledge what it is overriding.

---

Summary: What You Now Know

📋 Quick Reference Card:

	Concept	What It Means in Practice
🗂️	Context files as code	Stored in git, reviewed in PRs, deployed with the repo
📜	Contract framing	Encodes team intent; changes are explicit, not silent
🏗️	Minimum viable structure	7 sections before the first agent session
🗺️	Scoped inheritance	Root → subdirectory; local overrides must be declared
🔄	Living documentation	Audit at every major milestone; changelog explains why
🚫	Common pitfalls	Vague constraints, missing commands, no ownership
🧩	Broader context engineering	Context files feed into tool definitions, memory, and dynamic prompts

---

Next Steps in the Learning Path

Well-authored context files are not the destination — they are the foundation layer of a larger practice called context engineering. Here is how the skills you have built connect forward:

🔧 Tool Definitions Context files tell the agent how to behave; tool definitions tell the agent what it can do. The next step is authoring structured tool schemas (in OpenAI function-call format, MCP, or similar) and referencing them from your context file so the agent knows which tools are available and when to use them.

🧠 Memory Layers For long-running projects, static context files eventually hit limits. The progression leads to external memory — vector stores, structured logs of past decisions, or episodic summaries — that the agent retrieves at runtime. Your context file can specify which memory backend to use and what kinds of information should be persisted.

⚙️ Dynamic Prompt Assembly Advanced teams compose context programmatically: a base AGENTS.md is augmented at runtime with the current branch name, recent test failures, or the contents of a relevant ADR. Learning to author static context files well is the prerequisite skill for understanding what dynamic assembly should and should not override.

💡 Real-World Example: A platform team at a mid-size SaaS company began with a single AGENTS.md. Over six months it evolved into a three-level hierarchy of scoped files, a set of 12 tool definitions registered in their internal MCP server, and a nightly job that appended a "recent failures summary" to agent context before morning standup automation ran. Every stage of that evolution was legible in git history — each commit a record of the team learning something new about how to work with agents effectively.

---

Your Immediate Action Items

Close this lesson with three concrete tasks:

1. 🔍 Audit an existing project. Open your current repository and check whether an AGENTS.md or CLAUDE.md exists. Run it against the seven-section checklist. Identify the first gap and file a ticket to fix it.

2. 📋 Propose a PR template addition. Add a checklist item to your team's PR template: "If this PR changes agent behavior expectations, update AGENTS.md." This single change embeds context-file maintenance into your existing workflow without requiring new process.

3. 📅 Schedule a context file review. Pick the next major milestone in your project — a release, a sprint boundary, a team offsite — and block 30 minutes on the calendar now for an AGENTS.md review session. Treat it like a dependency audit: routine, brief, and high-value.

⚠️ Final critical point to remember: The most common reason context files fail teams is not poor structure — it is abandonment. A file authored once and never touched will diverge from reality within weeks. Ownership, review cadence, and PR discipline are what keep the contract alive. The file is only as good as the team's commitment to maintaining it.

🎯 Key Principle: You do not need a perfect context file. You need a maintained one. Start small, iterate in public, and let the git history tell the story of a team that got progressively better at working with AI agents.