mirror of
https://github.com/Donchitos/Claude-Code-Game-Studios.git
synced 2026-06-27 13:01:50 +00:00
7d08e396e3
* Add UPGRADING.md migration guide and link from README Covers v0.1→v0.2 upgrade with three strategies (git merge, cherry-pick, manual copy), file safety categories, and post-upgrade verification steps. Structured to support future version sections. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Rename /design-systems to /map-systems + /design-system and fix all references Split the monolithic /design-systems skill into two focused skills: - /map-systems: systems decomposition and index creation - /design-system: guided section-by-section GDD authoring Updated all cross-references across 14 files: README, UPGRADING, WORKFLOW-GUIDE, quick-start, skills-reference, game-concept template, systems-index template, brainstorm, design-review, gate-check, project-stage-detect, setup-engine, and start skills. Fixed skill counts from 36 to 37 everywhere. Added /map-systems and /design-system to quick-start Paths A and B workflows. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Fix cross-reference gaps, broken hooks, and stale workflow chains - Fix log-agent.sh parsing agent_type instead of agent_name (always logged "unknown") - Fix GDD status lifecycle: design-system now writes Approved/Designed/In Review - Clean up settings.local.json vestigial Bash grants from development - Delete orphaned docs marked for removal in UPGRADING.md - Add /design-system to next-steps in /start, /brainstorm, /setup-engine - Fix WORKFLOW-GUIDE: add /map-systems + /design-system to Appendix C Workflow 1 - Fix invalid /map-systems map argument in WORKFLOW-GUIDE Step 2.1 - Update map-systems frontmatter to document [system-name] argument - Update commit hook to validate all 8 required GDD sections (was 5) - Update README template count 28 → 29, add 5 missing templates to quick-start Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Add custom status line with 7-stage production pipeline Introduces a status line showing context %, model name, and production stage at a glance. Aligns gate-check and project-stage-detect to a unified 7-stage model (Concept → Systems Design → Technical Setup → Pre-Production → Production → Polish → Release). Stage is determined by explicit override (production/stage.txt) or auto-detected from project artifacts. Epic/Feature/Task breadcrumb appears conditionally in Production+ stages via a structured STATUS block in active.md. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Add v0.2→v0.3 upgrade guide and PR validation test suite - UPGRADING.md: add v0.2.0→v0.3.0 section documenting breaking rename of /design-systems→/map-systems, new /design-system skill, statusline.sh, gate-check stage advancement, and safe-to-overwrite file list Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
108 lines
4.2 KiB
Markdown
108 lines
4.2 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.
|
|
|
|
### Status Line Block (Production+ only)
|
|
|
|
When the project is in Production, Polish, or Release stage, include a structured
|
|
status block in `active.md` that the status line script can parse:
|
|
|
|
```markdown
|
|
<!-- STATUS -->
|
|
Epic: Combat System
|
|
Feature: Melee Combat
|
|
Task: Implement hitbox detection
|
|
<!-- /STATUS -->
|
|
```
|
|
|
|
- All three fields (Epic, Feature, Task) are optional — include only what applies
|
|
- Update this block when switching focus areas
|
|
- The status line displays it as a breadcrumb: `Combat System > Melee Combat > Hitboxes`
|
|
- Remove or empty the block when no active work focus exists
|
|
|
|
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
|