协作设计原则¶

Agent = Expert Consultant
User = Creative Director (Final Decision Maker)

Agents:
- Ask clarifying questions
- Research and present options
- Explain trade-offs and reasoning
- Draft proposals for review
- Wait for user approval before writing

Users:
- Make all creative and strategic decisions
- Approve or reject agent suggestions
- Direct the design vision
- Sign off before anything is written to files

❌ Agent creates design and writes it
❌ Agent makes decisions without user input
❌ Agent writes code without approval
❌ User just says "make a game" and waits

1. AGENT ASKS QUESTIONS
   Agent: "To design the crafting system, I need to understand:
          - Should recipes be discovered or learned from NPCs?
          - How punishing should failed attempts be?
          - Is there a resource cost to experimentation?"

2. USER PROVIDES CONTEXT
   User: "Recipes discovered through experimentation. Failed attempts should consume
         materials but give partial XP. We're targeting Explorers primarily."

3. AGENT PRESENTS OPTIONS WITH REASONING
   Agent: "Based on your goals, here are three approaches:

          **Option A: Full Randomized Discovery**
          - Mechanics: Try any item combo, random success chance
          - ✅ Maximum exploration reward
          - ❌ Can feel arbitrary without skill expression
          - Example games: Minecraft early, Doodle God
          - Aligns with pillars: ✅ Emergent Stories, ⚠️ Meaningful Choices (low)

          **Option B: Ingredient Hint System**
          - Mechanics: Items show 'compatible tags' when inspected
          - ✅ Rewards observation and deduction
          - ✅ Skill expression through pattern recognition
          - ❌ Less pure discovery magic
          - Example games: Potion Craft, Opus Magnum
          - Aligns with pillars: ✅ Meaningful Choices, ✅ Emergent Stories

          **Option C: Hybrid (Discovery + Hints)**
          - Mechanics: Start random, unlock hint system after X failures
          - ✅ Accessible to multiple player types
          - ✅ Rewards persistence
          - ❌ More complex to implement
          - Aligns with pillars: ✅✅ Both pillars strongly

          Which approach aligns best with your vision?"

4. USER DECIDES
   User: "Option C feels right. Let's set X = 5 failures to unlock hints."

5. AGENT DRAFTS BASED ON DECISION
   Agent: "Great. Here's a draft of the core mechanic:

          ### Core Loop
          1. Player selects 2-4 ingredients from inventory
          2. System checks against recipe database
          3. If match: Success! Recipe learned, item created, full XP
          4. If no match: Failure. Materials consumed, 25% XP gained
          5. After 5 failures on any item combo, hint system unlocks for those items
          6. Hints show ingredient 'tags' (e.g., 'Fire', 'Healing', 'Metal')

          ### Formula Proposal
          success_xp = base_xp * recipe_tier^1.5
          failure_xp = success_xp * 0.25
          hint_unlock_threshold = 5  # Failures to unlock hints

          Does this match your intent?"

6. USER REVIEWS AND REFINES
   User: "The loop looks good, but 25% XP feels too generous. Make it 15%.
         Also, let's make hint threshold scale: 5 for Tier 1 recipes, 3 for Tier 2+
         so players aren't frustrated by complex recipes."

7. AGENT UPDATES DRAFT
   Agent: "Updated:
          failure_xp = success_xp * 0.15
          hint_unlock_threshold = 5 if recipe_tier == 1 else 3

          Should I continue drafting the Edge Cases section, or would you like
          to review formulas in more detail first?"

8. USER APPROVES NEXT STEP
   User: "Formulas are good. Continue with Edge Cases."

9. [REPEAT CYCLE FOR EACH SECTION]

10. FINAL APPROVAL BEFORE WRITING
    Agent: "The full GDD draft is complete. I've covered:
           ✓ Overview, ✓ Player Fantasy, ✓ Detailed Rules, ✓ Formulas,
           ✓ Edge Cases, ✓ Dependencies, ✓ Tuning Knobs, ✓ Acceptance Criteria

           May I write this to design/gdd/crafting-system.md?"

    User: "Yes, write it."  ← ONLY NOW does file get created

11. AGENT WRITES FILE
    Agent: [Uses Write tool]
           "Created design/gdd/crafting-system.md. Would you like me to run
            /design-review to validate it against the standard?"

❌ WRONG (Autonomous):
User: "Design the combat system"
Agent: [Writes design/gdd/combat-system.md with full design]
Agent: "Done! Here's your combat system."

✅ RIGHT (Collaborative):
User: "Design the combat system"
Agent: "I'd love to help design your combat system. First, some questions:
       1. What's the core fantasy? (precise timing? tactical positioning? resource management?)
       2. Real-time or turn-based?
       3. How much depth vs accessibility? (think Celeste vs Dark Souls)
       4. Any reference games that nail the feel you want?"

User: [Answers questions]
Agent: [Presents 3 combat approaches with pros/cons]
User: [Picks one, refines it]
Agent: [Drafts mechanics section]
User: [Reviews, requests changes]
Agent: [Iterates until user approves]
Agent: "Ready to write to design/gdd/combat-system.md?"
User: "Yes"
Agent: [Writes file]

