Context Master

Context Master

Universal context management and planning skill for complex tasks, long sessions, and multi-file projects. Works the same way whether you are in the Web app, the API, or Claude Code CLI; CLI-specific bonuses live in references/claude-code-cli.md.

This SKILL.md is intentionally short. Detailed material lives in references/ — load only what you need.

When to activate

Activate proactively whenever the request matches one of:

• Multi-file project (3+ related files, websites, apps, APIs, doc sets).
• Architecture or technology decision ("should we use X or Y", "which approach…").
• Research / comparison / tradeoff analysis.
• Refactoring or migration work.
• Long coding session where context efficiency matters.
• Any task with 3+ sequential steps or shared dependencies.

If the request is a single file with no dependencies, skip this skill.

The 5-step workflow (memorize this)

For any multi-file project — websites, apps, APIs, documentation sets — run these five steps in order:

1. STOP — do not create any files yet. 2. PLAN — use extended thinking or a planning document (both equally valid; see references/multi-file-planning.md). 3. ANNOUNCE — state the file list and creation order to the user. 4. CREATE — write files in optimal order (foundations before dependents). 5. VERIFY — check that every reference resolves; fix issues before declaring done.

Worked example (portfolio website)

User: "Create a portfolio with home, about, projects, and contact pages."

Step 1 STOP    -- do not start with index.html.
Step 2 PLAN    -- "Think hard about architecture: 5 files needed,
                  styles.css is the shared dependency."
Step 3 ANNOUNCE -- "I'll create:
                  1. styles.css       (shared styling)
                  2. index.html       (references styles.css)
                  3. about.html
                  4. projects.html
                  5. contact.html"
Step 4 CREATE   -- write files in that order.
Step 5 VERIFY   -- every HTML file links styles.css; navigation resolves.

Result: no refactor, no re-export, no broken links.

The full template, optimal-order patterns by project type (website / React / backend API / etc.), and verification checklists are in references/multi-file-planning.md.

Core principles (one line each)

1. Plan before you write — extended thinking or planning doc, never both skipped. 2. Foundations first — shared dependencies (CSS, config, base classes, schemas) precede dependents. 3. Delegate deep analysis to isolated contexts — subagents (CLI) or thinking artifacts (Web/API) keep the main thread clean. 4. Phase boundaries — name each phase ("Phase 1 complete; moving to Phase 2: …") so context doesn't blur. 5. Artifacts over inline content — long code or docs live in artifacts/files, not chat history. 6. Progressive disclosure — ask for one slice at a time; don't batch unrelated steps. 7. Signal resets — say "setting aside the previous approach…" when changing direction. 8. Reflect after large projects — was it planned? Did references break? Use the post-project checklist in references/multi-file-planning.md.

Full rationale and examples for every principle: references/universal-best-practices.md.

Token-savings rule of thumb

A 200K-token context window holds roughly 16-17 medium projects with planning, 7-8 without — a 2.1x effective increase. Numbers and methodology in references/multi-file-planning.md.

Passive deep-thinking architecture

The single most powerful pattern for context efficiency: route deep reasoning into an isolated space and return a short summary to the main thread.

• Claude Code CLI: /agent deep-analyzer "Ultrathink about [decision]" — ~5K tokens of reasoning happens out-of-band; main context receives a ~200-token summary (~23x efficiency).
• Web / API: "Create a deep-analysis artifact and ultrathink about [decision]" — same idea, artifact instead of subagent.

Triggers, anti-patterns, and ready-made prompts: references/thinking-delegation.md.

Common workflows (pointers only)

Each of these has a step-by-step procedure in references/workflows.md:

• Workflow 0 — Multi-file website/project creation (the default — same 5 steps above with extra detail).
• Workflow 1 — Complex decision-making (architecture, tech choice).
• Workflow 2 — Complex feature development (analysis → design → implement → test → integrate).
• Workflow 3 — Research and technology evaluation.
• Workflow 4 — Code generation and iteration via artifacts.
• Workflow 5 — Refactoring with isolated analysis.

Anti-patterns (avoid these)

Quick list — examples and fixes in references/anti-patterns.md:

1. Creating files before planning — wastes context on refactors. 2. Asking for everything at once — overloads context and produces shallow output. 3. Inlining long code/docs in chat — bloats history; use artifacts/files. 4. Letting deep reasoning happen in main thread — costs ~5K tokens that could be ~200. 5. No phase boundaries — context blurs across unrelated subtasks.

Troubleshooting

When sessions drift (responses unfocused, conversations getting too long, code regenerating instead of editing, extended thinking not engaging), see references/troubleshooting.md for a symptom → remedy table covering Web/API and CLI separately.

Claude Code CLI bonuses

If you are running in Claude Code CLI, you also get:

• /clear, /compact, /continue — built-in context controls.
• /agent <name> — delegate to an isolated subagent.
• CLAUDE.md — persistent project memory.
• Helper scripts for generating CLAUDE.md and subagent definitions.

Details, script invocations, and the deep-analysis delegation patterns: references/claude-code-cli.md.

Skill–subagent integration patterns (when both are available) live in references/agent-skills-integration-2025.md. Long-form context strategies and subagent prompt patterns: references/context_strategies.md and references/subagent_patterns.md.

Reference map

Success indicators

• You announced the plan before creating any file.
• Foundation files (CSS, config, schemas) were written before dependents.
• No reference broke on first run; no refactor was needed.
• Deep reasoning happened in a subagent or artifact, not the main thread.
• Phases were named as you crossed them.

If any of those failed, walk back through references/anti-patterns.md and references/multi-file-planning.md post-project section before the next task.

🚨 CRITICAL GUIDELINES

Windows File Path Requirements

MANDATORY: Always Use Backslashes on Windows for File Paths

When using Edit or Write tools on Windows, you MUST use backslashes (\) in file paths, NOT forward slashes (/).

Examples:

• ❌ WRONG: D:/repos/project/file.tsx
• ✅ CORRECT: D:\repos\project\file.tsx

This applies to:

• Edit tool file_path parameter
• Write tool file_path parameter
• All file operations on Windows systems

Documentation Guidelines

NEVER create new documentation files unless explicitly requested by the user.

• Priority: Update existing README.md files rather than creating new documentation
• Repository cleanliness: Keep repository root clean - only README.md unless user requests otherwise
• Style: Documentation should be concise, direct, and professional - avoid AI-generated tone
• User preference: Only create additional .md files when user specifically asks for documentation

---

Agent Skills Integration (2025)

Overview

Integration patterns between context-master and Agent Skills for autonomous context management in 2025 Claude Code.

Core Pattern: Context-Aware Agent Skills

What Are Agent Skills?

Context-efficient knowledge packages that:

• Activate automatically based on context
• Provide specialized guidance
• Stay lean (avoid context bloat)
• Delegate heavy lifting to subagents

Context Master + Agent Skills Synergy

Context Master provides:

• Planning frameworks for multi-file projects
• Thinking delegation architecture
• Context optimization strategies
• Session management patterns

Agent Skills provide:

• Domain-specific knowledge
• Automated activation triggers
• Custom tool integration
• Team-wide consistency

Pattern 1: Context-First Agent Skill

# My Custom Agent Skill

## Activation Triggers
- User mentions "create [N]+ files"
- Request involves "architecture"
- Task needs "planning"

## Instructions

### Step 1: Context Check
Before proceeding, ask:
- Are we working with multi-file project? (YES → use context-master)
- Is thinking delegation needed? (YES → delegate)

### Step 2: Leverage Context Master
- Use /plan-project command for architecture
- Use thinking delegation for deep analysis
- Reference context-master patterns

### Step 3: Your Domain Work
- Implement using domain expertise
- Verify structure using /verify-structure
- Document decisions in DECISIONS.md

