context-engineering

Context Engineering

Proactively manage what goes into the context window. More context is NOT better — the right context at the right time is better. This skill teaches techniques to keep context lean, focused, and effective.

The reactive context-guard hook warns when context is bloated (50+ tool calls). This skill prevents it from getting there in the first place.

Rules

1. Target <2,000 lines per task — if a task requires reading more, split it
2. Load on demand — don't read files "just in case". Read when you need them
3. Forget aggressively — once a file is understood, stop re-reading it
4. Prefer Grep over Read — search for what you need instead of reading entire files
5. One concern per session — avoid mixing unrelated tasks in the same conversation
6. Summarize, don't accumulate — after analyzing multiple files, synthesize findings into a brief summary instead of carrying all raw content

Context hierarchy

What to load first, in priority order:

Priority	Source	Why
1	CLAUDE.md	Project rules, conventions, commands — always relevant
2	Spec modules (docs/specs/)	Only the ones active for this task
3	The specific files being changed	Direct context for the work
4	Test files for changed code	Verify behavior expectations
5	Error output / logs	Only when debugging
6	Conversation history	Degrades over time — prefer files as source of truth

Techniques

1. Task decomposition

Before starting a large task, split it into independent sub-tasks:

Task: "Implement user authentication"
→ Sub-task 1: Design auth API (read: PRD, API spec)
→ Sub-task 2: Implement auth middleware (read: framework docs, existing middleware)
→ Sub-task 3: Add auth tests (read: test patterns, middleware code)
→ Sub-task 4: Update docs (read: CLAUDE.md, existing docs)

Each sub-task has its own minimal context set.

2. Strategic file reading

BAD:  Read entire src/ to "understand the codebase"
GOOD: Grep for the function name, read only the relevant file + its test