init: scaffold Seth-Workflow-April-2026
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>
This commit is contained in:
Mortdecai
@@ -0,0 +1,159 @@
|
||||
# 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
|
||||
|
||||
1. **Read selectively**: Use line limits when reading large files
|
||||
2. **Summarize findings**: Don't paste entire files into responses
|
||||
3. **Use project indexes**: Reference structure, not full content
|
||||
4. **Tier documentation lookups**: Knowledge -> lightweight fetch -> heavy docs
|
||||
5. **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
|
||||
```
|
||||
Reference in New Issue
Block a user