Pattern 2: Autonomous Context Delegation

Instead of doing analysis in Agent Skill context:

Bad (fills Agent Skill context):

"Let me think deeply about the architecture..."
[5K tokens of thinking in Agent Skill context]

Good (preserves Agent Skill context):

"This needs deep analysis. Let me delegate:
/agent deep-analyzer "Ultrathink about [architecture]"
[Deep analysis happens in isolated agent context]
[Returns summary to Agent Skill - clean]

Pattern 3: Project-Specific Context Strategy

In your Agent Skill:

## When This Skill Activates

1. Check if CLAUDE.md exists
2. If yes: Load context strategy from CLAUDE.md
3. If no: Use default context-master patterns

Recommended CLAUDE.md Strategy for This Skill

Include in your project's CLAUDE.md:

ContextStrategy:
  - Use subagents for: [domain-specific searches]
  - Keep in main for: [your domain decisions]
  - Compact when: [context grows beyond X]
  - Clear before: [major phase transitions]

Pattern 4: Team Consistency

Create Standard Agent Skill Template

# Team Agent Skill Template

## Activation
Activates for: [domain work]

## Context Management

Before doing any analysis:
1. Reference /plan-project for multi-file work
2. Use thinking delegation for complex decisions
3. Document findings in [DOMAIN]_FINDINGS.md
4. Leave main context clean for other agents

## Integration Points
- Works with: context-master, plugin-master
- Delegates to: deep_analyzer for critical choices
- Outputs to: Structured documents, not context

Pattern 5: Cascading Deep Analysis

For complex domains requiring multiple analyses:

User Request → Triggers Your Agent Skill
              ↓
Agent Skill identifies sub-questions:
  Q1: Frontend implications?
  Q2: Backend implications?
  Q3: Data implications?
  Q4: Integrated recommendation?
              ↓
Delegates each:
  /agent frontend-deep-analyzer "Ultrathink Q1"
  /agent backend-deep-analyzer "Ultrathink Q2"
  /agent data-deep-analyzer "Ultrathink Q3"
  /agent synthesis-analyzer "Ultrathink Q4"
              ↓
Receives 4 summaries (~200 tokens each)
              ↓
Agent Skill synthesizes in clean context
              ↓
Returns integrated recommendation to main

Context used in main: ~1,200 tokens (4 summaries + synthesis) vs Traditional: 20K+ tokens (all thinking in main) Efficiency: 16-17x

Pattern 6: Progressive Context Loading

Avoid loading all project context upfront:

// In your Agent Skill:

Step 1: Minimal context
- Load just CLAUDE.md
- Understand strategy

Step 2: Selective context
- Load only relevant files (use subagent search)
- Get summaries, not full content

Step 3: Deep dive only if needed
- Load full context only for specific modules
- Use Progressive disclosure pattern

Implementation Checklist

• [ ] Agent Skill documentation mentions context-master
• [ ] Activation triggers align with planning needs
• [ ] Uses /plan-project for multi-file work
• [ ] Delegates deep analysis to subagents
• [ ] Documents decisions outside of context
• [ ] CLAUDE.md includes skill-specific strategies
• [ ] Team training covers thinking delegation
• [ ] Hooks configured for auto-management

Advanced: Agent Skill + Plugin Creation Workflow

For creating domain-specific plugins:

1. User wants new plugin for domain X
2. Agent Skill → plugin-master integration:
   /agent plugin-architect "Design plugin for X"
   
3. plugin-architect:
   - Thinks about structure
   - Considers context implications
   - References context-master patterns
   
4. Returns design
5. User/Agent Skill creates plugin
6. New plugin includes context-master references

Real-World Example: Frontend Agent Skill

# Frontend Agent Skill

## When This Activates
- User: "Create a React component..."
- User: "Build a multi-page website..."
- User: "Design component architecture..."

## Instructions

### Multi-File Check
If creating 3+ files:
1. "/plan-project - Think about component structure"
2. Wait for analysis
3. Implement files in recommended order
4. "/verify-structure - Check component references"

### Complex Decisions
If component architecture is complex:
1. "/agent frontend-analyzer - Think about patterns"
2. Receive analysis
3. Design components in main context (clean)

### Documentation
1. Save component decisions to COMPONENT_DECISIONS.md
2. Leave main context for next task
3. Reference document as needed

Measuring Success

Good indicators:

• Main context stays under 50K tokens for complex work
• Multiple features/analyses per session without degradation
• Clear decision logs without context bloat
• Smooth team collaboration

Warning signs:

• Main context consistently >80K
• Responses getting less focused
• Need to restart sessions more often
• Team members report context issues

Multi-file context anti-patterns

Five concrete creation-order anti-patterns and their fixes. Use these as references when planning the order in which files will be written.

Anti-pattern 1: JS modules before the main app file

Wrong:

1. Create utils.js
2. Create helpers.js
3. Create api.js
4. Create app.js (main file that imports all the above)
Problem: Had to keep going back to app.js to add imports

Right:

1. Think about module structure
2. Create app.js (with import statements planned)
3. Create utils.js (knowing what app.js needs)
4. Create helpers.js (knowing what app.js needs)
5. Create api.js (knowing what app.js needs)
Benefit: app.js structured correctly from the start

Anti-pattern 2: Inline styles then extract later

Wrong:

1. Create index.html with inline styles
2. Create about.html with inline styles
3. Realize styles are duplicated
4. Extract to styles.css
5. Update all HTML files to reference it
Problem: Redundant work, had to edit multiple files

Right:

1. Think: These pages will share styling
2. Create styles.css first
3. Create HTML files that reference styles.css
Benefit: No duplication, no refactoring needed

Anti-pattern 3: Components before data structure

Wrong:

1. Create UserProfile.jsx component
2. Create UserList.jsx component
3. Realize data structure is unclear
4. Go back and modify components to match data
Problem: Components built on assumptions

Right:

1. Think about data structure first
2. Create types.js or schema.js
3. Create components that use defined data structure
Benefit: Components built correctly from the start

Anti-pattern 4: Pages before shared layout

Wrong:

1. Create home.html with full layout
2. Create about.html with full layout
3. Realize layout should be shared
4. Extract to layout component/template
5. Refactor all pages
Problem: Major refactoring required

Right:

1. Think: Pages will share layout
2. Create layout.html or Layout component
3. Create pages that use the layout
Benefit: DRY from the start

Anti-pattern 5: Config files last

Wrong:

1. Create multiple files with hardcoded values
2. Realize config should be centralized
3. Create config.js
4. Update all files to use config
Problem: Config scattered, hard to change

Right:

1. Think: What values will be used across files?
2. Create config.js first
3. Create other files that import config
Benefit: Centralized configuration from start

Claude Code CLI tooling

Bonus features only available when using Claude Code CLI. Web and API users can skip this reference.

Generate CLAUDE.md

Create a context-optimized CLAUDE.md for your project:

python scripts/generate_claude_md.py --type [TYPE] --output ./CLAUDE.md

Available types:

• general - general-purpose projects
• backend - API/service projects
• frontend - web applications
• fullstack - full-stack applications
• data - data science / ML projects
• library - library / package development

Claude Code reads CLAUDE.md automatically, providing persistent project guidance across sessions.

Create subagents

For recurring tasks, create dedicated subagents:

python scripts/create_subagent.py [NAME] --type [TYPE] --output [DIR]

Types:

• researcher - documentation searches with deep analysis
• tester - test execution with failure analysis
• analyzer - code analysis with architectural insights
• builder - build / deployment tasks
• deep_analyzer - complex decisions requiring extensive thinking (recommended for architecture, tech choices, design patterns)

