first commit

2026-05-10 13:52:46 +08:00
commit ccc63d1e70
4583 changed files with 584341 additions and 0 deletions
--- a/software-development/writing-plans/SKILL.md
+++ b/software-development/writing-plans/SKILL.md
@@ -0,0 +1,557 @@
+---
+name: writing-plans
+description: "Write implementation plans: bite-sized tasks, paths, code."
+version: 1.1.0
+author: Hermes Agent (adapted from obra/superpowers)
+license: MIT
+metadata:
+  hermes:
+    tags: [planning, design, implementation, workflow, documentation]
+    related_skills: [subagent-driven-development, test-driven-development, requesting-code-review]
+---
+
+# Writing Implementation Plans
+
+## Overview
+
+Write comprehensive implementation plans assuming the implementer has zero context for the codebase and questionable taste. Document everything they need: which files to touch, complete code, testing commands, docs to check, how to verify. Give them bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.
+
+Assume the implementer is a skilled developer but knows almost nothing about the toolset or problem domain. Assume they don't know good test design very well.
+
+**Core principle:** A good plan makes implementation obvious. If someone has to guess, the plan is incomplete.
+
+## When to Use
+
+**Always use before:**
+- Implementing multi-step features
+- Breaking down complex requirements
+- Delegating to subagents via subagent-driven-development
+
+**Don't skip when:**
+- Feature seems simple (assumptions cause bugs)
+- You plan to implement it yourself (future you needs guidance)
+- Working alone (documentation matters)
+
+## Bite-Sized Task Granularity
+
+**Each task = 2-5 minutes of focused work.**
+
+Every step is one action:
+- "Write the failing test" — step
+- "Run it to make sure it fails" — step
+- "Implement the minimal code to make the test pass" — step
+- "Run the tests and make sure they pass" — step
+- "Commit" — step
+
+**Too big:**
+```markdown
+### Task 1: Build authentication system
+[50 lines of code across 5 files]
+```
+
+**Right size:**
+```markdown
+### Task 1: Create User model with email field
+[10 lines, 1 file]
+
+### Task 2: Add password hash field to User
+[8 lines, 1 file]
+
+### Task 3: Create password hashing utility
+[15 lines, 1 file]
+```
+
+## Plan Document Structure
+
+### Header (Required)
+
+Every plan MUST start with:
+
+```markdown
+# [Feature Name] Implementation Plan
+
+> **For Hermes:** Use subagent-driven-development skill to implement this plan task-by-task.
+
+**Goal:** [One sentence describing what this builds]
+
+**Architecture:** [2-3 sentences about approach]
+
+**Tech Stack:** [Key technologies/libraries]
+
+---
+```
+
+### Task Structure
+
+Each task follows this format:
+
+````markdown
+### Task N: [Descriptive Name]
+
+**Objective:** What this task accomplishes (one sentence)
+
+**Files:**
+- Create: `exact/path/to/new_file.py`
+- Modify: `exact/path/to/existing.py:45-67` (line numbers if known)
+- Test: `tests/path/to/test_file.py`
+
+**Step 1: Write failing test**
+
+```python
+def test_specific_behavior():
+    result = function(input)
+    assert result == expected
+```
+
+**Step 2: Run test to verify failure**
+
+Run: `pytest tests/path/test.py::test_specific_behavior -v`
+Expected: FAIL — "function not defined"
+
+**Step 3: Write minimal implementation**
+
+```python
+def function(input):
+    return expected
+```
+
+**Step 4: Run test to verify pass**
+
+Run: `pytest tests/path/test.py::test_specific_behavior -v`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add tests/path/test.py src/path/file.py
+git commit -m "feat: add specific feature"
+```
+````
+
+## Writing Process
+
+### Step 1: Understand Requirements
+
+Read and understand:
+- Feature requirements
+- Design documents or user description
+- Acceptance criteria
+- Constraints
+
+### Step 2: Explore the Codebase
+
+Use Hermes tools to understand the project:
+
+```python
+# Understand project structure
+search_files("*.py", target="files", path="src/")
+
+# Look at similar features
+search_files("similar_pattern", path="src/", file_glob="*.py")
+
+# Check existing tests
+search_files("*.py", target="files", path="tests/")
+
+# Read key files
+read_file("src/app.py")
+```
+
+### Step 3: Design Approach
+
+Decide:
+- Architecture pattern
+- File organization
+- Dependencies needed
+- Testing strategy
+
+### Step 4: Write Tasks
+
+Create tasks in order:
+1. Setup/infrastructure
+2. Core functionality (TDD for each)
+3. Edge cases
+4. Integration
+5. Cleanup/documentation
+
+### Step 5: Add Complete Details
+
+For each task, include:
+- **Exact file paths** (not "the config file" but `src/config/settings.py`)
+- **Complete code examples** (not "add validation" but the actual code)
+- **Exact commands** with expected output
+- **Verification steps** that prove the task works
+
+### Step 6: Review the Plan
+
+Check:
+- [ ] Tasks are sequential and logical
+- [ ] Each task is bite-sized (2-5 min)
+- [ ] File paths are exact
+- [ ] Code examples are complete (copy-pasteable)
+- [ ] Commands are exact with expected output
+- [ ] No missing context
+- [ ] DRY, YAGNI, TDD principles applied
+
+### Step 7: Save the Plan
+
+```bash
+mkdir -p docs/plans
+# Save plan to docs/plans/YYYY-MM-DD-feature-name.md
+git add docs/plans/
+git commit -m "docs: add implementation plan for [feature]"
+```
+
+## Principles
+
+### DRY (Don't Repeat Yourself)
+
+**Bad:** Copy-paste validation in 3 places
+**Good:** Extract validation function, use everywhere
+
+### YAGNI (You Aren't Gonna Need It)
+
+**Bad:** Add "flexibility" for future requirements
+**Good:** Implement only what's needed now
+
+```python
+# Bad — YAGNI violation
+class User:
+    def __init__(self, name, email):
+        self.name = name
+        self.email = email
+        self.preferences = {}  # Not needed yet!
+        self.metadata = {}     # Not needed yet!
+
+# Good — YAGNI
+class User:
+    def __init__(self, name, email):
+        self.name = name
+        self.email = email
+```
+
+### TDD (Test-Driven Development)
+
+Every task that produces code should include the full TDD cycle:
+1. Write failing test
+2. Run to verify failure
+3. Write minimal code
+4. Run to verify pass
+
+See `test-driven-development` skill for details.
+
+### Frequent Commits
+
+Commit after every task:
+```bash
+git add [files]
+git commit -m "type: description"
+```
+
+## Common Mistakes
+
+### Vague Tasks
+
+**Bad:** "Add authentication"
+**Good:** "Create User model with email and password_hash fields"
+
+### Incomplete Code
+
+**Bad:** "Step 1: Add validation function"
+**Good:** "Step 1: Add validation function" followed by the complete function code
+
+### Missing Verification
+
+**Bad:** "Step 3: Test it works"
+**Good:** "Step 3: Run `pytest tests/test_auth.py -v`, expected: 3 passed"
+
+### Missing File Paths
+
+**Bad:** "Create the model file"
+**Good:** "Create: `src/models/user.py`"
+
+## Execution Handoff
+
+After saving the plan, offer the execution approach:
+
+**"Plan complete and saved. Ready to execute using subagent-driven-development — I'll dispatch a fresh subagent per task with two-stage review (spec compliance then code quality). Shall I proceed?"**
+
+When executing, use the `subagent-driven-development` skill:
+- Fresh `delegate_task` per task with full context
+- Spec compliance review after each task
+- Code quality review after spec passes
+- Proceed only when both reviews approve
+
+## Remember
+
+```
+Bite-sized tasks (2-5 min each)
+Exact file paths
+Complete code (copy-pasteable)
+Exact commands with expected output
+Verification steps
+DRY, YAGNI, TDD
+Frequent commits
+```
+
+**A good plan makes implementation obvious.**
+
+## 中文计划模板
+
+### 计划头部
+
+```markdown
+# [功能名称] 实现计划
+
+> **Hermes 使用说明：** 使用 subagent-driven-development 技能逐个任务执行此计划。
+
+**目标：** [一句话描述要构建什么]
+
+**架构：** [2-3 句话描述技术方案]
+
+**技术栈：** [关键技术/库]
+
+**预计时间：** [总时间估算]
+
+---
+```
+
+### 任务结构
+
+```markdown
+### 任务 N: [描述性名称]
+
+**目标：** 此任务要完成什么（一句话）
+
+**文件：**
+- 创建：`exact/path/to/new_file.py`
+- 修改：`exact/path/to/existing.py:45-67`（如果知道行号）
+- 测试：`tests/path/to/test_file.py`
+
+**步骤 1: 编写失败测试**
+
+```python
+def test_specific_behavior():
+    result = function(input)
+    assert result == expected
+```
+
+**步骤 2: 运行测试验证失败**
+
+运行：`pytest tests/path/test.py::test_specific_behavior -v`
+预期：FAIL — "function not defined"
+
+**步骤 3: 编写最小实现**
+
+```python
+def function(input):
+    return expected
+```
+
+**步骤 4: 运行测试验证通过**
+
+运行：`pytest tests/path/test.py::test_specific_behavior -v`
+预期：PASS
+
+**步骤 5: 提交**
+
+```bash
+git add tests/path/test.py src/path/file.py
+git commit -m "feat: 添加特定功能"
+```
+```
+
+### 任务粒度示例
+
+**太粗：**
+```markdown
+### 任务 1: 构建认证系统
+[50 行代码，跨越 5 个文件]
+```
+
+**合适：**
+```markdown
+### 任务 1: 创建用户模型，包含邮箱字段
+[10 行，1 个文件]
+
+### 任务 2: 为用户添加密码哈希字段
+[8 行，1 个文件]
+
+### 任务 3: 创建密码哈希工具函数
+[15 行，1 个文件]
+```
+
+### 中文计划示例
+
+```markdown
+# 用户认证功能实现计划
+
+> **Hermes 使用说明：** 使用 subagent-driven-development 技能逐个任务执行此计划。
+
+**目标：** 实现用户注册、登录、JWT 令牌生成的完整认证系统
+
+**架构：** 使用 Flask + SQLAlchemy + bcrypt，遵循 RESTful 设计
+
+**技术栈：** Python 3.11, Flask 2.3.2, SQLAlchemy 2.0, bcrypt 4.0, PyJWT 2.8
+
+**预计时间：** 4 小时
+
+---
+
+### 任务 1: 创建用户模型
+
+**目标：** 创建 User 模型，包含邮箱和密码哈希字段
+
+**文件：**
+- 创建：`src/models/user.py`
+- 测试：`tests/models/test_user.py`
+
+**步骤 1: 编写失败测试**
+
+```python
+def test_user_creation():
+    user = User(email="test@example.com", password_hash="hashed")
+    assert user.email == "test@example.com"
+    assert user.password_hash == "hashed"
+```
+
+**步骤 2: 运行测试验证失败**
+
+运行：`pytest tests/models/test_user.py -v`
+预期：FAIL — "cannot import name 'User'"
+
+**步骤 3: 编写最小实现**
+
+```python
+class User:
+    def __init__(self, email, password_hash):
+        self.email = email
+        self.password_hash = password_hash
+```
+
+**步骤 4: 运行测试验证通过**
+
+运行：`pytest tests/models/test_user.py -v`
+预期：PASS
+
+**步骤 5: 提交**
+
+```bash
+git add src/models/user.py tests/models/test_user.py
+git commit -m "feat: 创建用户模型"
+```
+
+---
+
+### 任务 2: 添加密码哈希功能
+
+**目标：** 实现密码哈希和验证功能
+
+**文件：**
+- 创建：`src/utils/password.py`
+- 测试：`tests/utils/test_password.py`
+
+**步骤 1: 编写失败测试**
+
+```python
+def test_hash_password():
+    hashed = hash_password("password123")
+    assert hashed != "password123"
+    assert verify_password("password123", hashed) is True
+    assert verify_password("wrong", hashed) is False
+```
+
+**步骤 2: 运行测试验证失败**
+
+运行：`pytest tests/utils/test_password.py -v`
+预期：FAIL — "cannot import name 'hash_password'"
+
+**步骤 3: 编写最小实现**
+
+```python
+import bcrypt
+
+def hash_password(password):
+    return bcrypt.hashpw(password.encode(), bcrypt.gensalt()).decode()
+
+def verify_password(password, hashed):
+    return bcrypt.checkpw(password.encode(), hashed.encode())
+```
+
+**步骤 4: 运行测试验证通过**
+
+运行：`pytest tests/utils/test_password.py -v`
+预期：PASS
+
+**步骤 5: 提交**
+
+```bash
+git add src/utils/password.py tests/utils/test_password.py
+git commit -m "feat: 添加密码哈希功能"
+```
+
+---
+
+### 任务 3: 创建注册端点
+
+**目标：** 实现用户注册 API
+
+**文件：**
+- 创建：`src/routes/auth.py`
+- 测试：`tests/routes/test_auth.py`
+
+**步骤 1: 编写失败测试**
+
+```python
+def test_register(client):
+    response = client.post('/api/register', json={
+        'email': 'test@example.com',
+        'password': 'password123'
+    })
+    assert response.status_code == 201
+    assert 'user' in response.json
+```
+
+**步骤 2: 运行测试验证失败**
+
+运行：`pytest tests/routes/test_auth.py::test_register -v`
+预期：FAIL — "404 Not Found"
+
+**步骤 3: 编写最小实现**
+
+```python
+from flask import Blueprint, request, jsonify
+
+auth_bp = Blueprint('auth', __name__)
+
+@auth_bp.route('/api/register', methods=['POST'])
+def register():
+    data = request.json
+    # TODO: 实现注册逻辑
+    return jsonify({'user': {'email': data['email']}}), 201
+```
+
+**步骤 4: 运行测试验证通过**
+
+运行：`pytest tests/routes/test_auth.py::test_register -v`
+预期：PASS
+
+**步骤 5: 提交**
+
+```bash
+git add src/routes/auth.py tests/routes/test_auth.py
+git commit -m "feat: 创建注册端点"
+```
+
+---
+```
+
+### 计划审查清单
+
+- [ ] 任务是否按逻辑顺序排列？
+- [ ] 每个任务是否足够小（2-5 分钟）？
+- [ ] 文件路径是否精确？
+- [ ] 代码示例是否完整（可直接复制）？
+- [ ] 命令是否精确，包含预期输出？
+- [ ] 是否包含验证步骤？
+- [ ] 是否应用了 DRY、YAGNI、TDD 原则？
+- [ ] 是否包含中文注释和文档？