Guide — context-engineer

06 New Projects

Starting from scratch.

Create your project, run setup, and you're done. Everything activates automatically.

1

Create your project

Initialize a new directory with git. Nothing special required.

Terminal
mkdir my-new-project && cd my-new-project && git init

2

Run setup

Creates a CLAUDE.md with budget zones, tool efficiency rules, model switching, and output filtering — all configured automatically.

Claude Code
/context-engineer:setup

3

Verify with a health check

Checks CLAUDE.md config, hooks, MCP hygiene, git state, and project structure. Get a pass/warn/fail table with specific fix recommendations.

Claude Code
/context-engineer:diagnose

4

Start building

Work normally. Tests, builds, and lints are filtered automatically. Budget zones adapt as context fills. You're in GREEN zone — explore freely, read full files, make architecture decisions with Opus.

Tips for new projects

Let Claude explore freely at first. You're in GREEN zone (< 60% context). Take advantage of full exploration for architecture decisions.

Create TASK.md early for complex features. Run /context-engineer:fresh-context "building the auth system" before starting multi-session work. Your progress survives across sessions.

07 Existing Projects

Drop it into any codebase.

Already have a project with a CLAUDE.md? Context-engineer fits right in without touching your existing configuration.

1

Run setup in your project

No CLAUDE.md? One gets created with the complete rules section.
Existing CLAUDE.md? Rules are appended. Your content stays untouched.
Already have the rules? Setup detects it and skips. No duplication.

Claude Code
/context-engineer:setup

2

Audit your MCP servers

Existing projects accumulate MCP servers over time. Each one adds token overhead. Get a table with name, tool count, estimated tokens, and a keep/review/remove recommendation.

Claude Code
/context-engineer:audit-mcp

3

Run the health check

Pay attention to hook coverage (are they matching your build tools?), CLAUDE.md integration (did rules merge cleanly?), and project structure (any reorganization opportunities?).

Claude Code
/context-engineer:diagnose

4

Keep working — sessions just got longer

Your workflow doesn't change. Sessions that used to die at 45 minutes now last hours. Hooks silently save thousands of tokens per test/build/lint cycle.

Tips for existing projects

Watch the budget zones on large codebases. You'll hit YELLOW and ORANGE faster because there's more code to process. The budget zone skill automatically guides Claude to be more selective.

Use fresh context for big refactors. Run /context-engineer:fresh-context "refactoring payments" before starting. When context gets heavy, TASK.md and PROGRESS.md are ready for a clean handoff.

Don't fight the RED zone. When context exceeds 85%, let Claude wrap up and create handoff files. A fresh session with full awareness beats a degraded session every time.

08 Budget Zones

Adaptive behavior as context fills.

Four zones determine how Claude works. No configuration — it adapts automatically based on how much of the context window is consumed.

GREEN — Below 60%

Full exploration mode. Read entire files freely. Use Opus for architecture decisions. No constraints on tool usage. This is where you do your best creative work.

YELLOW — 60-75%

Getting warm. Prefers Grep over Read. Summarizes content before processing. Batches related operations. Delegates simple tasks to Haiku subagents.

ORANGE — 75-85%

Conservation mode. Line ranges only, no full file reads. Targeted Grep searches. Delegates everything possible to subagents. Focus on your primary task.

RED — Above 85%

Time to hand off. Finishes the immediate task. Creates TASK.md + PROGRESS.md automatically. Suggests starting a new conversation with full context preserved.

09 Fresh Context Pattern

Complex tasks survive across sessions.

When context gets heavy or a feature spans multiple sessions, create handoff files so the next session picks up exactly where you left off.

1

Create handoff files

Run the command with a description of your task. Two files get created in your project root.

Claude Code
/context-engineer:fresh-context "implementing JWT authentication"

2

Two files capture everything

TASK.md — Goal, constraints, key files, decisions already made, current context.
PROGRESS.md — Steps completed, current state, next steps, notes and blockers.

3

Continue in a new session

Open Claude Code in the same directory. Claude reads CLAUDE.md automatically. Then tell it to pick up where you left off. Fresh context, full awareness, zero token baggage.

Claude Code
# In a new Claude Code session:
Read TASK.md and PROGRESS.md and continue where the last session left off.

10 Smart Routing

Right model, right task.

Stop using a sledgehammer for every nail. The model switching skill routes tasks to the optimal model automatically.

Task Type	Model	Cost
File search, grep, quick lookups, simple edits	Haiku	1x
Code review, refactoring, multi-file changes	Sonnet	5x
Architecture decisions, complex debugging, security review	Opus	25x

Degradation detection.

Four stages of context degradation with automatic detection. The skill flags problems in real time so you can act before quality collapses.

Stage	Context	Signs
Stage 1	~60%	Forgetting details, asking for re-confirmation of earlier decisions
Stage 2	~75%	Contradicting decisions, missing imports, inconsistent naming
Stage 3	~85%	Hallucinating APIs that don't exist, looping on the same fix attempt
Stage 4	~90%+	Incoherent reasoning, nonsensical code generation

11 Daily Workflow

Your cheat sheet.

Starting a session

Open Claude Code in your project. CLAUDE.md loads automatically. Hooks are active. Continuing previous work? Tell Claude to read TASK.md and PROGRESS.md.

During a session

Tests/builds/linting are filtered automatically. Budget zones adapt silently. Degradation detection watches in the background. Model switching guides subagent usage.

Ending a session

Task done? Commit your code. Task continues? Run /context-engineer:fresh-context. Hit RED zone? Claude suggests creating handoff files automatically.

Periodic maintenance

Run /context-engineer:diagnose if sessions feel slow. Run /context-engineer:audit-mcp after adding new MCP servers. Update CLAUDE.md if architecture changes.

12 Troubleshooting

Common questions.

Issue	Solution
Hooks don't seem to be filtering	Hooks only activate on output > 40 lines. Run a test suite with enough tests to generate verbose output.
Setup added duplicate content	Run /context-engineer:diagnose to check. Remove the duplicate section from CLAUDE.md manually.
Context still fills quickly	Expected on large codebases. Use fresh context more frequently. Focus sessions on specific subsystems.
Want to customize hook triggers	Edit scripts at hooks/scripts/. Each has a pattern matcher at the top.
Want to change the 40-line threshold	Edit the LINE_COUNT check in any hook script under hooks/scripts/.