This writes .claude/agents/[NAME].md. Invoke with:

/agent [NAME] [task description]

Built-in commands

• /clear - reset context between tasks
• /compact - compress context while preserving key decisions
• /continue - resume previous session
• /agent [NAME] - delegate task to a subagent with isolated context

Patterns

Deep-analysis delegation

1. /clear (start fresh)
2. /agent deep-analyzer "Ultrathink about [complex decision]"
3. [Receives well-reasoned analysis in ~200 tokens]
4. Make decision and implement
5. Main context stayed clean throughout

Research with thinking

1. /agent pattern-researcher "Research [topic] and think hard about implications"
2. [Subagent searches + thinks in isolation]
3. Review findings in main context
4. Proceed with informed decision

TDD with analysis

1. Write test in main context
2. /agent test-runner "Run test and think hard if it fails"
3. [Subagent analyzes root cause in isolation]
4. Implement fix based on analysis
5. /agent test-runner "verify"
6. If passing: commit and /clear

Architecture evolution

1. /agent analyzer "Think deeply about current architecture issues"
2. [Receives analysis: bottlenecks, technical debt, opportunities]
3. /agent deep-analyzer "Recommend evolution strategy"
4. Create EVOLUTION.md plan
5. /clear
6. Execute plan phase by phase

Large refactoring with thinking

1. /agent analyzer "Think hard about refactoring scope and risks"
2. [Receives risk assessment + strategy]
3. Create REFACTOR.md plan
4. /clear
5. For each file:
   - Load and refactor
   - /agent test-runner "analyze test results"
   - /clear before next

For detailed Claude Code patterns see subagent_patterns.md and context_strategies.md.

Scripts

generate_claude_md.py

python scripts/generate_claude_md.py --type TYPE --output PATH

Options:

• --type project type (general, backend, frontend, fullstack, data, library)
• --output output path (default: ./CLAUDE.md)

create_subagent.py

python scripts/create_subagent.py NAME --type TYPE --output DIR

Options:

• NAME agent name (e.g., test-runner, doc-searcher)
• --type agent type (researcher, tester, analyzer, builder, deep_analyzer)
• --output output directory (default: current directory)

Context Management Strategies

Detailed workflows and strategies for managing context efficiently in Claude Code.

Understanding Context Usage

Context window size:

• Standard: 200K tokens (~150K words)
• Extended (API): 1M tokens (~750K words)

What consumes context:

• Conversation history (messages back and forth)
• File contents loaded into context
• Tool call results (bash output, test results, etc.)
• CLAUDE.md configuration
• Extended thinking blocks

Context awareness: Claude Sonnet 4.5 tracks remaining context and reports it with each tool call.

Core Commands

/clear - Reset Context

When to use:

• Between major features or tasks
• After completing a self-contained piece of work
• When switching between different parts of the codebase
• If you notice Claude getting distracted or referencing old context

Example workflow:

1. Complete feature A
2. Run tests and commit
3. /clear
4. Start feature B with fresh context

/compact - Compress Context

When to use:

• Before starting complex multi-step work
• When approaching context limits (~80% full)
• To preserve key decisions while clearing clutter

What it does: Summarizes conversation history while retaining key information.

Example workflow:

1. Long research and planning session
2. /compact "Summarize architecture decisions and open TODOs"
3. Continue with implementation

/continue - Resume Session

When to use:

• Returning to previous work
• After a break
• To pick up where you left off

Combines well with:

claude --continue  # Resume last session in current project

Strategy 1: Task Isolation

Goal: Keep each task in its own context bubble.

Workflow:

1. Start task → /clear (if needed)
2. Use subagents for research/analysis
3. Main context focuses on implementation
4. Complete and test
5. /clear before next task

When to use:

• Multiple independent features
• Bug fixes that don't require historical context
• Refactoring isolated modules

Benefits:

• Each task starts with clean slate
• No cross-contamination between tasks
• More predictable context usage

---

Strategy 2: Progressive Context Management

Goal: Build up context deliberately, clearing non-essential information.

Workflow:

1. Research phase
   - Subagents search and analyze
   - Main context reviews summaries
   
2. Planning phase
   - "think hard" to create plan
   - Save plan to document/issue
   
3. /compact "Keep architecture decisions and plan"
   
4. Implementation phase
   - Reference plan document
   - Focus on current file/module
   
5. Testing phase
   - Subagent runs tests
   - Main context addresses failures
   
6. /clear before next feature

When to use:

• Large features requiring multiple steps
• Complex refactoring
• Projects with extensive research phase

Benefits:

• Intentional context building
• Clear phase transitions
• Preserved key decisions

---

🚨 CRITICAL GUIDELINES

Windows File Path Requirements

MANDATORY: Always Use Backslashes on Windows for File Paths

When using Edit or Write tools on Windows, you MUST use backslashes (\) in file paths, NOT forward slashes (/).

Examples:

• ❌ WRONG: D:/repos/project/file.tsx
• ✅ CORRECT: D:\repos\project\file.tsx

This applies to:

• Edit tool file_path parameter
• Write tool file_path parameter
• All file operations on Windows systems

Documentation Guidelines

NEVER create new documentation files unless explicitly requested by the user.

• Priority: Update existing README.md files rather than creating new documentation
• Repository cleanliness: Keep repository root clean - only README.md unless user requests otherwise
• Style: Documentation should be concise, direct, and professional - avoid AI-generated tone
• User preference: Only create additional .md files when user specifically asks for documentation

---

Strategy 3: Parallel Workstreams

Goal: Work on multiple aspects simultaneously using subagents.

Workflow:

1. Main context: High-level orchestration
2. Subagent A: Frontend work
3. Subagent B: Backend work  
4. Subagent C: Test execution
5. Main context: Integration and coordination

When to use:

• Full-stack features
• Multi-component changes
• When different aspects are independent

Benefits:

• Efficient use of subagent isolation
• Parallel progress
• Main context stays focused on coordination

---

Strategy 4: Test-Driven Context Management

Goal: Keep context focused on current test/implementation cycle.

Workflow:

1. Write test in main context
2. /agent test-runner "run new test"
3. Implement feature to pass test
4. /agent test-runner "run test suite"
5. If fail → fix in main context
6. If pass → commit and /clear

When to use:

• TDD workflows
• Bug fixes with test coverage
• API endpoint development

Benefits:

• Tight feedback loop
• Context stays focused on current test
• Test output doesn't clutter main context

---

Strategy 5: Documentation-First Development

Goal: Use CLAUDE.md as persistent memory across sessions.

Setup:

# CLAUDE.md

## Current Focus
Sprint goal: User authentication system

## Recent Decisions
- Using JWT with refresh tokens
- PostgreSQL for user storage
- Redis for session management

## Next Tasks
- [ ] Implement token refresh endpoint
- [ ] Add rate limiting
- [ ] Write integration tests

## Architecture Notes
[Key decisions that inform all work]

Workflow:

1. CLAUDE.md provides persistent context
2. Each session references current focus
3. Update CLAUDE.md with new decisions
4. /clear frequently - CLAUDE.md persists

When to use:

• Multi-day projects
• Team collaboration (CLAUDE.md in git)
• Complex projects needing persistent memory

Benefits:

• Survives /clear commands
• Shared team knowledge
• Consistent across sessions

---

Scenario-Based Strategies

Scenario: Large Refactoring

Challenge: Need broad codebase understanding but context fills quickly.

Strategy:

1. Subagent: "Map all files using old pattern"
2. Review map, create refactoring plan
3. Save plan to REFACTOR.md
4. /clear
5. For each file:
   a. Load file
   b. Refactor based on plan
   c. Test
   d. /clear before next file

---

Scenario: Bug Investigation

