Setup and context
Project configuration files are critical to the success of AI-driven development. With the rise of AGENTS.md and CLAUDE.md, AI tools can now understand project intent with precision.
What is AGENTS.md?—The De Facto Standard
Historical Context: Formal Adoption by Linux Foundation
In 2025, the Agentic AI Foundation (AAIF), operating under the Linux Foundation, formally adopted AGENTS.md as an ecosystem standard. Today, over 60,000 repositories on GitHub use this format—making it a true industry standard, not merely a suggestion.
Purpose of AGENTS.md
AGENTS.md provides a metadata layer that enables AI agents to automatically understand projects and operate correctly. Unlike human-readable READMEs, this format is designed for machines to parse and execute as actionable instructions.
Tool Support (March 2026)
| Tool | AGENTS.md | CLAUDE.md | Precedence | |---|---|---|---| | Claude Code | ✓ Fallback | ✓ Primary | CLAUDE.md first | | Codex CLI | ✓ Full | ✗ None | Directory traversal | | Cursor | ✓ Root only | ✗ None | Root only | | GitHub Copilot | ✗ Not yet | ✗ Not yet | Infers from prompt | | Gemini CLI | ✓ Full | ✗ None | Both supported |
What is CLAUDE.md?—Claude Code-Optimized Format
Design Philosophy
CLAUDE.md is a configuration format optimized specifically for Claude Code (Anthropic's official CLI). It differs from AGENTS.md in key ways:
- Focuses on Claude-specific features (Cowork integration, memory systems)
- Supports richer contextual information for complex workflows
- Defines rules for multi-file edits and concurrent operations
- Enables step-by-step execution (Step 0–8 patterns)
Structure Example
---
# Project Overview
## Technology Stack
## Critical Rules
### 1. [Rule 1]
### 2. [Rule 2]
...
## Complete Workflow (Step 0–8)CLAUDE.md uses structured sections that are both human-readable and easy for Claude Code to parse.
AGENTS.md vs. CLAUDE.md: Key Differences
1. Format Structure
| Aspect | AGENTS.md | CLAUDE.md | |---|---|---| | Base Format | YAML + Markdown | Headings + Markdown | | Machine Readability | YAML parser required | Text traversal + section extraction | | Human Readability | Moderate (YAML syntax) | High (pure Markdown) | | Extensibility | Strict schema | Free-form sections |
2. Coverage Strengths
AGENTS.md excels at:
- Environment setup (dependencies, version constraints)
- Test, build, and deploy commands
- File structure explanation
- Prohibitions (untouchable files, immutable logic)
CLAUDE.md excels at:
- Step-by-step workflows (Step 0 → Step 8)
- Claude Code–specific features (scheduled tasks, Cowork integration)
- Operational manuals for projects
- Detailed troubleshooting reference tables
3. Discovery Order
AI Tool launches
↓
Search for CLAUDE.md (Claude Code)
↓ [if not found]
Search for AGENTS.md (fallback)
↓ [if not found]
Directory traversal (Codex CLI)
↓ [if not found]
Infer from prompt history (GitHub Copilot, etc.)How to Write Them Effectively
AGENTS.md Writing Guide (Practical Example)
# agents.md
---
agents:
- name: "Frontend Developer"
role: "React/TypeScript development"
constraints:
- "Can edit src/components/* only"
- "All API calls must be in src/services/*"
- "Use Tailwind CSS exclusively"
verification:
- "npm test passes all"
- "npm run lint returns zero errors"
- "Type check: tsc --noEmit"
- name: "Backend Developer"
role: "Node.js API development"
constraints:
- "Can edit src/api/* only"
- "Database schema changes forbidden"
verification:
- "npm run test:api"
- "curl http://localhost:3001/health"
technology_stack:
- "React 19 + TypeScript 5"
- "Node.js 20 + Express"
- "PostgreSQL 15"
- "Docker Compose"
build:
frontend: "npm run build:web"
backend: "npm run build:api"
test: "npm test"
deploy: "docker-compose up -d"
prohibitions:
- "Never edit node_modules directly"
- "Never commit .env.local"
- "Never create database migrations automatically"
- "Never update major versions without approval"
---CLAUDE.md Writing Guide (Practical Example)
# MyProject — CLAUDE.md
This file is the Claude Code configuration for MyProject.
## Critical Rules
### 1. Always use TypeScript
JavaScript is forbidden by default. Exception: monolithic config files (webpack.config.js, etc.)
### 2. Keep test files in src/tests/
- ❌ src/components/Button.test.tsx
- ✓ src/tests/Button.test.tsx
### 3. Use CSS Modules exclusively
Inline Tailwind CSS is forbidden to maintain scoped styling and prevent name collisions.
## Step 0–8 Workflow
### Step 0: Environment Setup
```bash
git clone [github.com](https://github.com/user/myproject.git)
cd myproject
npm install --prefer-offlineStep 1: Type Check
tsc --noEmitStep 2: Run Tests
npm test -- --coverageStep 3: Code Implementation
...
Step 4: Lint + Format
npm run lint:fix...
Common Mistakes & Fixes
Mistake 1: Mixing CSS-in-JS libraries
❌ Mixing styled-components with CSS Modules ✓ Use CSS Modules only
Mistake 2: Excessive new dependencies
❌ npm install lodash moment (large utilities) ✓ Use existing dependencies
...
---
## Best Practices
### Pattern 1: Small to Medium Projects (< 100K LoC)
✓ Create AGENTS.md (aligns with 60,000 repo standard) ✓ CLAUDE.md not required
**Benefits:**
- Multi-AI tool compatible (Codex CLI, Cursor, Gemini CLI)
- Standard format—easy for new team members
- Likely automatic support with tool updates
### Pattern 2: Claude Code–Centric Large Projects
✓ Create CLAUDE.md (detailed workflows) ✓ Also include AGENTS.md (fallback)
**File structure:**
project/ ├── CLAUDE.md ← Claude Code detailed config ├── agents.md ← For other tools (AGENTS.md format) ├── README.md ← Human documentation ├── src/ ├── tests/ └── docs/
### Pattern 3: Multi-AI + Multi-Team Environment
✓ Base on AGENTS.md with multiple role definitions ✓ Enhance with CLAUDE.md for Claude Code specifics ✓ Also include .cursorrules / .copilot-instructions
**Result:**
- GitHub Copilot (.copilot-instructions)
- Cursor (.cursorrules)
- Claude Code (CLAUDE.md)
- Codex CLI (AGENTS.md)
Each tool receives instructions in its native format.
---
## Essential Sections to Include
Five must-have sections in both AGENTS.md and CLAUDE.md:
### 1. Project Overview / Technology Stack
```markdown
## Project Overview
- Purpose:
- Target Users:
- Core Architecture:
## Technology Stack
- Frontend: React 19 + TypeScript
- Backend: Node.js 20 + Express
- Database: PostgreSQL 15
- Infrastructure: Docker Compose + GitHub Actions
2. Build, Test, and Run Commands
## Command Reference
```bash
npm install # Install dependencies
npm run dev # Start dev server
npm test # Run all tests
npm run build # Production build
npm run lint:fix # Lint and auto-fix
### 3. Coding Standards / Design Principles
```markdown
## Coding Standards
- TypeScript strict mode (strict: true)
- Naming: camelCase (vars/functions), PascalCase (types/components)
- File size limit: 300 lines (split if exceeded)
4. Testing Guidelines
## Testing Guidelines
- Coverage: 80% minimum required
- Test framework: Vitest
- E2E: Playwright (src/tests/e2e/)5. Prohibitions
## Prohibitions (AI Must Never)
- Edit node_modules directly
- Commit .env files
- Create database schemas automatically
- Update major dependency versions without approvalIncremental Implementation Strategy
Initial version (minimal):
Write 5–10 critical rules
Growth phase (after 1 month):
Add common errors and mistakes
Include remediation steps for each
Mature phase (6+ months):
Define multiple roles (Frontend, Backend, QA)
Add step-by-step workflows
Build detailed troubleshooting reference (30–50 items)
Conclusion
| Aspect | AGENTS.md | CLAUDE.md | |---|---|---| | Use When | Multi-AI tools / standardization required | Claude Code–centric / detailed workflows | | Tool Support | 4+ tools | 1 tool (but deeply optimized) | | Learning Curve | Moderate | Low | | Implementation | Easy (YAML templates) | Moderate (custom sections) | | Adoption (60K repos) | ✓ Standard | ✗ Claude Lab–specific |
Final recommendation:
New projects → Start with AGENTS.md
Existing projects → Backfill AGENTS.md + enhance with CLAUDE.md
Claude Code–exclusive → CLAUDE.md + AGENTS.md fallback
This approach ensures you're prepared for AI tool evolution while keeping documentation readable for humans.
Related Resources
- AGENTS.md Official Specification
- [Claude Code Official Guide]((/articles/claude-code/claude-code-agent-guide)
- [Claude Code settings.json Complete Reference]((/articles/claude-code/claude-code-settings-json-complete-guide)
- [Building MCP Servers]((/articles/claude-code/build-mcp-server)