strategy guide — current as of v3.0 · v3.0 in progress

# Choose the right context strategy

SigMap supports three modes: full, per-module, and hot-cold. This page shows exactly when to use each one, what token cost to expect, and how MCP changes the decision.

At a glance

## Quick comparison

Strategy | Always injected | Context loss | MCP required | Best fit
--- | --- | --- | --- | ---
full | ~4,000 tokens | No | No | Default for all IDEs and onboarding
per-module | ~100-300 tokens overview | No | No | Module-based projects, focused work
hot-cold | ~200-800 hot set | Cold files unless fetched | Yes for cold | Claude Code / Cursor with MCP

How to use

## Each strategy in detail

Use the same config file key for all modes. Switch mode, run once, and compare token output with --report.

### full

No context loss No MCP needed

Single output file with all signatures. Best if you want complete context all the time and do not want to manage additional files.

{ "strategy": "full", "maxTokens": 6000 }

### per-module

No context loss No MCP needed

Writes one file per top-level module plus a tiny overview. You inject only the module you are currently working on.

{ "srcDirs": ["server", "web", "desktop"], "strategy": "per-module" }

### hot-cold

Cold needs MCP Smallest always-on

Recently changed files stay hot and auto-injected. Everything else goes to context-cold.md and should be pulled via MCP when needed.

{ "strategy": "hot-cold", "hotCommits": 10, "diffPriority": true }

Case by case

## Real usage scenarios

Use this section to decide quickly based on your workflow, not just token numbers.

#### Scenario A: Fix a login bug

You edited auth files in the last few commits and need fast iteration.

Winner: hot-cold. Hot set already contains the files you are editing.

#### Scenario B: Cross-module question

You need frontend + backend context in one answer. MCP may or may not be available.

Winner: per-module. Load both module files, no context loss and no MCP dependency.

#### Scenario C: Team with MCP enabled

Claude Code / Cursor is standard across the team and MCP is always available.

Winner: hot-cold. Keep always-on tiny and fetch cold context only when needed.

#### Scenario D: Onboarding new engineers

Need broad project understanding quickly, with minimal setup complexity.

Winner: full. One file, complete picture, no additional workflow steps.

Decision tree

## Pick the right default for your team

1. No MCP in your IDE: choose full or per-module.
2. Module boundaries are clear: choose per-module.
3. MCP always available and active area is small: choose hot-cold.
4. Unsure: start with full, then move to per-module when output grows.

More detail

## Full reference docs

For complete migration steps, compatibility matrix, and advanced examples, use the full Markdown guide.

1. Detailed guide in repository: docs/CONTEXT_STRATEGIES.md
2. CLI reference and setup: Quick Start
3. MCP setup: docs/MCP_SETUP.md