Challenge: Unknown cause, need to search widely but track findings.

Strategy:

1. Create BUG_NOTES.md to track findings
2. Subagent: "Search logs for error X"
3. Document findings in BUG_NOTES.md
4. Subagent: "Analyze code paths that could cause X"
5. Document in BUG_NOTES.md
6. /compact "Keep bug theory and evidence"
7. Implement fix
8. /agent test-runner "verify fix"

---

Scenario: New Feature with Unknown Patterns

Challenge: Need to research existing patterns without cluttering context.

Strategy:

1. Subagent: "Find similar features in codebase"
2. Subagent: "Extract common patterns from those features"
3. Main context reviews patterns
4. "think about best approach for new feature"
5. Create implementation plan
6. /clear
7. Implement based on plan
8. Reference plan doc if needed

---

Scenario: Multi-File Feature

Challenge: Changes span many files, hard to keep all in context.

Strategy:

1. Create FEATURE.md with:
   - Overall design
   - File change checklist
   - Cross-file dependencies
   
2. For each file:
   a. Load just that file
   b. Reference FEATURE.md for context
   c. Make changes
   d. Test
   e. /compact if context getting full
   
3. Final integration test
4. /clear and move to next feature

---

Advanced Techniques

Technique: Context Checkpoints

Save key state to files before clearing:

1. Long planning session
2. "Create PLAN.md with our architecture decisions"
3. /clear
4. Reference PLAN.md during implementation

Technique: Layered Context Loading

Load information progressively as needed:

1. Start with just current file
2. If need more context: "show me the caller"
3. If need more: "show me the config"
4. Don't load everything upfront

Technique: Subagent Summarization

Use subagents to create digestible summaries:

Subagent: "Analyze all 50 test files and create a summary:
- Total coverage percentage
- Files with <50% coverage
- Most complex tests"

Then work from the summary, not the raw test files.

Technique: Incremental /compact

Compress context multiple times in long sessions:

1. Research phase → /compact "Keep research findings"
2. Planning phase → /compact "Keep findings and plan"
3. Implementation → /compact "Keep plan and decisions"

Monitoring Context Health

Signs context is getting cluttered:

• Claude references old, irrelevant information
• Responses become less focused
• Performance seems to degrade
• You're >80% through context budget

Remedies: 1. /compact for quick compression 2. /clear for fresh start 3. Move key info to files before clearing 4. Use subagents more aggressively

Best Practices Summary

1. Use /clear liberally between tasks 2. Front-load subagent usage for research 3. Document decisions in CLAUDE.md or files 4. Load files progressively as needed 5. Test in subagents to keep output isolated 6. /compact before complex multi-step work 7. Think first to plan before implementing 8. Reference plans instead of keeping full context 9. Batch similar operations in single subagent 10. Monitor context usage and respond proactively

Multi-file project planning

Detailed planning procedure for any project that touches three or more related files. The headline workflow lives in SKILL.md; this reference holds the full template, the optimal-order patterns by project type, and the verification checklists.

Two planning methods

Both are equally effective. Pick based on project complexity.

Method A: extended thinking

"Think hard about the architecture for this [project]:
- What files are needed and their purpose?
- What are shared dependencies?
- What is optimal creation order?
- What are cross-file references?
- What could go wrong?"

Best for: quick projects, straightforward structures, when planning fits in a thinking block.

Method B: planning document

Create ARCHITECTURE_PLAN.md (via Write tool or artifact):
- Files needed with purposes
- Shared dependencies
- Numbered creation order with reasoning
- Cross-file reference map
- Potential issues to avoid

Best for: complex projects, when you want a reference document, when planning is extensive.

Architecture plan template

ARCHITECTURE PLAN TEMPLATE

FILES NEEDED:
  - [filename]: [purpose]
  - [filename]: [purpose]

SHARED DEPENDENCIES (must be created first):
  - [dependency]: [what files need this]

CREATION ORDER (numbered with reasoning):
  1. [file] - Reason: [why this first]
  2. [file] - Reason: [why this second]
  3. [file] - Reason: [why this third]

CROSS-FILE REFERENCES:
  - [file A] references [file B] via [method]
  - [file C] imports [file D] via [method]

POTENTIAL ISSUES TO AVOID:
  - [what could go wrong]
  - [common mistake]

Filled example: portfolio website

ARCHITECTURE PLAN

FILES NEEDED:
  - styles.css: Shared styling for all pages
  - index.html: Home page with navigation
  - about.html: About page
  - projects.html: Portfolio showcase
  - contact.html: Contact form

SHARED DEPENDENCIES:
  - styles.css: All HTML files need this for consistent styling

CREATION ORDER:
  1. styles.css - Shared dependency, all HTML files will reference it
  2. index.html - Main entry point, establishes structure
  3. about.html - References styles.css which now exists
  4. projects.html - References styles.css which now exists
  5. contact.html - References styles.css which now exists

CROSS-FILE REFERENCES:
  - All HTML files link to styles.css via <link rel="stylesheet">
  - All HTML pages link to each other via <a href="...">

POTENTIAL ISSUES TO AVOID:
  - Creating HTML before CSS - would require going back to add links
  - Inline styles in HTML - would require extraction later
  - Inconsistent navigation - hard to maintain across files

Optimal file creation order

General principles:

1. Foundations first - shared dependencies before dependents (CSS before HTML, config before code, base classes before derived classes). 2. Core before features - essential files first (index.html before other pages, main.js before feature modules). 3. Structure before content - layout before details (HTML structure before detailed content, API skeleton before endpoint implementations).

Common patterns by project type:

Website project:
1. styles.css        (shared styling)
2. index.html        (home page - references styles.css)
3. about.html        (references styles.css)
4. projects.html     (references styles.css)
5. contact.html      (references styles.css)
6. script.js         (if needed)

React application:
1. package.json      (dependencies)
2. App.js            (main component)
3. components/Header.js
4. components/Footer.js
5. pages/Home.js
6. pages/About.js
7. styles/main.css

Backend API:
1. config.js         (configuration)
2. database.js       (DB connection)
3. models/User.js    (data models)
4. routes/auth.js    (route handlers)
5. routes/api.js
6. server.js         (entry point)

Token-savings illustration

Context-window capacity: with planning you can complete ~16-17 medium projects per 200K window vs ~7-8 without (2.1x effective increase).

Step 3: create files with awareness

As each file is written:

• Reference what was already created.
• Note what future files will depend on this one.
• Keep naming and structure consistent.
• Add comments about dependencies where helpful.

Step 4: verify

File-path verification

- CSS links: <link href="styles.css"> (not "style.css" or "css/styles.css")
- JS scripts: <script src="script.js">
- Images: <img src="image.png">
- Relative paths match actual file structure

Reference-loading verification

- HTML files find the CSS file
- JavaScript imports resolve correctly
- No 404 errors for missing files
- Correct syntax in link / script tags

Navigation verification (for websites)

- All navigation links point to correct files
- Links use correct relative paths
- No broken navigation
- Back / forward navigation works logically

Cross-file reference verification

- Components import correctly
- Modules can access exported functions
- Shared utilities are accessible
- API calls reference correct endpoints

Consistency verification

- Naming conventions consistent
- Styling uniform (if using shared CSS)
- Code structure follows same patterns
- Documentation style matches across files

Filled verification: portfolio website

After creating styles.css, index.html, about.html, projects.html, contact.html:

[OK] All HTML files have <link rel="stylesheet" href="styles.css">
[OK] styles.css exists and has content
[OK] Navigation links:
     - index.html links to about.html, projects.html, contact.html
     - All other pages link back to index.html
[OK] All pages use consistent styling from styles.css
[OK] No broken links or missing file references

Result: project structure verified, ready to use.