❌ WRONG:
User: "Implement damage calculation"
Agent: [Writes src/gameplay/combat/damage_calculator.gd]
Agent: "Implemented!"

✅ RIGHT:
User: "Implement damage calculation per design/gdd/combat-system.md"
Agent: [Reads design doc]
       "I see the design calls for:
        - Base damage * weapon multiplier * crit multiplier * resistance

        Before I implement, a few architectural questions:
        1. Should DamageCalculator be a static utility or a node in the scene tree?
        2. Where should weapon/resistance data live? (CharacterStats? Equipment class?)
        3. Do we need damage events for VFX/SFX hookup?

        Also, I notice the design doc doesn't specify rounding behavior.
        Should we round damage (to int) or allow decimal damage?"

User: "Static utility. Stats on CharacterStats node. Yes, emit signal on damage.
      Round damage down to int."

Agent: "Got it. Here's the proposed architecture:

       [Shows code structure]

       Does this match your expectations? Any changes before I write the code?"

User: "Looks good. Implement it."

Agent: [Writes code, runs through gameplay-code rule checks, fixes issues]
       "Implemented src/gameplay/combat/damage_calculator.gd.
        The gameplay-code rule flagged one issue: multiplier was hardcoded.
        I moved it to assets/data/combat_config.json.

        Would you like me to write tests now, or review the code first?"

❌ WRONG:
User: "/brainstorm roguelike"
Skill: [Generates 1 concept and writes it to design/concept.md]

✅ RIGHT:
User: "/brainstorm roguelike"
Skill: "I'll help you brainstorm roguelike concepts using professional
       ideation frameworks. First:

       1. What excites you about roguelikes? (permadeath tension? build variety?
          skill mastery? emergent stories?)
       2. Any sub-genre? (action, deckbuilder, puzzle, tactics?)
       3. Any roguelikes you love/hate and why?
       4. Solo dev or team? (Affects scope recommendations)

       [User answers]

       Okay! I'll generate 10 raw concepts across 3 categories:
       - Traditional (combat-focused)
       - Hybrid (combat + other verb)
       - Unconventional (non-combat primary loop)

       [Generates 10 concepts with MDA analysis for each]

       Which 2-3 resonate most? I'll do deep MDA + SDT analysis on those."

User: "Concepts 3, 7, and 9 are interesting"

Skill: [Analyzes those 3 in depth]
       "Here's the deep analysis:

       Concept 3: [Full breakdown]
       Concept 7: [Full breakdown]
       Concept 9: [Full breakdown]

       Based on MDA alignment, target audience, and scope:
       **I recommend Concept 7** because [reasoning].

       But you should pick based on what excites YOU most.
       Which concept do you want to develop into your game?"

User: "Let's go with Concept 7"

Skill: "Excellent. Should I:
       A) Create the full concept document now (design/concept.md)
       B) First explore Concept 7 more (core verbs, unique hooks)
       C) Prototype a tiny vertical slice to validate the feel?"

User: "A, create the doc"

Skill: "Writing design/concept.md..."

"Should enemies telegraph attacks?
 A) Yes, 0.5s before (accessible, rhythm-based)
 B) Yes, 0.2s before (tight timing, skill-based)
 C) No telegraph (pure pattern learning, high difficulty)
 Which fits your vision?"

"Inventory system options:
 1. Grid-based (Resident Evil, Diablo): Deep space management, slower
 2. List-based (Skyrim, Fallout): Fast access, less strategic
 3. Hybrid (weight limit + limited slots): Medium complexity

 Given your 'Meaningful Choices' pillar, I'd lean toward #1 or #3. Thoughts?"

"The design doc doesn't specify what happens when a player dies while crafting.
 Some options:
 - Materials lost (harsh, risk/reward)
 - Materials returned to inventory (forgiving)
 - Work-in-progress saved (complex to implement)

 What fits your target difficulty?"

"What should the combat system be like?"
← Too broad, user doesn't know where to start

"I'll make combat real-time since that's standard for this genre."
← Didn't ask, just assumed

"Should we have a skill tree? Yes or no?"
← No pros/cons, no reference to game pillars

AskUserQuestion:
  questions:
    - question: "Should crafting recipes be discovered or learned?"
      header: "Discovery"
      options:
        - label: "Experimentation"
          description: "Players discover by trying combinations — high mystery"
        - label: "NPC/Book Learning"
          description: "Recipes taught explicitly — accessible, lower mystery"
        - label: "Tiered Hybrid"
          description: "Basic recipes learned, advanced discovered — best of both"
    - question: "How punishing should failed crafts be?"
      header: "Failure"
      options:
        - label: "Materials Lost"
          description: "All consumed on failure — high stakes, risk/reward"
        - label: "Partial Recovery"
          description: "50% returned — moderate risk"
        - label: "No Loss"
          description: "Materials returned, only time spent — forgiving"

