Mortdecai
9ff8e915b8
User-agnostic, shareable AI-assisted development workflow distilled from 26+ real projects. Includes 9 composable rules, 4 project templates, pre-push secret scanning hook, 3 methodology guides, and customization docs. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
5.7 KiB
Context & Session Management
Effective context management is critical for AI coding assistant performance. Apply these patterns automatically.
Thinking Modes
AI coding assistants support different thinking depths. Use the appropriate mode for the task:
| Mode | Effort | When to Use |
|---|---|---|
| Light | ~4k tokens | Simple tasks, quick fixes, routine operations |
| Medium | ~8k tokens | Moderate complexity, single-file changes |
| Deep | ~16k tokens | Multi-file changes, architectural decisions |
| Maximum | ~32k tokens | Complex problems, deep analysis, novel solutions |
Mode Selection Guidelines
Light thinking for:
- Bug fixes with obvious solutions
- Adding simple functions
- Documentation updates
- Routine git operations
Medium thinking for:
- Implementing defined features
- Code review of single files
- Debugging with clear symptoms
- Refactoring within a module
Deep thinking for:
- Features touching multiple files
- Debugging with unclear root cause
- API design decisions
- Integration work
Maximum thinking for:
- Architectural planning
- Complex algorithm design
- Unfamiliar codebases (initial exploration)
- Multi-system integration
- Research synthesis
Context Budget Awareness
Understanding Your Budget
AI assistant context windows are NOT all available for work:
| Component | Approximate Tokens | Notes |
|---|---|---|
| Tool definitions | ~25-30k | Loaded at startup |
| Auto-loaded rules | ~3-5k | From .claude/rules/ |
| Plugins | ~3-5k | If installed |
| CLAUDE.md | ~1-2k | Project instructions |
| Startup overhead | ~35-45k | Before any work begins |
| Working context | ~125-165k | What's actually available |
When Quality Degrades
Quality degradation is gradual, not a cliff. Watch for these symptoms:
- Forgetting earlier instructions
- Repeating previously rejected approaches
- Missing obvious connections between files
- Declining code quality
- Ignoring established patterns
Fresh Session vs Compacting
| Situation | Recommendation |
|---|---|
| Iterative refinement of same feature | Let it compact, continuity helps |
| Switching to unrelated task | Fresh session |
| Quality noticeably declining | Fresh session |
| Deep in complex debugging | Let it compact, context is valuable |
| After completing major milestone | Fresh session (clean slate) |
| AI contradicting itself | Fresh session |
Key principle: Important context should live in files, not just conversation history. If you've been writing decisions to CLAUDE.md, task notes, and code to files, then a fresh session can reload what matters.
Execution Readiness Check
Before starting implementation of 3+ tasks, verify context budget.
| Context Used | Action |
|---|---|
| < 70% | Proceed with implementation |
| 70-80% | Ask: "We have N tasks remaining and context is at ~X%. Proceed now or defer to a fresh session?" |
| > 80% | Default to deferring. Commit current work, create handoff doc, start fresh. |
Why this exists: At high context usage, quality degrades gradually -- forgotten instructions, repeated mistakes, missed connections. Starting multi-task execution late in a session risks compounding errors.
Persistence Strategy
Don't rely on conversation history for important context.
| Context Type | Where to Persist | When Loaded |
|---|---|---|
| Project patterns, constraints | CLAUDE.md | Every session |
| Architectural decisions | docs/decisions/*.md |
On demand |
| Current task learnings | Task notes/descriptions | With task |
| Session discoveries | SESSION.md or work log | On demand |
| Pre-compaction state | .claude/sessions/ |
On session start |
| Code rationale | Code comments | With file |
Good: Add stable project patterns to CLAUDE.md (sparingly)
Good: Create docs/decisions/YYYY-MM-DD-topic.md for ADRs
Good: Put "why" comments in code
Bad: Dump session notes into CLAUDE.md (bloats startup)
Bad: Assume the AI remembers 30 messages ago
Bad: Reference "what we discussed earlier" without specifics
CLAUDE.md should stay lean -- it's loaded every session. Use it for stable, long-term project context only.
Sub-Agent Best Practices
Sub-agents get fresh context windows. Use them for:
| Task Type | Use Sub-Agent? | Why |
|---|---|---|
| Isolated research | Yes | Fresh context, focused scope |
| Code review | Yes | Independent perspective |
| Validation/testing | Yes (blind) | Unbiased verification |
| Multi-step implementation | Sometimes | Break at natural boundaries |
| Quick fixes | No | Overhead not worth it |
Blind Validator Pattern: For testing, spawn a separate agent that only sees test results, not the implementation. This prevents bias in verification.
Token-Conscious Habits
- Read selectively: Use line limits when reading large files
- Summarize findings: Don't paste entire files into responses
- Use project indexes: Reference structure, not full content
- Tier documentation lookups: Knowledge -> lightweight fetch -> heavy docs
- Clear completed context: Start fresh after major milestones
Quick Reference
Context feeling sluggish?
|-- Quality actually declining? (forgetting, contradicting, poor output)
| |-- Yes, same task: Spawn sub-agent for fresh perspective
| |-- Yes, new task: Start fresh session
| |-- No, just anxious: Continue working
|
|-- Switching task domains?
| |-- Related work: Continue
| |-- Completely different: Fresh session
|
|-- Major milestone complete?
| |-- Natural breakpoint: Good time for fresh session
|
|-- About to execute 3+ tasks?
|-- Context < 70%: Proceed
|-- Context 70-80%: Ask user
|-- Context > 80%: Handoff doc + fresh session