If verification fails, fix issues before considering the project complete.

When to use this planning approach

Always plan first for:

• Websites with multiple pages (3+ HTML files)
• Applications with multiple components
• Projects with shared dependencies (CSS, config files)
• API implementations with multiple endpoints
• Documentation sets with multiple files
• Any project where files reference each other

Skip planning for:

• Single-file creations
• Truly independent files with no relationships
• Simple, obvious structures

Post-project reflection

1. Did you plan before creating files? [Yes/No]
2. How many files did you create? [Number]
3. Did you have to refactor or fix file references? [Yes/No]
4. If you planned first:
   - Estimated context used: ~[2,500-4,500] tokens for [3-8] files
5. If you skipped planning:
   - You likely used: ~[6,000-12,000] tokens
   - Potential savings missed: ~[3,500-7,500] tokens

Success indicators:

• Created foundation files (CSS, config) before dependent files.
• No major refactoring needed after file creation.
• All file references worked on first try.
• Could describe file creation order before starting.
• Spent more time planning than fixing.

Improvement signals:

• Had to go back and add shared dependencies.
• Needed to refactor file structure after creation.
• Found broken references between files.
• Created files in no particular order.
• Spent more time fixing than planning.

Subagent Patterns

Common patterns and best practices for using subagents in Claude Code, with emphasis on thinking delegation for context efficiency.

The Thinking Delegation Paradigm

Core insight: Subagents have isolated context windows. When subagents use extended thinking, that reasoning happens in THEIR context, not the main session's context.

This enables:

• Deep analysis (5K+ thinking tokens)
• Main context receives summaries (~200 tokens)
• 23x context efficiency while maintaining analytical rigor
• Sustainable long sessions with multiple complex analyses

The architecture:

Main Session: Makes decisions, stays focused
    ↓ delegates with thinking trigger
Subagent: Uses extended thinking in isolation (5K tokens)
    ↑ returns summary
Main Session: Receives actionable conclusion (200 tokens)

Context math:

• Traditional: 7K tokens per analysis in main context
• With delegation: 300 tokens per analysis in main context
• Efficiency gain: 23x

Thinking-Enabled Subagent Types

Deep Analyzer (Type: deep_analyzer)

Purpose: Complex decisions requiring extensive analysis

What it does:

• ALWAYS uses "ultrathink" for analysis
• Evaluates multiple approaches
• Considers tradeoffs and implications
• Returns well-reasoned recommendations

When to use:

• Architecture decisions
• Technology evaluations
• Design pattern selection
• Performance optimization strategies
• Security assessments
• Refactoring approach planning

Example usage:

/agent architecture-advisor "Should we use microservices or modular monolith 
for a 10M user e-commerce platform with 8 developers?"

[Subagent thinks deeply in isolation - 5K tokens]
[Returns to main: ~200 token summary with recommendation]

Pattern Researcher (Type: researcher)

Purpose: Research with analytical thinking

What it does:

• Searches documentation/code
• Uses "think hard" for multi-source analysis
• Synthesizes insights with reasoning
• Returns analysis, not just data

When to use:

• API pattern research
• Best practice discovery
• Technology comparison
• Design pattern evaluation

Example usage:

/agent pattern-researcher "Research authentication patterns in our codebase 
and think hard about which approach fits our scale requirements"

[Subagent searches + analyzes - 3K tokens thinking]
[Returns: Summary of patterns with reasoned recommendation]

Code Analyzer (Type: analyzer)

Purpose: Architectural insights and deep code analysis

What it does:

• Analyzes code structure
• Uses "think harder" for architecture
• Identifies implications and opportunities
• Returns actionable insights

When to use:

• Architecture assessment
• Technical debt identification
• Performance bottleneck analysis
• Refactoring opportunity discovery

Example usage:

/agent code-analyzer "Think deeply about our authentication system's 
architecture and identify improvement opportunities"

[Subagent analyzes + thinks - 4K tokens]
[Returns: Key findings with prioritized recommendations]

Test Analyzer (Type: tester)

Purpose: Test execution with failure analysis

What it does:

• Runs test suites
• Uses "think hard" when tests fail
• Analyzes root causes
• Returns actionable diagnostics

When to use:

• Test suite execution
• Failure diagnosis
• Regression analysis
• Coverage assessment

Example usage:

/agent test-analyzer "Run the auth test suite and if failures occur, 
think hard about root causes"

[Subagent runs tests, analyzes failures - 2K tokens thinking]
[Returns: Test status + root cause analysis if needed]

Core Principles

Subagents have isolated context windows - They only send relevant information back to the main orchestrator, not their full context. This makes them ideal for tasks that generate lots of intermediary results.

When to use subagents:

• Searching through large codebases
• Analyzing multiple files for patterns
• Research tasks with extensive documentation
• Running tests or builds
• Any investigation that doesn't need full project context

When NOT to use subagents:

• Quick single-file edits
• Simple queries that need immediate response
• Tasks requiring full project context for decision-making

Common Patterns

Pattern 1: Research → Plan → Implement

Main Context:

1. "Use a subagent to search our codebase for similar authentication implementations"
2. [Review subagent findings]
3. "think about the best approach based on those examples"
4. [Implement in main context]

Why it works: Research generates lots of search results that would clutter main context. Main agent only sees the summary.

---

Pattern 2: Parallel Investigation

Main Context:

"Spin up three subagents:
1. One to analyze our error handling patterns
2. One to check test coverage
3. One to review documentation

Report back with key findings from each."

Why it works: Each subagent has its own context window. They can work in parallel without interfering with each other.

---

🚨 CRITICAL GUIDELINES

Windows File Path Requirements

MANDATORY: Always Use Backslashes on Windows for File Paths

When using Edit or Write tools on Windows, you MUST use backslashes (\) in file paths, NOT forward slashes (/).

Examples:

• ❌ WRONG: D:/repos/project/file.tsx
• ✅ CORRECT: D:\repos\project\file.tsx

This applies to:

• Edit tool file_path parameter
• Write tool file_path parameter
• All file operations on Windows systems

Documentation Guidelines

NEVER create new documentation files unless explicitly requested by the user.

• Priority: Update existing README.md files rather than creating new documentation
• Repository cleanliness: Keep repository root clean - only README.md unless user requests otherwise
• Style: Documentation should be concise, direct, and professional - avoid AI-generated tone
• User preference: Only create additional .md files when user specifically asks for documentation

---

Pattern 3: Test-Driven Workflow

Main Context:

1. Write tests in main context
2. "Use a subagent to run the test suite and report results"
3. [Implement fixes based on failures]
4. "Subagent: run tests again"
5. [Repeat until passing]

Why it works: Test output can be verbose. Subagent filters it down to pass/fail status and specific failures.

---

Pattern 4: Build Verification

Main Context:

1. Make code changes
2. "Subagent: run the build and verify it succeeds"
3. [If build fails, review error]
4. [Fix and repeat]

Why it works: Build logs are long. Subagent only reports success/failure and relevant errors.

---

Pattern 5: Multi-File Analysis

Main Context:

"Use a subagent to:
1. Find all files using the old API
2. Analyze migration complexity
3. Return list of files and complexity assessment"

[Review findings]
"Create a migration plan based on that analysis"

Why it works: File searching and analysis stays in subagent. Main context gets clean summary for planning.

Usage Syntax

Starting a Subagent

/agent <agent-name> <task-description>

or in natural language:

"Use a subagent to [task]"
"Spin up a subagent for [task]"
"Delegate [task] to a subagent"

Pre-configured vs Ad-hoc

Pre-configured agents (stored in .claude/agents/):

/agent test-runner run the full test suite

Ad-hoc agents (created on the fly):

"Use a subagent to search the codebase for error handling patterns"

