manage-agent-instructions

Core Principles

These principles apply to ALL agent instruction files (CLAUDE.md, AGENTS.md).

1. Minimal Root File

The root instruction file should be as small as possible. Every token loads on every request regardless of relevance.

Absolute minimum content:

• One-sentence project description (acts as role prompt)
• Package manager (if not npm)
• Non-standard build/test commands

Everything else belongs in progressive disclosure files.

2. Progressive Disclosure

Structure knowledge in layers:

Level 1: Root file (~100-300 words)
Level 2: docs/CONVENTIONS.md, docs/TYPESCRIPT.md, etc.
Level 3: Nested references within those files

Load context only when needed for the current task.

3. Describe Capabilities, Not Paths

File paths change constantly. Instead of "auth logic lives in src/auth/handlers.ts", write "Authentication is handled by the AuthService module" and let the agent discover current paths.

4. No Instruction Bloat

Curate ruthlessly. Remove redundant instructions (agent already knows), vague guidance ("write clean code"), contradicting rules, and auto-generated boilerplate.

5. Tool-Specific Files

Claude Code uses CLAUDE.md, not AGENTS.md. For multi-tool support, symlink or redirect between them.

6. Monorepo Strategy

Keep each level focused on its scope. Avoid duplication.