docs: add conventional commits guide and design decisions template

2026-07-26 14:22:44 +00:00
parent cbb77576bb
commit 1eec71ded1
2 changed files with 131 additions and 1 deletions
@@ -18,9 +18,47 @@
 ### Git Workflow

 - Small, focused commits with descriptive messages
- Branch naming: `feature/<name>`, `bugfix/<name>`
+- Branch naming: `feat/<name>`, `chore/<name>`, `bugfix/<name>`
 - Pull requests should include what/why, not just what changed

+#### Conventional Commits
+
+Use this format for all commit messages:
+
+```
+<type>: <description>
+```
+
+**Types:**
+
+| Type      | When to use                                          |
+|-----------|------------------------------------------------------|
+| `feat`    | New feature or functionality                         |
+| `fix`     | Bug fixes                                            |
+| `chore`   | Maintenance, docs, config, dependencies              |
+| `refactor`| Code change that neither fixes a bug nor adds a feat |
+| `test`    | Adding or updating tests                             |
+| `docs`    | Documentation changes only                           |
+| `style`   | Formatting, whitespace, semicolons (no code change)  |
+| `perf`    | Performance improvements                             |
+
+**Examples:**
+
+```
+feat: add player movement with WASD and mouse look
+fix: resolve collision detection issue on river logs
+chore: update README with setup instructions
+docs: add game design questionnaire
+refactor: extract enemy AI into separate class
+perf: optimize physics process loop
+```
+
+**Rules:**
+
+- Lowercase description after the colon
+- No period at the end
+- Imperative mood: "add" not "added" or "adds"
+
 ## AI Development Guidelines

 When working with AI assistants on this project:
@@ -29,6 +67,65 @@ When working with AI assistants on this project:
 2. **Godot patterns** — AI should follow Godot 4 C# conventions (signals, `_Process`, `_PhysicsProcess`, etc.)
 3. **Incremental changes** — one feature at a time; verify each works before moving on
 4. **Scene integrity** — don't modify `.tscn` files directly unless necessary; prefer code-based node creation
+5. **C#优先** — implement as much as possible in C# rather than GDScript or visual scripting
+
+## AI Development Cycle
+
+All feature work follows this cycle:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 1. PLAN CHANGES                                             │
+│    - Describe what will be built, why, and how              │
+│    - List files to create/modify                            │
+│    - Note any design decisions                              │
+└─────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────┐
+│ 2. REVIEW CHANGES (initial)                                 │
+│    - Self-review before implementation                        │
+│    - Check against design doc and questionnaire              │
+└─────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────┐
+│ 3. PRESENT CHANGES                                          │
+│    - Show what you plan to do                               │
+│    - Await feedback/approval                                │
+└─────────────────────────────────────────────────────────────┘
+                              ↓ (feedback → loop back to Plan)
+                              ↓ (approved)
+┌─────────────────────────────────────────────────────────────┐
+│ 4. IMPLEMENT CHANGES                                        │
+│    - Write code, create scenes, update docs                 │
+│    - Keep changes focused and atomic                        │
+└─────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────┐
+│ 5. REVIEW CHANGES (fresh perspective)                       │
+│    - Use a fresh subagent or second pass without bias       │
+│    - Check for bugs, style issues, Godot best practices     │
+└─────────────────────────────────────────────────────────────┘
+                              ↓ (issues → loop back to Implement)
+                              ↓ (approved)
+┌─────────────────────────────────────────────────────────────┐
+│ 6. PRESENT FINAL CHANGES                                    │
+│    - Show completed implementation                          │
+│    - Summarize what was done                                │
+└─────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────┐
+│ 7. DOCUMENT DESIGN CHOICES (if applicable)                  │
+│    - Update DESIGN.md with key decisions                    │
+│    - Note trade-offs, alternatives considered               │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Key Rules
+
+- **Never skip review** — even small changes get a second look
+- **Fresh eyes matter** — use a different agent/context for the final review when possible
+- **Feedback is mandatory** — if feedback requests changes, loop back to Plan
+- **Document decisions** — if a design choice was made, record it in `DESIGN.md`

 ## Quick Reference

@@ -0,0 +1,33 @@
+# FrogFPS — Design Decisions Log
+
+*Track important design choices here. Each entry explains what was decided, why, and any alternatives considered.*
+
+---
+
+## Template
+
+```markdown
+### [Date] — [Feature/Decision Name]
+
+**Decision:** What was chosen
+
+**Rationale:** Why this choice was made
+
+**Alternatives Considered:**
+- Option A: ...
+- Option B: ...
+
+**Trade-offs:**
+- Pros: ...
+- Cons: ...
+
+**Related Files:**
+- `path/to/file.cs`
+- `path/to/scene.tscn`
+```
+
+---
+
+## Entries
+
+<!-- Add entries below this line -->