Example Subagent Configurations

Research Subagent

File: .claude/agents/researcher.md

# Researcher

Documentation and code search specialist

## Instructions

Search through documentation and code efficiently. Return only the most 
relevant information with specific file paths and line numbers. 
Summarize findings concisely.

## Allowed Tools
- read
- search
- web_search

## Autonomy Level
Medium - Take standard search actions autonomously

Test Runner Subagent

File: .claude/agents/test-runner.md

# Test Runner

Automated test execution and reporting

## Instructions

Execute test suites and report results clearly. Focus on:
- Pass/fail status
- Specific failing tests
- Error messages and stack traces
- Coverage metrics if available

## Allowed Tools
- bash
- read

## Autonomy Level
High - Execute tests fully autonomously

Code Analyzer Subagent

File: .claude/agents/analyzer.md

# Analyzer

Code analysis and pattern detection

## Instructions

Analyze code structure and identify:
- Duplicate patterns
- Complexity hotspots
- Dependency relationships
- Potential issues

Provide actionable insights with specific locations.

## Allowed Tools
- read
- search
- bash

## Autonomy Level
Medium - Analyze autonomously, ask before making suggestions

Anti-Patterns

❌ Using Subagents for Everything

Bad:

"Use a subagent to edit this single file"

Why: Overhead of subagent isn't worth it for simple tasks.

Good:

"Edit this file to add the new function"

---

❌ Not Providing Clear Task Scope

Bad:

"Use a subagent to look at the code"

Why: Too vague. Subagent doesn't know what to focus on.

Good:

"Use a subagent to search for all database query patterns and assess 
which ones are vulnerable to SQL injection"

---

❌ Expecting Full Context Transfer

Bad:

Main: [Long discussion about architecture]
Then: "Subagent: implement that plan we just discussed"

Why: Subagent doesn't have access to your conversation history.

Good:

"Subagent: implement the authentication module with:
- JWT tokens
- Refresh token rotation
- Rate limiting
Based on our existing user service patterns."

Performance Tips

1. Front-load research - Use subagents early for research, then implement in main context 2. Batch similar tasks - One subagent for all file searches, not separate subagents per file 3. Clear instructions - Be specific about what the subagent should return 4. Iterate in main context - Use main context for back-and-forth refinement 5. Trust the summary - Don't ask subagent to return full documents

Advanced: Chaining Subagents

Scenario: Complex analysis requiring multiple specialized agents

1. "Subagent: search for all API endpoints and list them"
2. [Review list]
3. "Subagent: for each endpoint in that list, check test coverage"
4. [Review coverage report]
5. "Subagent: analyze the untested endpoints and estimate testing effort"

Why chaining works: Each subagent builds on the previous results without cluttering the main context with intermediary data.

---

Thinking Delegation Patterns

Pattern 1: Deep Decision Analysis

Problem: Need to make complex architectural decision

Traditional approach (main context):

"Think deeply about microservices vs monolith"
[5K tokens of thinking in main context]

Thinking delegation approach:

/agent deep-analyzer "Ultrathink about microservices vs monolith 
for 10M user platform, 8 dev team, considering deployment, maintenance, 
scaling, and team velocity"

