title: Progressive Disclosure slug: progressive-disclosure category: workflow-pattern status: proven difficulty: beginner tags: [CLAUDE.md, configuration, iterative, context-management] prerequisites: [basic-cli-usage, claude-md-basics] estimated_time: 10min to learn, ongoing practice cost_per_use: "$0.00 (configuration only)"

Progressive Disclosure

Problem

Writing a massive CLAUDE.md up front is guesswork — you do not know what the agent needs until it fails. A 500-line instruction file wastes context tokens on rules the agent may never need, and you still miss the rules it actually does need. You need a way to build configuration organically from real failures.

Solution

Start with a minimal CLAUDE.md and grow it only when the agent makes a mistake you want to prevent next time.

Step-by-Step

1. Start minimal: Create a CLAUDE.md with only project basics (language, build commands, test commands).
2. Work normally: Use the agent for real tasks.
3. Observe failures: When the agent does something wrong, note the correction you give it.
4. Promote to CLAUDE.md: If you correct the same thing twice, add a rule to CLAUDE.md.
5. Prune periodically: Remove rules that are no longer relevant or that the agent consistently follows without prompting.

When to Use

• Starting a new project with CLI agents
• Onboarding CLI agents to an existing codebase
• When your CLAUDE.md has grown stale or bloated
• When the agent keeps making the same mistake

When NOT to Use

• You already have a well-tuned CLAUDE.md that works
• One-off tasks where you will not reuse the configuration
• Team settings where CLAUDE.md is managed centrally (coordinate first)

Example: Claude Code

# Step 1: Start with a minimal CLAUDE.md
cat > CLAUDE.md << 'EOF'
# Project: my-api

## Stack
- TypeScript, Node.js 20, Express
- PostgreSQL with Prisma ORM
- Jest for testing

## Commands
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`
EOF

# Step 2: Work normally. The agent makes a mistake:
claude -p "Add a new endpoint for user preferences."
# Agent uses raw SQL instead of Prisma. You correct it in session.

# Step 3: It happens again on the next task. Promote to CLAUDE.md:
cat >> CLAUDE.md << 'EOF'

## Rules
- Always use Prisma ORM for database queries. Never write raw SQL.
EOF

# Step 4: Over time, your CLAUDE.md grows organically:
cat >> CLAUDE.md << 'EOF'
- Use zod for request validation, not manual checks.
- Error responses must use the ApiError class from src/errors.ts.
- New endpoints need tests in tests/routes/ following existing patterns.
EOF

# Audit your CLAUDE.md periodically
claude -p "Review our CLAUDE.md file. For each rule, check if it is \
  still relevant to the current codebase. Flag any rules that reference \
  files, patterns, or libraries that no longer exist."

Example: Codex CLI

# Codex uses AGENTS.md instead of CLAUDE.md — same principle applies
cat > AGENTS.md << 'EOF'
# Project: my-api
- TypeScript, Express, Prisma ORM
- Run tests: npm test
- Always use Prisma for DB access
EOF

# After repeated corrections, append:
echo "- Use zod for validation, not manual checks." >> AGENTS.md

Cost Estimate

This pattern saves money over time by reducing corrections and re-runs caused by preventable agent mistakes.

Maturity Notes

Status: Proven. This pattern reflects how experienced CLI agent users actually build their configurations. The key discipline is the "two-strike rule" — do not add a rule after a single mistake (it might be a fluke), but always add one after the second occurrence. Over 2-4 weeks of active use, you will build a CLAUDE.md that precisely matches your project's needs.

Related

• Module: Project Memory
• Pattern: Explore Before Change
• Module: Session Architecture