compiling-project-settings

Creating Project Settings

Analyzes your codebase and generates a lean CLAUDE.md following the "less is more" principle. References docs/ for detailed content.

Critical: The 150 Instruction Limit

Claude reliably follows ~150 instructions. Claude Code's system prompt uses ~50, leaving ~100 for CLAUDE.md + agents combined. A bloated CLAUDE.md degrades all instruction-following.

Safety

Always use fd instead of find for filesystem discovery. fd is safe by design (no -exec, no -delete).

When Invoked

1. Pre-Flight Validation:

• Verify git repository (FAIL if not)
• If CLAUDE.md exists, update it unconditionally; report "updated" (not "created") in the summary

2. Codebase Analysis:

• Detect tech stack from project files
• Identify framework and architecture pattern
• Map key directory structure
• Check for .claude/agents/planner.md and builder.md (triggers Workflow section)

3. Code Exploration:

• Read key configuration files
• Sample 2-3 implementation files to detect patterns
• Identify essential commands (build, test, run)

4. Generate Lean CLAUDE.md (~50-100 lines):

1. Mission Statement (1 sentence, bold) — why this project exists and who it serves; anchors every coding, speccing, and architecture decision
2. Project Context (2-3 sentences) — what this is
3. About This Project (tech stack, 2-3 sentences)
4. Key Directories (5-8 items max)
5. Commands (essential only)
6. Standards (critical conventions only)
7. Notes (gotchas, warnings)
8. Workflow (conditional — only if planner/builder agents exist)
9. Additional Documentation — references to docs/ files

5. Validation:

• Verify under 100 lines
• Verify 80% rule compliance
• Confirm no bloat or linting instructions

Arguments

• --focus "area": Emphasize specific patterns (e.g., "caching", "auth")
• Default: Lean CLAUDE.md only. Run /compiling-project-docs afterward for detailed docs.

CLAUDE.md Template (Target: 50-100 lines)

# Project Context

**Mission:** One sentence — what the project does and who it serves.

Brief context (1-2 sentences).

## About This Project

[Tech stack, 2-3 sentences max]

## Key Directories

- `src/` — Source code
- `tests/` — Test files
- [5-8 items max]

## Commands

```bash
[command]  # Dev server
[command]  # Run tests
[command]  # Build

Standards

• [Critical convention 1]
• [3-5 items max, only what causes bugs if missed]

Notes

• [Gotcha 1]
• [Only critical warnings]

Workflow

When implementing multi-part features:

1. Decompose into independent subproblems
2. Spawn parallel planner agents via Task tool
3. Collect plans, resolve file-overlap conflicts
4. Spawn parallel builder agents for independent tasks
5. Sequence tasks that touch shared files; parallelize the rest

Additional Documentation

Before specific tasks, read relevant documentation:

• Architecture: docs/architecture.md
• Testing: docs/testing.md Read only what's relevant to your current task.

Generate docs with: /compiling-project-docs

## The 80% Rule

**Only include instructions relevant to 80%+ of sessions.**

Include in CLAUDE.md: essential commands, critical conventions, key directories, gotchas, tech stack overview.

Move to `docs/`: detailed deployment steps, comprehensive code style, full architecture, database schema, edge case handling.

Do NOT include: linting rules (use actual linters), what Claude can infer, task-specific instructions (belong in agents), sensitive info (API keys, credentials).

Run `/compiling-project-docs` to generate the `docs/` content.