添加 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/docs/hooks-reference/hook-input-schemas.md
+++ b/.claude/docs/hooks-reference/hook-input-schemas.md
@@ -0,0 +1,126 @@
+# Hook Input/Output Schemas
+
+This documents the JSON payloads each Claude Code hook receives on stdin for every event type.
+
+## PreToolUse
+
+Fired before a tool is executed. Can **allow** (exit 0) or **block** (exit 2).
+
+### PreToolUse: Bash
+
+```json
+{
+  "tool_name": "Bash",
+  "tool_input": {
+    "command": "git commit -m 'feat: add player health system'",
+    "description": "Commit changes with message",
+    "timeout": 120000
+  }
+}
+```
+
+### PreToolUse: Write
+
+```json
+{
+  "tool_name": "Write",
+  "tool_input": {
+    "file_path": "src/gameplay/health.gd",
+    "content": "extends Node\n..."
+  }
+}
+```
+
+### PreToolUse: Edit
+
+```json
+{
+  "tool_name": "Edit",
+  "tool_input": {
+    "file_path": "src/gameplay/health.gd",
+    "old_string": "var health = 100",
+    "new_string": "var health: int = 100"
+  }
+}
+```
+
+### PreToolUse: Read
+
+```json
+{
+  "tool_name": "Read",
+  "tool_input": {
+    "file_path": "src/gameplay/health.gd"
+  }
+}
+```
+
+## PostToolUse
+
+Fired after a tool completes. **Cannot block** (exit code ignored for blocking). Stderr messages are shown as warnings.
+
+### PostToolUse: Write
+
+```json
+{
+  "tool_name": "Write",
+  "tool_input": {
+    "file_path": "assets/data/enemy_stats.json",
+    "content": "{\"goblin\": {\"health\": 50}}"
+  },
+  "tool_output": "File written successfully"
+}
+```
+
+### PostToolUse: Edit
+
+```json
+{
+  "tool_name": "Edit",
+  "tool_input": {
+    "file_path": "assets/data/enemy_stats.json",
+    "old_string": "\"health\": 50",
+    "new_string": "\"health\": 75"
+  },
+  "tool_output": "File edited successfully"
+}
+```
+
+## SubagentStart
+
+Fired when a subagent is spawned via the Task tool.
+
+```json
+{
+  "agent_name": "game-designer",
+  "model": "sonnet",
+  "description": "Design the combat healing mechanic"
+}
+```
+
+## SessionStart
+
+Fired when a Claude Code session begins. **No stdin input** — the hook just runs and its stdout is shown to Claude as context.
+
+## PreCompact
+
+Fired before context window compression. **No stdin input** — the hook runs to save state before compression occurs.
+
+## Stop
+
+Fired when the Claude Code session ends. **No stdin input** — the hook runs for cleanup and logging.
+
+## Exit Code Reference
+
+| Exit Code | Meaning | Applicable Events |
+|-----------|---------|-------------------|
+| 0 | Allow / Success | All events |
+| 2 | Block (stderr shown to Claude) | PreToolUse only |
+| Other | Treated as error, tool proceeds | All events |
+
+## Notes
+
+- Hooks receive JSON on **stdin** (pipe). Use `INPUT=$(cat)` to capture.
+- Parse with `jq` if available, fall back to `grep` for cross-platform compatibility.
+- On Windows, `grep -P` (Perl regex) is often unavailable. Use `grep -E` (POSIX extended) instead.
+- Path separators may be `\` on Windows. Normalize with `sed 's|\\|/|g'` when comparing paths.
--- a/.claude/docs/hooks-reference/post-merge-asset-validation.md
+++ b/.claude/docs/hooks-reference/post-merge-asset-validation.md
@@ -0,0 +1,84 @@
+# Hook: post-merge-asset-validation
+
+## Trigger
+
+Runs after any merge to the `develop` or `main` branch that includes changes
+to `assets/`.
+
+## Purpose
+
+Validates that all assets in the merged branch conform to naming conventions,
+size budgets, and format requirements. Prevents non-compliant assets from
+accumulating on integration branches.
+
+## Implementation
+
+```bash
+#!/bin/bash
+# Post-merge hook: Asset validation
+# Checks merged assets against project standards
+
+MERGED_ASSETS=$(git diff --name-only HEAD@{1} HEAD | grep -E '^assets/')
+
+if [ -z "$MERGED_ASSETS" ]; then
+    exit 0
+fi
+
+EXIT_CODE=0
+WARNINGS=""
+
+for file in $MERGED_ASSETS; do
+    filename=$(basename "$file")
+
+    # Check naming convention (lowercase with underscores)
+    if echo "$filename" | grep -qE '[A-Z[:space:]-]'; then
+        WARNINGS="$WARNINGS\nNAMING: $file -- must be lowercase with underscores"
+        EXIT_CODE=1
+    fi
+
+    # Check texture sizes (must be power of 2)
+    if [[ "$file" == *.png || "$file" == *.jpg ]]; then
+        # Requires ImageMagick
+        if command -v identify &> /dev/null; then
+            dims=$(identify -format "%w %h" "$file" 2>/dev/null)
+            if [ -n "$dims" ]; then
+                w=$(echo "$dims" | cut -d' ' -f1)
+                h=$(echo "$dims" | cut -d' ' -f2)
+                if (( (w & (w-1)) != 0 || (h & (h-1)) != 0 )); then
+                    WARNINGS="$WARNINGS\nSIZE: $file -- dimensions ${w}x${h} not power-of-2"
+                fi
+            fi
+        fi
+    fi
+
+    # Check file size budgets
+    size=$(stat -f%z "$file" 2>/dev/null || stat -c%s "$file" 2>/dev/null)
+    if [ -n "$size" ]; then
+        # Textures: max 4MB
+        if [[ "$file" == assets/art/* ]] && [ "$size" -gt 4194304 ]; then
+            WARNINGS="$WARNINGS\nBUDGET: $file -- ${size} bytes exceeds 4MB texture budget"
+            EXIT_CODE=1
+        fi
+        # Audio: max 10MB for music, 512KB for SFX
+        if [[ "$file" == assets/audio/sfx* ]] && [ "$size" -gt 524288 ]; then
+            WARNINGS="$WARNINGS\nBUDGET: $file -- ${size} bytes exceeds 512KB SFX budget"
+        fi
+    fi
+done
+
+if [ -n "$WARNINGS" ]; then
+    echo "=== Asset Validation Report ==="
+    echo -e "$WARNINGS"
+    echo "================================"
+    echo "Run /asset-audit for a full report."
+fi
+
+exit $EXIT_CODE
+```
+
+## Agent Integration
+
+When this hook reports issues:
+1. For naming violations: fix manually or invoke `art-director` for guidance
+2. For size violations: invoke `technical-artist` for optimization advice
+3. For a full audit: run `/asset-audit` skill
--- a/.claude/docs/hooks-reference/post-sprint-retrospective.md
+++ b/.claude/docs/hooks-reference/post-sprint-retrospective.md
@@ -0,0 +1,78 @@
+# Hook: post-sprint-retrospective
+
+## Trigger
+
+Manual trigger at the end of each sprint (typically invoked by the producer
+agent or the human developer).
+
+## Purpose
+
+Automatically generates a retrospective starting point by analyzing the sprint
+data: what was planned vs completed, velocity changes, bug trends, and common
+blockers. This is not a git hook but a workflow hook invoked through the
+`producer` agent.
+
+## Implementation
+
+This is a workflow hook, not a git hook. It is invoked by running:
+
+```
+@producer Generate sprint retrospective for Sprint [N]
+```
+
+The producer agent should:
+
+1. **Read the sprint plan** from `production/sprints/sprint-[N].md`
+2. **Calculate metrics**:
+   - Tasks planned vs completed
+   - Story points planned vs completed (if used)
+   - Carryover items from previous sprint
+   - New tasks added mid-sprint
+   - Average task completion time
+3. **Analyze patterns**:
+   - Most common blockers
+   - Which agent/area had the most incomplete work
+   - Which estimates were most inaccurate
+4. **Generate the retrospective**:
+
+```markdown
+# Sprint [N] Retrospective
+
+## Metrics
+| Metric | Value |
+|--------|-------|
+| Tasks Planned | [N] |
+| Tasks Completed | [N] |
+| Completion Rate | [X%] |
+| Carryover from Previous | [N] |
+| New Tasks Added | [N] |
+| Bugs Found | [N] |
+| Bugs Fixed | [N] |
+
+## Velocity Trend
+[Sprint N-2]: [X] | [Sprint N-1]: [Y] | [Sprint N]: [Z]
+Trend: [Improving / Stable / Declining]
+
+## What Went Well
+- [Automatically detected: tasks completed ahead of estimate]
+- [Facilitator adds team observations]
+
+## What Went Poorly
+- [Automatically detected: tasks that were carried over or cut]
+- [Automatically detected: areas with significant estimate overruns]
+- [Facilitator adds team observations]
+
+## Blockers
+| Blocker | Frequency | Resolution Time | Prevention |
+|---------|-----------|----------------|-----------|
+
+## Action Items for Next Sprint
+| # | Action | Owner | Priority |
+|---|--------|-------|----------|
+
+## Estimation Accuracy
+| Area | Avg Planned | Avg Actual | Accuracy |
+|------|------------|-----------|----------|
+```
+
+5. **Save** to `production/sprints/sprint-[N]-retro.md`
--- a/.claude/docs/hooks-reference/pre-commit-code-quality.md
+++ b/.claude/docs/hooks-reference/pre-commit-code-quality.md
@@ -0,0 +1,60 @@
+# Hook: pre-commit-code-quality
+
+## Trigger
+
+Runs before any commit that modifies files in `src/`.
+
+## Purpose
+
+Enforces coding standards before code enters version control. Catches style
+violations, missing documentation, overly complex methods, and hardcoded
+values that should be data-driven.
+
+## Implementation
+
+```bash
+#!/bin/bash
+# Pre-commit hook: Code quality checks
+# Adapt the specific checks to your language and tooling
+
+CODE_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '^src/')
+
+EXIT_CODE=0
+
+if [ -n "$CODE_FILES" ]; then
+    for file in $CODE_FILES; do
+        # Check for hardcoded magic numbers in gameplay code
+        if [[ "$file" == src/gameplay/* ]]; then
+            # Look for numeric literals that are likely balance values
+            # Adjust the pattern for your language
+            if grep -nE '(damage|health|speed|rate|chance|cost|duration)[[:space:]]*[:=][[:space:]]*[0-9]+' "$file"; then
+                echo "WARNING: $file may contain hardcoded gameplay values. Use data files."
+                # Warning only, not blocking
+            fi
+        fi
+
+        # Check for TODO/FIXME without assignee
+        if grep -nE '(TODO|FIXME|HACK)[^(]' "$file"; then
+            echo "WARNING: $file has TODO/FIXME without owner tag. Use TODO(name) format."
+        fi
+
+        # Run language-specific linter (uncomment appropriate line)
+        # For GDScript: gdlint "$file" || EXIT_CODE=1
+        # For C#: dotnet format --check "$file" || EXIT_CODE=1
+        # For C++: clang-format --dry-run -Werror "$file" || EXIT_CODE=1
+    done
+
+    # Run unit tests for modified systems
+    # Uncomment and adapt for your test framework
+    # python -m pytest tests/unit/ -x --quiet || EXIT_CODE=1
+fi
+
+exit $EXIT_CODE
+```
+
+## Agent Integration
+
+When this hook fails:
+1. For style violations: auto-fix with your formatter or invoke `lead-programmer`
+2. For hardcoded values: invoke `gameplay-programmer` to externalize the values
+3. For test failures: invoke `qa-tester` to diagnose and `gameplay-programmer` to fix
--- a/.claude/docs/hooks-reference/pre-commit-design-check.md
+++ b/.claude/docs/hooks-reference/pre-commit-design-check.md
@@ -0,0 +1,70 @@
+# Hook: pre-commit-design-check
+
+## Trigger
+
+Runs before any commit that modifies files in `design/` or `assets/data/`.
+
+## Purpose
+
+Ensures design documents and game data files maintain consistency and
+completeness before they enter version control. Catches missing sections,
+broken cross-references, and invalid data before they propagate.
+
+## Implementation
+
+```bash
+#!/bin/bash
+# Pre-commit hook: Design document and game data validation
+# Place in .git/hooks/pre-commit or configure via your hook manager
+
+DESIGN_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '^design/')
+DATA_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '^assets/data/')
+
+EXIT_CODE=0
+
+# Check design documents for required sections
+if [ -n "$DESIGN_FILES" ]; then
+    for file in $DESIGN_FILES; do
+        if [[ "$file" == *.md ]]; then
+            # Check for required sections in GDD documents
+            if [[ "$file" == design/gdd/* ]]; then
+                for section in "Overview" "Detailed" "Edge Cases" "Dependencies" "Acceptance Criteria"; do
+                    if ! grep -qi "$section" "$file"; then
+                        echo "ERROR: $file missing required section: $section"
+                        EXIT_CODE=1
+                    fi
+                done
+            fi
+        fi
+    done
+fi
+
+# Validate JSON data files
+if [ -n "$DATA_FILES" ]; then
+    for file in $DATA_FILES; do
+        if [[ "$file" == *.json ]]; then
+            # Find a working Python command
+            PYTHON_CMD=""
+            for cmd in python python3 py; do
+                if command -v "$cmd" >/dev/null 2>&1; then
+                    PYTHON_CMD="$cmd"
+                    break
+                fi
+            done
+            if [ -n "$PYTHON_CMD" ] && ! "$PYTHON_CMD" -m json.tool "$file" > /dev/null 2>&1; then
+                echo "ERROR: $file is not valid JSON"
+                EXIT_CODE=1
+            fi
+        fi
+    done
+fi
+
+exit $EXIT_CODE
+```
+
+## Agent Integration
+
+When this hook fails, the committer should:
+1. For missing design sections: invoke the `game-designer` agent to complete
+   the document
+2. For invalid JSON: invoke the `tools-programmer` agent or fix manually
--- a/.claude/docs/hooks-reference/pre-push-test-gate.md
+++ b/.claude/docs/hooks-reference/pre-push-test-gate.md
@@ -0,0 +1,80 @@
+# Hook: pre-push-test-gate
+
+## Trigger
+
+Runs before any push to a remote branch. Mandatory for pushes to `develop`
+and `main`.
+
+## Purpose
+
+Ensures the build compiles, unit tests pass, and critical smoke tests pass
+before code reaches shared branches. This is the last automated quality gate
+before code affects other developers.
+
+## Implementation
+
+```bash
+#!/bin/bash
+# Pre-push hook: Build and test gate
+
+REMOTE="$1"
+URL="$2"
+
+# Only enforce full gate for develop and main
+PROTECTED_BRANCHES="develop main"
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+
+FULL_GATE=false
+for branch in $PROTECTED_BRANCHES; do
+    if [ "$CURRENT_BRANCH" = "$branch" ]; then
+        FULL_GATE=true
+        break
+    fi
+done
+
+echo "=== Pre-Push Quality Gate ==="
+
+# Step 1: Build
+echo "Building..."
+# Adapt to your build system:
+# make build || exit 1
+# dotnet build || exit 1
+# cargo build || exit 1
+echo "Build: PASS"
+
+# Step 2: Unit tests
+echo "Running unit tests..."
+# Adapt to your test framework:
+# python -m pytest tests/unit/ -x || exit 1
+# dotnet test tests/unit/ || exit 1
+# cargo test || exit 1
+echo "Unit tests: PASS"
+
+if [ "$FULL_GATE" = true ]; then
+    # Step 3: Integration tests (only for protected branches)
+    echo "Running integration tests..."
+    # python -m pytest tests/integration/ -x || exit 1
+    echo "Integration tests: PASS"
+
+    # Step 4: Smoke tests
+    echo "Running smoke tests..."
+    # python -m pytest tests/playtest/smoke/ -x || exit 1
+    echo "Smoke tests: PASS"
+
+    # Step 5: Performance regression check
+    echo "Checking performance baselines..."
+    # python tools/ci/perf_check.py || exit 1
+    echo "Performance: PASS"
+fi
+
+echo "=== All gates passed ==="
+exit 0
+```
+
+## Agent Integration
+
+When this hook fails:
+1. Build failure: invoke `lead-programmer` to diagnose
+2. Unit test failure: invoke `qa-tester` to identify the failing test and
+   `gameplay-programmer` or relevant programmer to fix
+3. Performance regression: invoke `performance-analyst` to analyze