Catalog My learning Blog
AI-Assisted Coding Course: Agentic Development in 30 Days · Phase 2 · Lesson 7 · 5 min read

How to Write CLAUDE.md and AGENTS.md Files

On this page
  1. Learning Objective
  2. Concept Explanation
  3. Worked Example: A Compact AGENTS.md with a Claude Code Bridge
  4. Real-World Examples
  5. Review Questions & Answers

Learning Objective

Write effective project instruction files for coding agents: know where CLAUDE.md and AGENTS.md live and how they load, what belongs in them and what does not, how to keep them short with imports and path-scoped rules, and how to maintain them as the project changes.

Concept Explanation

Every coding agent starts each session with no memory of your project. Instruction files fix that. When a session starts, the agent loads a markdown file from your repository and treats its contents as standing instructions. Claude Code reads CLAUDE.md. Most other agents, including OpenAI Codex, Cursor, GitHub Copilot, Gemini CLI and many more, read AGENTS.md, an open format created in 2025 that became a Linux Foundation project under the Agentic AI Foundation in December 2025 and has been adopted by more than 60,000 repositories. Claude Code can also read AGENTS.md, so a team using several tools can keep one file and, if needed, a CLAUDE.md that imports it.

Files can exist at several levels. A project file at the repository root is shared through version control and is where team knowledge belongs. A personal file in your home directory applies to all your projects, for preferences such as your editor or language of explanation. A local file, CLAUDE.local.md in Claude Code, holds your private notes for one project and is gitignored. Files in subdirectories load when the agent works in that part of the tree, which suits monorepos where each package has its own commands and conventions.

What belongs in the file is information the agent cannot easily infer and needs often. The commands to build, test, lint and run the app, with the exact flags. The project layout in a few lines. Conventions that differ from defaults, such as "use the Result type for errors, never throw in domain code". Architectural boundaries: which layers may call which. Gotchas that cost time: the test database must be running, a generated client must be regenerated after schema changes. And the definition of done: run these checks before reporting completion.

What does not belong is just as important. Do not paste style rules your linter already enforces; let the agent run the linter. Do not include long explanations, tutorials or the full API reference. Do not include secrets. Do not include task-specific instructions that confuse other tasks. Claude Code's documentation recommends keeping each file under about 200 lines because longer files consume context and reduce adherence. Use imports, written as @path/to/file, to pull in details only where needed, and path-scoped rules, such as files in .claude/rules with a paths field, to load instructions only when the agent touches matching files.

Treat the file as code. Review changes to it in pull requests, prune instructions that are outdated or contradictory, and add a rule whenever you find yourself correcting the agent for the same thing twice. Contradictions matter: when two instructions conflict, the agent may follow either one.

SectionExample contentWhy it earns its place
Commandsnpm test -- path, npm run typecheck, docker compose up dbAgent cannot guess flags and setup
Layoutapps/web is Next.js, services/billing is GoSaves exploration on every task
ConventionsErrors as Result, no default exportsDiffers from common defaults
BoundariesUI never imports from db/Prevents architectural drift
GotchasRegenerate client after editing schema.prismaAvoids repeated, costly mistakes
Definition of doneTypecheck, lint and tests pass; show outputMakes verification routine

Worked Example: A Compact AGENTS.md with a Claude Code Bridge

The AGENTS.md below serves every tool on the team. CLAUDE.md imports it and adds one Claude-specific rule, and a path-scoped rule file keeps database guidance out of unrelated tasks.

Code
<!-- AGENTS.md -->
# Acme Store

## Commands
- Install: pnpm install
- Dev server: pnpm dev (needs `docker compose up -d db` first)
- Tests: pnpm test -- <path>   (whole suite: pnpm test, about 3 minutes)
- Checks before finishing: pnpm typecheck && pnpm lint && pnpm test -- <changed area>

## Layout
- apps/web: Next.js storefront. apps/admin: internal admin.
- packages/core: domain logic, framework-free. packages/db: Prisma schema and client.

## Conventions
- Domain functions return Result<T, DomainError>; never throw in packages/core.
- Money is integer cents (type Cents). Never use floats for currency.
- New UI components go in apps/web/components with a colocated *.test.tsx.

## Boundaries
- apps/* may import packages/*, never the reverse. UI never imports packages/db directly.

## Gotchas
- After editing packages/db/schema.prisma run pnpm db:generate, or types will be stale.

## Done means
- All checks above pass, and your summary lists the commands you ran and their results.
Code
<!-- CLAUDE.md -->
@AGENTS.md

- Use plan mode for any change touching more than three files.
Code
<!-- .claude/rules/database.md -->
---
paths: packages/db/**
---
- Every migration must be reversible; include the down migration.
- Never edit an applied migration; create a new one.

The project file is about 30 lines, every line changes behavior, and database rules load only when the agent works in packages/db.

AGENTS.md serves most tools and CLAUDE.md can import it. Personal and local files add private preferences, and path-scoped rules load only when the agent touches matching files, keeping the always-loaded part short.
AGENTS.md serves most tools and CLAUDE.md can import it. Personal and local files add private preferences, and path-scoped rules load only when the agent touches matching files, keeping the always-loaded part short.

Real-World Examples

  • AGENTS.md was released by OpenAI with contributors including Google, Cursor, Factory and Sourcegraph in August 2025, adopted by tools such as Codex, Cursor, GitHub Copilot, Gemini CLI and VS Code, and donated to the Linux Foundation's Agentic AI Foundation in December 2025.
  • Claude Code's memory documentation recommends targeting under 200 lines per CLAUDE.md, using @path imports and path-scoped rules for detail, and periodically removing outdated or conflicting instructions because contradictions lead to arbitrary choices.
Key TakeawaysInstruction files give every agent session the durable project knowledge it cannot infer from the code on its own. That means commands, layout, conventions, boundaries, gotchas and the definition of done. Use AGENTS.md for cross-tool teams and CLAUDE.md for Claude Code, which can import it. Keep files short, leave linter rules to the linter, push detail into imports and path-scoped rules, and maintain the file like code, adding a rule whenever you correct the same mistake twice.

Review Questions & Answers

AGENTS.md is an open, cross-tool instruction file format read by many agents. CLAUDE.md is Claude Code's instruction file; Claude Code can also read AGENTS.md, and a CLAUDE.md can import AGENTS.md so a team maintains one shared file.

The linter already enforces them deterministically. Repeating them wastes context and can drift from the real configuration; it is better to tell the agent to run the linter.

They load only when the agent works on files matching their paths, so detailed guidance for one area, such as database migrations, does not consume context or distract during unrelated tasks.

Correcting the agent for the same mistake twice. Recurring corrections are exactly the durable knowledge the file should capture.