CLAUDE.md

Custom instructions that Claude Code reads automatically.

AGENTS.md

Custom instructions that coding agents read automatically.

Codex CLI · Gemini CLI · Cursor · OpenCode

Be concise.

Models can only follow a few instructions before failing.

📉 Fewer Concepts

→

🎯 More Focus

→

🚀 Better Results

If you tell someone 100 things, they'll struggle to remember them all.

Why conciseness matters

Models don't "think" - they generate text based on previous text.

What the model sees:

  • System prompt + CLAUDE.md files
  • Code files it reads
  • MCP server responses, tool results, etc

Confusing or unrelated content increases entropy - the model has more noise to work through.

Keep context clean

Be concise. Only include what the model truly needs.

Start fresh often. Use /new or exit and relaunch sessions frequently.

Every instruction competes for the model's attention.

When CLAUDE.md Loads

~/.claude/CLAUDE.md     # Always loaded (personal prefs)

~/pla/CLAUDE.md         # Loaded when you start a session here

~/pla/CLAUDE.local.md   # Personal additions (gitignored)

All files are loaded and appended. Treat changes like code review.

Progressive Disclosure

Add CLAUDE.md files in subdirectories - loaded only when working there.

project/
├── CLAUDE.md              # Build commands, architecture
├── src/
│   ├── CLAUDE.md          # Code patterns
│   └── models/
│       └── CLAUDE.md      # Model conventions
├── tests/
│   └── CLAUDE.md          # Test utilities
└── docs/
    └── CLAUDE.md          # Doc style

tests/CLAUDE.md loads only when working in tests/.

Rules

For larger projects: .claude/rules/*.md

  • Works like Cursor's rules system
  • Path-specific with YAML frontmatter (paths: ["src/**/*.ts"])
  • Same priority as CLAUDE.md - they coexist

Writing Tips

  • Be concise - read and be skeptical of every line
  • Be specific - "Use Pest" not "Use appropriate testing"
  • Include commands - npm run dev, zar migrate
  • Skip obvious things - no standard conventions
  • No code formatting rules - it's not an expensive, slow linter

Example: Root

# Project Name

Laravel 11 + Livewire 3. SingleStore database.

## Commands
- `zar migrate` - Run migrations
- `zex vendor/bin/pint --dirty` - Format code

## Patterns
- Multi-tenant: filter by tenant_id

Example: Subdirectory

# tests/CLAUDE.md

## Multi-tenancy
Call `createNewTenantAndSetAsCurrent()` in beforeEach().

## Factories
Located in `database/factories/`.

Quick Reference

Global

~/.claude/CLAUDE.md
Personal

Project

./CLAUDE.md
Git: Yes

Subdirectory

./dir/CLAUDE.md
Git: Yes

Personal

**/CLAUDE.local.md
Git: No

Rules

.claude/rules/*.md
Git: Yes

Tools: Status Lines