mirror of
https://github.com/Donchitos/Claude-Code-Game-Studios.git
synced 2026-10-16 09:48:34 +00:00
DonchitosandClaude Opus 5
d05699707f
`project.yaml` at the repo root is now the single source of truth for a project's configuration, replacing `production/stage.txt`, `production/review-mode.txt` and `.claude/docs/technical-preferences.md` (all three still read as a fallback; nothing is force-deleted). **`modes.rigor` — one question instead of six.** `minimal`, `standard` or `full` fronts six knobs: `modes.workflow`, `docs.density`, `qa.level`, `modes.story_granularity`, `modes.review_mode` and `team.size`. It defaults to `minimal`, which is a change from 1.0's behaviour: the heavier tier was measured costing several times more to reach working code without producing a better result, and returning nothing when a fresh developer inherited the project. Pin `modes.rigor: standard` to keep 1.0's process level. Also in this release: - `/settings` to view or change any setting, and `project.local.yaml` for per-developer preferences that should not be committed. - `system_overrides` to hold one system to a higher standard than the rest of the project, and `testing.strict` to set per test type whether missing evidence blocks a story or warns. - A story that changes anything the player sees is not closed until the game has been launched, observed, and a screenshot retained in `production/qa/evidence/`. A parse check is not a run. This holds at every rigor level, including `minimal`, where automated tests are waived but the look is not. - The code root is engine-specific and enforced as such: Godot `src/`, Unity `Assets/`, Unreal `Source/<Module>/`. Two of the three will not build a project laid out any other way. - Migration tooling for existing projects: `.claude/scripts/migrate-v1-config.sh` converts a 1.0 layout, non-destructively by default, with a report to review before `--finalize` deletes anything. - Ask-before-write holds regardless of personal automation settings. Upgrading from 1.0 or earlier: see UPGRADING.md. Full list of changes: CHANGELOG.md. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016xvzG3i7pWQg4LjyDwWMXd
171 lines
7.4 KiB
Markdown
171 lines
7.4 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
|
|
|
|
**Create it from `.claude/docs/templates/session-state.md`** — the file has a
|
|
schema, and hooks depend on it.
|
|
|
|
Two regions, and the distinction is load-bearing:
|
|
|
|
| Region | Who reads it | Rule |
|
|
|--------|--------------|------|
|
|
| `<!-- STATUS -->` … `<!-- /STATUS -->` | `statusline.sh` (breadcrumb, Production+ only) | Keep the markers even when empty |
|
|
| `<!-- CHECKPOINT -->` … `<!-- /CHECKPOINT -->` | `session-start.sh` and `pre-compact.sh` | **Overwrite, never append.** Under ~25 lines — hooks inject it verbatim |
|
|
| Everything after `<!-- /CHECKPOINT -->` | humans, and an agent that wants detail | Free-form; no hook injects it |
|
|
|
|
The checkpoint holds: current task, next step, what it is blocked on, files in
|
|
progress, open questions. Write it so a cold reader can resume without opening
|
|
anything else.
|
|
|
|
> **Why the split.** One append-only file doing both jobs grows without bound —
|
|
> past 700 lines every consumer invents its own slice: a status line parsing a
|
|
> STATUS block nothing writes, `pre-compact` injecting `head -100` (12.7 KB, at
|
|
> the moment context is scarcest), `session-start` previewing `tail -20` — the
|
|
> opposite end. None was wrong, because nothing defined where
|
|
> the recoverable state lived. Now every consumer reads the named region, and
|
|
> the cost is fixed no matter how long the narrative grows.
|
|
|
|
**Rotation.** When the narrative passes ~200 lines, move it into
|
|
`production/session-logs/`:
|
|
|
|
```bash
|
|
bash .claude/scripts/rotate-session-state.sh # --dry-run to preview
|
|
```
|
|
|
|
The checkpoint stays, the narrative is appended to a dated log, nothing is
|
|
deleted. `session-start.sh` observes when rotation is due but never performs it.
|
|
|
|
### 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. (The project
|
|
stage is resolved from `project.stage` in `project.yaml`, falling back to
|
|
`production/stage.txt`.)
|
|
|
|
```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
|
|
|
|
## Deterministic Helpers — `.claude/scripts/`
|
|
|
|
The cheapest context saving is not summarising a document, it is **not reading it
|
|
at all**. When a question has a deterministic answer, a script should answer it
|
|
and the model should spend its budget on judgment instead.
|
|
|
|
Two directories, two purposes — reach for the right one:
|
|
|
|
| Directory | Purpose | Invoked by |
|
|
|---|---|---|
|
|
| `.claude/hooks/` | Event-driven — wired into `settings.json` and fired by Claude Code | the harness |
|
|
| `.claude/scripts/` | Manually invoked from a skill body | `bash .claude/scripts/<name>.sh` |
|
|
|
|
Current helpers:
|
|
|
|
- **`gdd-structure-check.sh`** — which of the 8 standard sections a GDD contains.
|
|
Replaces a full-document read per GDD, and cannot hallucinate a missing
|
|
section. Reports **presence only**; the caller applies the workflow tier.
|
|
- **`review-scope.sh`** — which GDDs changed since the last cross-review, plus
|
|
their declared dependencies. Replaces reasoning through git history.
|
|
|
|
Two rules when adding one:
|
|
|
|
1. **A skill invoking a script needs `Bash` in `allowed-tools`**, or the step
|
|
silently no-ops. A skill that only needs *resolved config* does not — use the
|
|
documented `` !`cmd` `` body form, which is preprocessing and is not gated by
|
|
`allowed-tools` (see `.claude/docs/config-resolution.md`).
|
|
2. **Emit observations, not verdicts.** A script that scores or judges will
|
|
eventually contradict a tier, mode, or per-system override it does not know
|
|
about. Report what is on disk and let the caller decide what it means.
|
|
|
|
## 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
|