CLAUDE.md and AGENTS.md—Differences, Best Practices, and Implementation Patterns

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)

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

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-offline

Step 1: Type Check

tsc --noEmit

Step 2: Run Tests

npm test -- --coverage

Step 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 approval

Incremental 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

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)