添加 claude code game studios 到项目

2026-05-15 14:52:29 +08:00
parent dff559462d
commit a16fe4bff7
415 changed files with 78609 additions and 0 deletions
--- a/.claude/skills/reverse-document/SKILL.md
+++ b/.claude/skills/reverse-document/SKILL.md
@@ -0,0 +1,263 @@
+---
+name: reverse-document
+description: "Generate design or architecture documents from existing implementation. Works backwards from code/prototypes to create missing planning docs."
+argument-hint: "<type> <path> (e.g., 'design src/gameplay/combat' or 'architecture src/core')"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit, Bash
+model: sonnet
+# Read-only diagnostic skill — no specialist agent delegation needed
+---
+
+# Reverse Documentation
+
+This skill analyzes existing implementation (code, prototypes, systems) and generates
+appropriate design or architecture documentation. Use this when:
+- You built a feature without writing a design doc first
+- You inherited a codebase without documentation
+- You prototyped a mechanic and need to formalize it
+- You need to document "why" behind existing code
+
+---
+
+## Workflow
+
+## Phase 1: Parse Arguments
+
+**Format**: `/reverse-document <type> <path>`
+
+**Type options**:
+- `design` → Generate a game design document (GDD section)
+- `architecture` → Generate an Architecture Decision Record (ADR)
+- `concept` → Generate a concept document from prototype
+
+**Path**: Directory or file to analyze
+- `src/gameplay/combat/` → All combat-related code
+- `src/core/event-system.cpp` → Specific file
+- `prototypes/stealth-mech/` → Prototype directory
+
+**Examples**:
+```bash
+/reverse-document design src/gameplay/magic-system
+/reverse-document architecture src/core/entity-component
+/reverse-document concept prototypes/vehicle-combat
+```
+
+## Phase 2: Analyze Implementation
+
+**Read and understand the code/prototype**:
+
+**For design docs (GDD):**
+- Identify mechanics, rules, formulas
+- Extract gameplay values (damage, cooldowns, ranges)
+- Find state machines, ability systems, progression
+- Detect edge cases handled in code
+- Map dependencies (what systems interact?)
+
+**For architecture docs (ADR):**
+- Identify patterns (ECS, singleton, observer, etc.)
+- Understand technical decisions (threading, serialization, etc.)
+- Map dependencies and coupling
+- Assess performance characteristics
+- Find constraints and trade-offs
+
+**For concept docs (prototype analysis):**
+- Identify core mechanic
+- Extract emergent gameplay patterns
+- Note what worked vs what didn't
+- Find technical feasibility insights
+- Document player fantasy / feel
+
+## Phase 3: Ask Clarifying Questions
+
+**DO NOT** just describe the code. **ASK** about intent:
+
+**Design questions**:
+- "I see a [resource] system that depletes during [activity]. Was this for:
+  - Pacing (prevent spam)?
+  - Resource management (strategic depth)?
+  - Or something else?"
+- "The [mechanic] seems central. Is this a core pillar, or supporting feature?"
+- "[Value] scales exponentially with [factor]. Intentional design, or needs rebalancing?"
+
+**Architecture questions**:
+- "You're using a service locator pattern. Was this chosen for:
+  - Testability (mock dependencies)?
+  - Decoupling (reduce hard references)?
+  - Or inherited from existing code?"
+- "I see manual memory management instead of smart pointers. Performance requirement, or legacy?"
+
+**Concept questions**:
+- "The prototype emphasizes stealth over combat. Is that the intended pillar?"
+- "Players seem to exploit the grappling hook for speed. Feature or bug?"
+
+## Phase 4: Present Findings
+
+Before drafting, show what you discovered:
+
+```
+I've analyzed [path]/. Here's what I found:
+
+MECHANICS IMPLEMENTED:
+- [mechanic-a] with [property] (e.g. timing windows, cooldowns)
+- [mechanic-b] (e.g. interaction between two states)
+- [resource] system (depletes on [action], regens on [condition])
+- [state] system (builds up, triggers [effect])
+
+FORMULAS DISCOVERED:
+- [Output] = [formula using discovered variables]
+- [Secondary output] = [formula]
+
+UNCLEAR INTENT AREAS:
+1. [Resource] system — pacing or resource management?
+2. [Mechanic] — core pillar or supporting feature?
+3. [Value] scaling — intentional design or needs tuning?
+
+Before I draft the design doc, could you clarify these points?
+```
+
+Wait for user to clarify intent before drafting.
+
+## Phase 5: Draft Document Using Template
+
+Based on type, use appropriate template:
+
+| Type | Template | Output Path |
+|------|----------|-------------|
+| `design` | `templates/design-doc-from-implementation.md` | `design/gdd/[system-name].md` |
+| `architecture` | `templates/architecture-doc-from-code.md` | `docs/architecture/[decision-name].md` |
+| `concept` | `templates/concept-doc-from-prototype.md` | `prototypes/[name]/CONCEPT.md` or `design/concepts/[name].md` |
+
+**Draft structure**:
+- Capture **what exists** (mechanics, patterns, implementation)
+- Document **why it exists** (intent clarified with user)
+- Identify **what's missing** (edge cases not handled, gaps in design)
+- Flag **follow-up work** (balance tuning, missing features)
+
+## Phase 6: Show Draft and Request Approval
+
+**Collaborative protocol**:
+```
+I've drafted the [system-name] design doc based on your code and clarifications.
+
+[Show key sections: Overview, Mechanics, Formulas, Design Intent]
+
+ADDITIONS I MADE:
+- Documented [mechanic] as "[intent]" per your clarification
+- Added edge cases not in code (e.g., what if [resource] hits 0 mid-[action]?)
+- Flagged balance concern: [scaling type] scaling at [boundary condition]
+
+SECTIONS MARKED AS INCOMPLETE:
+- "[System] interaction with [other-system]" (not fully implemented yet)
+- "[Variant or feature]" (only [subset] implemented so far)
+
+May I write this to design/gdd/[system-name].md?
+```
+
+Wait for approval. User may request changes before writing.
+
+## Phase 7: Write Document with Metadata
+
+When approved, write the file with special markers:
+
+```markdown
+---
+status: reverse-documented
+source: [path/]
+date: [today]
+verified-by: [User name]
+---
+
+# [System Name] Design
+
+> **Note**: This document was reverse-engineered from the existing implementation.
+> It captures current behavior and clarified design intent. Some sections may be
+> incomplete where implementation is partial or intent was unclear.
+
+[Rest of document...]
+```
+
+## Phase 8: Flag Follow-Up Work
+
+After writing, suggest next steps:
+
+```
+✅ Written to design/gdd/combat-system.md
+
+FOLLOW-UP RECOMMENDED:
+1. Run /balance-check on combat formulas (exponential scaling concern)
+2. Create ADR for stamina system architecture decision
+3. Implement missing edge cases:
+   - Stamina depletion mid-combo behavior
+   - Stagger state during dodge
+4. Extend design doc when weapon variety is implemented
+
+Would you like me to tackle any of these now?
+```
+
+---
+
+## Template Selection Logic
+
+| If analyzing... | Use template... | Because... |
+|----------------|-----------------|------------|
+| `src/gameplay/*` | design-doc-from-implementation.md | Gameplay mechanics → GDD |
+| `src/core/*`, `src/ai/*` | architecture-doc-from-code.md | Core systems → ADR |
+| `prototypes/*` | concept-doc-from-prototype.md | Experiments → concept doc |
+| `src/networking/*` | architecture-doc-from-code.md | Technical systems → ADR |
+| `src/ui/*` | design-doc-from-implementation.md | UI/UX → design spec |
+
+---
+
+## Example Session: Reverse-Document a System
+
+```
+User: /reverse-document design src/gameplay/[system]
+
+Agent: I'll analyze your [system] implementation to create a design doc.
+       [Reads code, discovers mechanics, formulas]
+
+Agent: I've analyzed src/gameplay/[system]/. Here's what I found:
+       [Shows mechanics, formulas, unclear areas]
+
+       Before drafting, could you clarify:
+       1. [Resource] system intent?
+       2. Is [mechanic] a core pillar?
+       3. [Value] scaling — intentional or needs tuning?
+
+User: 1. [Resource] is for pacing, prevent [unwanted behavior]
+      2. [Mechanic] is core — I want [design intent]
+      3. Yeah, exponential is too much, should be linear
+
+Agent: Perfect, that clarifies the vision. Let me draft the design doc.
+       [Shows draft with clarified intent]
+
+       May I write this to design/gdd/[system-name].md?
+
+User: Yes, write it.
+
+Agent: ✅ Written to design/gdd/[system-name].md
+       ✅ Marked as [REVERSE-DOCUMENTED]
+       ✅ Flagged [value] scaling for rebalancing
+
+       Next steps:
+       - Update [formula] to [corrected scaling]
+       - Run /balance-check to validate [curve]
+       - Document [mechanic] as core pillar in game-pillars.md
+```
+
+---
+
+## Collaborative Protocol
+
+This skill follows the collaborative design principle:
+
+1. **Analyze First**: Read code, understand implementation
+2. **Question Intent**: Ask about "why", not just "what"
+3. **Present Findings**: Show discoveries, highlight unclear areas
+4. **User Clarifies**: Separate intent from accidents
+5. **Draft Document**: Create doc based on reality + intent
+6. **Show Draft**: Display key sections, explain additions
+7. **Get Approval**: "May I write to [filepath]?" On approval: Verdict: **COMPLETE** — document generated. On decline: Verdict: **BLOCKED** — user declined write.
+8. **Flag Follow-Up**: Suggest related work, don't auto-execute
+
+**Never assume intent. Always ask before documenting "why".**