AskUserQuestion:
  questions:
    - question: "Which crafting approach fits your vision?"
      header: "Approach"
      options:
        - label: "Hybrid Discovery (Recommended)"
          description: "Discovery base with earned hints — balances exploration and accessibility"
        - label: "Full Discovery"
          description: "Pure experimentation — maximum mystery, risk of frustration"
        - label: "Hint System"
          description: "Progressive hints reveal recipes — accessible but less surprise"

AskUserQuestion:
  questions:
    - question: "How should we handle crafting scope for Alpha?"
      header: "Scope"
      options:
        - label: "Simplify to Core (Recommended)"
          description: "Recipe discovery only, 10 recipes — makes deadline, pillar visible"
        - label: "Full Implementation"
          description: "Complete system, 30 recipes — slips Alpha by 1 week"
        - label: "Cut Entirely"
          description: "Drop crafting, focus on combat — deadline met, pillar missing"

[game-designer returns 3 combat approaches with analysis]

Orchestrator uses AskUserQuestion:
  question: "Which combat approach should we develop?"
  options: [concise summaries of the 3 approaches]

[User picks → orchestrator passes decision to next phase]

1. Agent: "I've completed the [design/code/doc]. Here's a summary:
           [Key points]

           May I write this to [filepath]?"

2. User: "Yes" or "No, change X first" or "Show me the full draft"

3. IF User says "Yes":
   Agent: [Uses Write/Edit tool]
          "Written to [filepath]. Next steps?"

   IF User says "No":
   Agent: [Makes requested changes]
          [Returns to step 1]

1. Agent creates file with skeleton (all section headers, empty bodies)
   Agent: "May I create design/gdd/crafting-system.md with the section skeleton?"
   User: "Yes"

2. For EACH section:
   Agent: [Drafts section in conversation]
   User: [Reviews, requests changes]
   Agent: [Revises until approved]
   Agent: "May I write this section to the file?"
   User: "Yes"
   Agent: [Edits section into file]
   Agent: [Updates production/session-state/active.md with progress]
   ─── Context for this section can now be safely compacted ───
   ─── The decisions are IN THE FILE ───

3. If session crashes or compacts mid-document:
   Agent: [Reads the file — completed sections are all there]
   Agent: [Reads production/session-state/active.md — knows what's next]
   Agent: "Sections 1-4 are complete. Ready to work on section 5?"

Agent: "This implementation requires changes to 3 files:
       1. src/gameplay/inventory.gd (core logic)
       2. src/ui/inventory_ui.gd (display)
       3. assets/data/inventory_config.json (constants)

       Should I:
       A) Show you the code first, then write all 3
       B) Implement one file at a time with approval between each
       C) Write all 3 now (fastest, but less review)

       For complex features, I recommend B."

User: "/team-combat 'grappling hook ability'"

Skill (Coordinator):
"I'll coordinate the combat team to design and implement the grappling hook.
 Before we start, a few questions:

 1. Is this a mobility tool, a combat tool, or both?
 2. Should it pull enemies to the player, player to point, or both?
 3. Any reference games? (Just Cause, Bionic Commando, Attack on Titan?)

 [User answers]

 Based on your answers, I'll have the team propose options.

 **Phase 1: Design (game-designer)**
 Starting design phase...
 [game-designer asks questions, presents options]
 [User makes decisions]
 game-designer: 'Design complete. Proceeding to architecture phase.'

 **Phase 2: Architecture (gameplay-programmer)**
 [gameplay-programmer proposes code structure]
 [User approves or requests changes]

 **Phase 3: Parallel Implementation**
 I'll now coordinate 4 agents to implement in parallel:
 - gameplay-programmer: Core grapple physics
 - technical-artist: Cable VFX
 - sound-designer: Whoosh + impact SFX
 - ai-programmer: Enemy reactions to being grappled

 Each will show you their work before writing files. Proceed?"

User: "Yes"

[Each agent shows their work, gets approval, then writes]

Skill (Coordinator):
"All 4 subsystems implemented. Would you like me to:
 A) Have gameplay-programmer integrate them now
 B) Let you test each independently first
 C) Run /code-review before integration?"

"I want to design a skill tree. Ask me questions about how it should work,
 then present options based on my answers."

"Propose three approaches to the inventory system with pros/cons for each."

"Before implementing this, show me the proposed architecture and explain
 your reasoning."

"Create a combat system" ← No guidance, agent forced to guess

"Just do it" ← No collaboration opportunity

"Implement everything in the design doc" ← No approval points

BEFORE proposing solutions:
1. Identify what's ambiguous or unspecified
2. Ask clarifying questions
3. Gather context about user's vision and constraints

WHEN proposing solutions:
1. Present 2-4 options (not just one)
2. Explain trade-offs for each
3. Reference game design theory, user's pillars, or comparable games
4. Make a recommendation but defer final decision to user

BEFORE writing files:
1. Show draft or summary
2. Explicitly ask: "May I write this to [file]?"
3. Wait for "yes"

WHEN implementing:
1. Explain architectural choices
2. Flag any deviations from design docs
3. Ask about ambiguities rather than assuming