mirror of
https://github.com/Donchitos/Claude-Code-Game-Studios.git
synced 2026-06-27 04:51:46 +00:00
e289ce906f
* Add context resilience: file-backed state, incremental writing, auto-recovery Prevents "prompt too long" crashes from killing sessions by persisting work to disk incrementally instead of relying on conversation memory. Changes: - pre-compact.sh: dumps session state before context compression - session-start.sh: detects active.md for crash recovery - session-stop.sh: archives and clears active.md on clean shutdown - context-management.md: file-backed state as primary strategy - 9 agents updated with incremental section writing protocol (game-designer, systems-designer, economy-designer, narrative-director, level-designer, world-builder, writer, art-director, audio-director) - CLAUDE.md: trimmed redundant imports (10 → 5) to reduce token overhead - design-docs.md rule: enforces incremental writing pattern - .gitignore: excludes ephemeral session state files - directory-structure.md: documents session-state/ and session-logs/ - COLLABORATIVE-DESIGN-PRINCIPLE.md: documents incremental writing pattern Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Add AskUserQuestion integration across collaborative protocols Explicitly reference the AskUserQuestion tool in all collaborative agent definitions, protocol templates, team orchestrator skills, and the master principle doc. Introduces the Explain-then-Capture pattern: agents write full expert analysis in conversation, then call AskUserQuestion with concise labels to capture decisions via structured UI. 26 files updated: - 3 protocol templates (design, leadership, implementation) - 14 agent definitions (10 design + 3 leadership + writer) - 8 orchestrator skills (brainstorm + 7 team-*) - 1 master principle doc (COLLABORATIVE-DESIGN-PRINCIPLE.md) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Add /design-systems skill: concept-to-GDD decomposition workflow Bridges the gap between game concept and per-system design documents. Professional studios use systems enumeration + dependency sorting between concept and feature docs — skipping this step is one of the most expensive mistakes (systems discovered during production cost 5-10x more to add). New files: - .claude/skills/design-systems/SKILL.md — 7-phase orchestration skill (enumerate systems, map dependencies, assign priorities, write GDDs) - .claude/docs/templates/systems-index.md — master tracking template Flow integration (7 existing skills updated): - brainstorm, start, setup-engine, design-review, gate-check, project-stage-detect, game-concept template all reference /design-systems at the appropriate workflow touchpoints Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Fix cross-platform bugs, add missing tool permissions, and update docs for v0.2.0 Hooks: fix \s → [[:space:]] in grep -E fallbacks (3 files), fix detect-gaps.sh empty-variable bug, fix log-agent.sh field name (agent_name → agent_type), harden validate-push.sh with explicit $MATCHED_BRANCH, convert for-in loops to while-read for space-safe iteration, add POSIX head -n syntax, increase PreCompact timeout, widen session-stop log window. Skills: add AskUserQuestion to 10 skills and TodoWrite to 8 multi-phase skills. Fix project-stage-detect template/output paths, tech-artist → technical-artist. Docs: add /design-systems to all references (README, quick-start, workflow guide, skills-reference), update skill count 35 → 36, remove stale AI artifacts from COLLABORATIVE-DESIGN-PRINCIPLE.md, add AskUserQuestion note to examples README. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
90 lines
3.7 KiB
Markdown
90 lines
3.7 KiB
Markdown
# Context Management
|
|
|
|
Context is the most critical resource in a Claude Code session. Manage it actively.
|
|
|
|
## File-Backed State (Primary Strategy)
|
|
|
|
**The file is the memory, not the conversation.** Conversations are ephemeral and
|
|
will be compacted or lost. Files on disk persist across compactions and session crashes.
|
|
|
|
### Session State File
|
|
|
|
Maintain `production/session-state/active.md` as a living checkpoint. Update it
|
|
after each significant milestone:
|
|
|
|
- Design section approved and written to file
|
|
- Architecture decision made
|
|
- Implementation milestone reached
|
|
- Test results obtained
|
|
|
|
The state file should contain: current task, progress checklist, key decisions
|
|
made, files being worked on, and open questions.
|
|
|
|
After any disruption (compaction, crash, `/clear`), read the state file first.
|
|
|
|
### Incremental File Writing
|
|
|
|
When creating multi-section documents (design docs, architecture docs, lore entries):
|
|
|
|
1. Create the file immediately with a skeleton (all section headers, empty bodies)
|
|
2. Discuss and draft one section at a time in conversation
|
|
3. Write each section to the file as soon as it's approved
|
|
4. Update the session state file after each section
|
|
5. After writing a section, previous discussion about that section can be safely
|
|
compacted — the decisions are in the file
|
|
|
|
This keeps the context window holding only the *current* section's discussion
|
|
(~3-5k tokens) instead of the entire document's conversation history (~30-50k tokens).
|
|
|
|
## Proactive Compaction
|
|
|
|
- **Compact proactively** at ~60-70% context usage, not reactively at the limit
|
|
- **Use `/clear`** between unrelated tasks, or after 2+ failed correction attempts
|
|
- **Natural compaction points:** after writing a section to file, after committing,
|
|
after completing a task, before starting a new topic
|
|
- **Focused compaction:** `/compact Focus on [current task] — sections 1-3 are
|
|
written to file, working on section 4`
|
|
|
|
## Context Budgets by Task Type
|
|
|
|
- Light (read/review): ~3k tokens startup
|
|
- Medium (implement feature): ~8k tokens
|
|
- Heavy (multi-system refactor): ~15k tokens
|
|
|
|
## Subagent Delegation
|
|
|
|
Use subagents for research and exploration to keep the main session clean.
|
|
Subagents run in their own context window and return only summaries:
|
|
|
|
- **Use subagents** when investigating across multiple files, exploring unfamiliar code,
|
|
or doing research that would consume >5k tokens of file reads
|
|
- **Use direct reads** when you know exactly which 1-2 files to check
|
|
- Subagents do not inherit conversation history — provide full context in the prompt
|
|
|
|
## Compaction Instructions
|
|
|
|
When context is compacted, preserve the following in the summary:
|
|
|
|
- Reference to `production/session-state/active.md` (read it to recover state)
|
|
- List of files modified in this session and their purpose
|
|
- Any architectural decisions made and their rationale
|
|
- Active sprint tasks and their current status
|
|
- Agent invocations and their outcomes (success/failure/blocked)
|
|
- Test results (pass/fail counts, specific failures)
|
|
- Unresolved blockers or questions awaiting user input
|
|
- The current task and what step we are on
|
|
- Which sections of the current document are written to file vs. still in progress
|
|
|
|
**After compaction:** Read `production/session-state/active.md` and any files being
|
|
actively worked on to recover full context. The files contain the decisions; the
|
|
conversation history is secondary.
|
|
|
|
## Recovery After Session Crash
|
|
|
|
If a session dies ("prompt too long") or you start a new session to continue work:
|
|
|
|
1. The `session-start.sh` hook will detect and preview `active.md` automatically
|
|
2. Read the full state file for context
|
|
3. Read the partially-completed file(s) listed in the state
|
|
4. Continue from the next incomplete section or task
|