[Subagent's isolated context: 6K tokens of thinking]
[Main receives: 250 token summary + recommendation]

Context saved: 5,750 tokens (~97%)

---

Pattern 2: Research → Think → Recommend

Problem: Need to research options and provide reasoned recommendation

Workflow:

Step 1: Research phase
/agent pattern-researcher "Research state management libraries 
and think hard about tradeoffs"

[Subagent searches + analyzes in isolation]
[Returns: Options with pros/cons]

Step 2: Decision phase
/agent deep-analyzer "Based on these options, ultrathink and 
recommend best fit for our use case"

[Subagent thinks deeply in isolation]
[Returns: Recommendation with rationale]

Step 3: Implementation
[Main context implements based on recommendation]

Why it works: Research and analysis isolated, implementation focused

---

Pattern 3: Iterative Analysis Refinement

Problem: Need to analyze multiple aspects without context accumulation

Workflow:

Round 1: /agent analyzer "Think about performance implications"
[Returns summary to main]

Round 2: /agent analyzer "Think about security implications"  
[Returns summary to main]

Round 3: /agent deep-analyzer "Synthesize performance and security 
analyses, recommend approach"
[Returns final recommendation to main]

Main context: Make decision with 3 concise summaries (~600 tokens total)

vs Traditional:

"Think about performance" [3K tokens in main]
"Think about security" [3K tokens in main]
"Synthesize" [needs both analyses in context]
Total: 6K+ tokens

Context efficiency: 10x improvement

---

Pattern 4: Parallel Deep Analysis

Problem: Multiple independent analyses needed

Workflow:

/agent analyzer-1 "Think deeply about database options"
/agent analyzer-2 "Think deeply about caching strategies"
/agent analyzer-3 "Think deeply about API design patterns"

[Each analyzes in parallel, isolated contexts]
[Each returns summary]

/agent deep-analyzer "Synthesize these analyses into coherent architecture"
[Returns integrated recommendation]

Why it works: Multiple deep analyses happen without accumulating in main context

---

Pattern 5: Test-Driven Development with Thinking

Problem: TDD cycle fills context with test output and debugging analysis

Traditional TDD:

Write test → Run test (verbose output) → Debug (thinking in main) → Fix → Repeat
[Context fills with test output + debugging thinking]

Thinking delegation TDD:

1. Write test in main context (focused)
2. /agent test-analyzer "Run test, if failure think hard about root cause"
3. [Subagent runs + analyzes in isolation]
4. [Returns: Status + root cause analysis if needed]
5. Fix based on analysis in main context
6. /agent test-analyzer "Verify fix"
7. Repeat until passing

Why it works: Test output and failure analysis isolated, main context stays implementation-focused

---

Pattern 6: Refactoring with Deep Assessment

Problem: Large refactoring needs strategy without filling main context

Workflow:

Step 1: Assessment
/agent analyzer "Think deeply about refactoring scope, risks, 
and approach for legacy auth system"

[Subagent analyzes codebase + thinks in isolation - 4K tokens]
[Returns: Risk assessment + strategy - 300 tokens]

Step 2: Planning
Create REFACTOR.md in main context based on strategy

Step 3: Execution
/clear
For each module:
  - Refactor based on plan
  - /agent test-analyzer "verify changes"
  - Commit
  - /clear

Why it works: Deep analysis happens once (isolated), execution follows clean plan

---

Pattern 7: Compound Decision Making

Problem: Multi-layer decision with dependencies

Workflow:

Layer 1: Foundation decision
/agent deep-analyzer "Ultrathink: Relational vs NoSQL for our use case"
[Returns: Relational recommended]

Layer 2: Specific technology
/agent deep-analyzer "Given relational choice, ultrathink: 
PostgreSQL vs MySQL vs MariaDB"
[Returns: PostgreSQL recommended with reasoning]

Layer 3: Architecture details
/agent deep-analyzer "Given PostgreSQL, ultrathink: Replication 
strategy for our scale"
[Returns: Streaming replication recommended]

Main context: Has 3 clear decisions (~600 tokens total)

vs Traditional: All thinking would accumulate in main context (12K+ tokens)

---

Advanced Thinking Patterns

Meta-Pattern: Thinking Chain

For extremely complex decisions requiring multiple analytical lenses:

1. /agent deep-analyzer "Analyze from business perspective"
2. /agent deep-analyzer "Analyze from technical perspective"
3. /agent deep-analyzer "Analyze from security perspective"
4. /agent deep-analyzer "Analyze from cost perspective"
5. /agent deep-analyzer "Synthesize all perspectives and recommend"

Main context receives: 5 concise analyses → integrated recommendation
Total in main: ~1K tokens
vs Traditional: 25K+ tokens of accumulated thinking

Meta-Pattern: Thinking Cascade

When decision depends on answering prior questions:

Q1: /agent deep-analyzer "Should we build or buy?"
    [Returns: Build recommended because...]

Q2: /agent deep-analyzer "Given building, which framework?"
    [Returns: React recommended because...]

Q3: /agent deep-analyzer "Given React, which state management?"
    [Returns: Zustand recommended because...]

Each analysis builds on previous conclusion, not previous reasoning

---

Passive deep-thinking architecture

The key insight: extended thinking can happen in isolated contexts (subagents on Claude Code, thinking artifacts on web/API), keeping the main session lean while still getting deep analysis.

Architectural pattern

Main Session (Orchestrator)
├─ Stays high-level and focused
├─ Makes decisions based on summaries
└─ Delegates complex analysis

        ↓ delegates with thinking triggers ↓

Analysis Layer (Agents/Artifacts)
├─ Extended thinking happens HERE (5K+ tokens)
├─ Deep reasoning happens HERE
├─ Context-heavy work happens HERE
└─ Returns concise summaries UP (~200 tokens)

        ↑ returns actionable conclusions ↑

Main Session
└─ Receives well-reasoned recommendations
└─ Context stays clean for sustained work

How this achieves passive deep thinking

Without thinking delegation:

• Extended thinking happens in main context.
• Reasoning accumulates (~5K tokens per analysis).
• Context fills quickly over long sessions.
• Eventually hits limits.

With thinking delegation:

• Subagents/artifacts do extended thinking in isolation.
• Main context only receives summaries (~200 tokens).
• Can sustain 25+ analyses before context issues.
• Deep thinking happens passively through architecture.

Key benefit: You get the depth of extended thinking without the context cost.

Implementation by environment

Claude Code: thinking subagents

# Create a deep analyzer for complex decisions
python scripts/create_subagent.py architecture-advisor --type deep_analyzer

# Create thinking-enabled researcher
python scripts/create_subagent.py pattern-researcher --type researcher

Usage:

Main session: "I need to decide between microservices and monolith"
↓
/agent architecture-advisor "Analyze microservices vs monolith
for an e-commerce platform with 10M users, considering team size
of 8 developers"
↓
Subagent's isolated context:
  - Uses "ultrathink" automatically
  - 5K+ tokens of deep reasoning
  - Evaluates tradeoffs thoroughly
↓
Returns to main: "After deep analysis, I recommend starting with
a modular monolith because [3 key reasons]. Microservices would
add complexity your team size can't support yet."
↓
Main session: Receives actionable advice, context clean

Context saved: ~4,800 tokens per analysis.

Web/API: thinking artifacts

User: "Analyze the best database for this use case"

Claude: "I'll create a deep analysis artifact where I can think
through this thoroughly."

[Creates artifact: "database-analysis.md"]
[Inside artifact:
  - Extended thinking block (collapsed in UI)
  - Detailed analysis
  - Comparison tables
  - Final recommendation
]

Main conversation: "Based on the analysis artifact, I recommend
PostgreSQL because [2-sentence summary]. See artifact for complete
reasoning including performance comparisons and scaling considerations."

Why this works:

• Thinking is visually separated (in artifact).
• Main conversation stays summary-focused.
• User can reference artifact when needed.
• Conversational context stays lean.

When to delegate vs keep in main

Delegate to thinking agents/artifacts for:

• Architecture decisions
• Technology evaluations
• Complex tradeoff analysis
• Multi-factor comparisons
• Design pattern selection
• Performance optimization strategies
• Security assessment
• Refactoring approach planning

Keep in main context for:

• Simple implementation
• Quick queries
• Tactical decisions with obvious answers
• Tasks requiring full project context

Example: state management for React app

Traditional approach (main context):

User: "What state management should I use?"
Claude: [5K tokens of thinking in main context]
Claude: [Another 2K tokens explaining recommendation]
Total: ~7K tokens consumed

Thinking-delegation approach:

User: "What state management should I use for a large e-commerce app?"

Claude Code:
"This warrants deep analysis. Let me delegate to a deep analyzer."
/agent architecture-advisor "Think deeply about state management
options (Redux, Zustand, Jotai, Context) for large-scale e-commerce
with real-time inventory"

[Subagent uses ultrathink in isolated context - 5K tokens]
[Returns summary - 200 tokens]

Main context: "The advisor recommends Zustand for these reasons..."
Total in main: ~300 tokens

Context efficiency: 23x improvement while maintaining analytical depth.

Compound effect over long sessions

Without delegation:

• Analysis 1: 7K tokens
• Analysis 2: 7K tokens
• Analysis 3: 7K tokens
• Analysis 4: 7K tokens
• Analysis 5: 7K tokens
• Total: 35K tokens (17% of 200K context)

With delegation:

• Analysis 1: 300 tokens
• Analysis 2: 300 tokens
• Analysis 3: 300 tokens
• Analysis 4: 300 tokens
• Analysis 5: 300 tokens
• Total: 1.5K tokens (0.75% of 200K context)

Result: 23x more analyses in the same context window while maintaining analytical rigor.

Context troubleshooting

Symptoms you may see in long or complex sessions, with universal and environment-specific remedies.

"Responses are getting less focused"

Symptom: Claude references old, irrelevant information or responses drift off topic.

Solutions:

• Web/API: "Setting aside previous discussion, let's focus on..."
• Claude Code: /clear or /compact
• Universal: break task into new phases with clear boundaries

"Complex task feels overwhelming"

Symptom: unsure where to start, too many moving parts.

Solutions: 1. "think harder about breaking this into phases" 2. Create a planning artifact 3. Execute one phase at a time 4. Reference plan artifact as you go

"Conversation getting too long"

Symptom: long history, hard to track what's been decided.

Solutions:

• Web/API: create a decisions.md artifact to summarize key points
• Claude Code: /compact to compress history
• Universal: start a new conversation with "Previously we decided X, Y, Z. Now let's..."

"Need to maintain context across sessions"

Symptom: having to re-explain everything each time.

Solutions:

• Create artifacts documenting key decisions and context.
• Claude Code: use CLAUDE.md for persistent project memory.
• Start new sessions with "Continuing from previous work where we [brief summary]".

"Code keeps being regenerated instead of edited"

Symptom: small changes result in entire code rewrites.

Solutions: 1. Use artifacts for code. 2. Request specific edits: "Update the handle_request function to add validation". 3. Don't say "show me the code again" - reference the existing artifact.

"Responses include too much explanation"

Symptom: lengthy explanations when you just want output.

Solutions:

• Be explicit: "Just create the artifact, minimal explanation".
• "Output only, no commentary".
• "Concise response please".

"Extended thinking not being used"

Symptom: jumping straight to solutions without analysis.

Solutions:

• Explicitly request: "think hard about...".
• Use stronger triggers: "ultrathink about...".
• Ask for planning: "think about multiple approaches".

Universal best practices

Eight rules that apply regardless of environment (Web, API, Claude Code CLI).

1. Delegate complex analysis to isolated contexts

The single most powerful pattern for context efficiency.

Claude Code:

GOOD: /agent deep-analyzer "Ultrathink about [complex decision]"
BAD:  "Think about [complex decision]"   (happens in main context)

Web/API:

GOOD: "Create analysis artifact and ultrathink about [decision]"
BAD:  "Ultrathink about [decision]"      (thinking stays in conversation)

Benefit: ~5K tokens of reasoning happens in isolation, main context receives ~200 token summary. 23x context efficiency while maintaining analytical depth.

2. Use extended thinking for planning

Before diving into implementation:

"think hard about the approach for [task]"

Even better with delegation:

• Claude Code: delegate to deep_analyzer subagent.
• Web/API: use thinking artifact.

Benefit: reasoning stays out of main context, you get thoughtful plans.

3. Create artifacts for substantial content

Don't inline long code or documents in conversation:

GOOD: "Create a Python script artifact that [functionality]"
BAD:  "Show me the Python code for [functionality]"

Benefit: content lives in artifacts, not conversation history.

4. Break complex tasks into explicit phases

State phase transitions clearly:

"Phase 1 complete. Moving to Phase 2: [description]"

With thinking delegation:

Phase 1: /agent deep-analyzer "analyze approaches"
Phase 2: Implement based on analysis

Benefit: each phase has clear purpose and boundaries.

5. Document decisions in artifacts

Create persistent references:

"Create a decisions.md artifact tracking our key choices"

Benefit: you can reference decisions without re-explaining full context.

6. Progressive disclosure

Don't request everything at once:

GOOD: "First, analyze the requirements"
      "Now, design the data model"
      "Now, implement the core logic"

BAD:  "Analyze requirements, design data model, and implement everything"

Benefit: each step builds on the last without overwhelming context.

7. Use thinking for exploration

When uncertain about approach:

"ultrathink about multiple approaches and recommend the best one"

Even better: delegate to deep_analyzer (Claude Code) or thinking artifact (Web/API).

Benefit: deep analysis without context clutter.

8. Signal context resets

When changing direction:

"Setting aside the previous approach, let's try a different angle..."

Benefit: clear boundaries prevent old context from interfering.

Advanced patterns

Iterative refinement

1. "Create initial version of [artifact]"
2. Review
3. "Improve [specific aspect]"
4. Review
5. "Add [feature]"
6. Continue iterating

Multi-artifact projects

1. "Create architecture.md artifact"
2. "Create database-schema.sql artifact"
3. "Create api-spec.yaml artifact"
4. "Now implement based on these artifacts"

Thinking → document → execute

1. "ultrathink about [complex problem]"
2. "Document the decision in a plan artifact"
3. "Execute phase 1 of the plan"
4. Reference plan artifact as you continue

Chunked content generation

1. "Create outline artifact"
2. "Write introduction (add to artifact)"
3. "Write section 1 (add to artifact)"
4. Continue section by section

Common context-management workflows

These six workflows cover the recurring complex tasks across Claude Code and Web/API. Each one starts with a planning or delegation step, then proceeds in clearly named phases.

Workflow 0: Multi-file website/project creation (most common)

If the user said "create a website/app with multiple pages", you are in this workflow.

Mandatory sequence:

STEP 1: STOP AND THINK (always first)
   Output: "Think hard about the architecture for this [project]..."
   [Extended thinking plans: files needed, creation order, dependencies]

STEP 2: ANNOUNCE THE PLAN
   Output: "I'll create these files in this order:
            1. styles.css (shared styling)
            2. index.html (home page)
            3. about.html
            4. projects.html
            5. contact.html"

STEP 3: CREATE FOUNDATION FILES FIRST
   Create: styles.css

STEP 4: CREATE DEPENDENT FILES
   Create: index.html (references styles.css)
   Create: about.html (references styles.css)
   Create: projects.html (references styles.css)
   Create: contact.html (references styles.css)

STEP 5: VERIFY
   Check: All HTML files reference styles.css correctly

Example: portfolio website

User: "Create a portfolio website with home, about, projects, and contact pages"

Before creating any files, output:

"Let me think hard about the architecture first..."

[Extended thinking plans:
 - Files needed: index.html, about.html, projects.html, contact.html, styles.css
 - Optimal order: styles.css FIRST (shared dependency), then HTML pages
 - Dependencies: All HTML files reference styles.css
 - Structure: Simple multi-page site with shared stylesheet]

Then announce the plan:

"I'll create the files in this order:

1. styles.css - Shared styling for all pages
2. index.html - Home page (references styles.css)
3. about.html - About page (references styles.css)
4. projects.html - Projects page (references styles.css)
5. contact.html - Contact page (references styles.css)

This ensures dependencies are in place before files that need them."

Then create files in that exact order.

Wrong vs right

WRONG:
User: "Create a portfolio website with home, about, projects, and contact pages"
[Immediately creates index.html without thinking]
[Creates about.html]
[Creates projects.html]
[Realizes CSS should be shared, has to go back and add it]
This wastes effort and context.

RIGHT:
User: "Create a portfolio website with home, about, projects, and contact pages"
"Think hard about architecture..." [Plans first]
"I'll create in this order: CSS first, then HTML pages" [Announces plan]
[Creates styles.css]
[Creates HTML pages that reference styles.css]
Efficient - no redundant work.

Workflow 1: Complex decision-making

Claude Code:

User: "Should we use microservices or monolith?"

1. /agent deep-analyzer "Ultrathink about architecture choice
   for 10M user e-commerce platform, 8 dev team"
2. [Receives well-reasoned recommendation in main context]
3. Make decision based on analysis
4. Proceed with implementation

Web/API:

User: "Should we use microservices or monolith?"

1. "Create a deep-analysis.md artifact and ultrathink about this"
2. [Artifact contains extended thinking + conclusion]
3. Main conversation: "Based on analysis, recommend monolith because..."
4. Proceed with implementation

Context efficiency: deep thinking happens, main context stays clean.

Workflow 2: Complex feature development

Phase 1: Architecture analysis
Claude Code: /agent deep-analyzer "Think deeply about architecture for [feature]"
Web/API: "Create architecture-analysis artifact with deep thinking"
[Isolated thinking → summary to main]

Phase 2: Design planning
"Based on that analysis, create implementation plan artifact"
[Main context references analysis conclusions]

Phase 3: Implementation
"Implement component A based on the plan"
[Create code artifact]

Phase 4: Testing
Claude Code: /agent test-runner "Run tests and analyze failures"
Web/API: "Run tests" [test output in separate space]

Phase 5: Integration
"Integrate based on architecture plan"

Why it works: each phase has a clear purpose, thinking isolated where needed.

Workflow 3: Research & technology evaluation

Phase 1: Deep research
Claude Code: /agent pattern-researcher "Research and think hard about
  authentication approaches, analyze tradeoffs"
Web/API: "Create research-findings artifact and think through options"

Phase 2: Synthesis
[Receives summary of findings]
"Create comparison table artifact"

Phase 3: Recommendation
Claude Code: /agent deep-analyzer "Based on research, recommend approach"
Web/API: "Based on research artifact, ultrathink and recommend"

Phase 4: Implementation
"Implement recommended approach"

Why it works: research and deep analysis isolated, implementation focused.

Workflow 4: Code generation & iteration

1. "Create a [language] script that [functionality]"
   → Artifact created

2. "Add [feature] to the script"
   → Artifact updated

3. "Optimize the [specific part]"
   → Targeted update

4. "Add error handling"
   → Incremental improvement

Why it works: all code lives in the artifact; conversation stays focused on what to change.

Workflow 5: Refactoring with analysis

Claude Code:

1. /agent analyzer "Think hard about refactoring approach
   for legacy auth system"
2. [Receives analysis in main: strategy, risks, order]
3. "Create REFACTOR.md plan based on analysis"
4. /clear
5. For each module:
   - Refactor according to plan
   - /agent test-runner "verify changes"
   - Commit
   - /clear before next

Web/API:

1. "Create refactoring-analysis artifact, think deeply about approach"
2. [Artifact has thinking + strategy]
3. "Create refactoring-plan artifact based on analysis"
4. Implement module by module
5. Reference plan artifact as you work

Why it works: deep analysis happens once (isolated), execution follows a clean plan.