# Writing Plans

> |

- **Type:** Skill
- **Install:** `agentstack add skill-hhhh124hhhh-skillmate-writing-plans`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [hhhh124hhhh](https://agentstack.voostack.com/s/hhhh124hhhh)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [hhhh124hhhh](https://github.com/hhhh124hhhh)
- **Source:** https://github.com/hhhh124hhhh/SkillMate/tree/main/resources/skills/writing-plans

## Install

```sh
agentstack add skill-hhhh124hhhh-skillmate-writing-plans
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 编写战略文档

## 概述

编写全面的实施计划，假设工程师对代码库零上下文。

**核心原则**：文档化实施所需的一切信息。

**开始时声明**："我正在使用 writing-plans 技能创建实施计划。"

**上下文**：应在专用工作树中运行（由 brainstorming 技能创建）。

**保存位置**：`docs/plans/YYYY-MM-DD-.md`

## 任务粒度

**每个步骤一个操作（2-5 分钟）**：
- "编写失败测试" - 步骤
- "运行测试验证失败" - 步骤
- "编写最小代码通过测试" - 步骤
- "运行测试验证通过" - 步骤
- "提交" - 步骤

## 计划文档头部

**每个计划必须以此头部开始**：

```markdown
# [功能名称] 实施计划

> **对于 Claude**：必需子技能：使用 superpowers:executing-plans 逐步实施此计划。

**目标**：[一句话描述此计划构建的内容]

**架构**：[2-3 句话说明方法]

**技术栈**：[关键技术/库]

---
```

## 任务结构

```markdown
### 任务 N：[组件名称]

**文件**：
- 创建：`exact/path/to/file.py`
- 修改：`exact/path/to/existing.py:123-145`
- 测试：`tests/exact/path/to/test.py`

**步骤 1：编写失败测试**

```python
def test_specific_behavior():
    result = function(input)
    assert result == expected
```

**步骤 2：运行测试验证失败**

运行：`pytest tests/path/test.py::test_name -v`
预期：FAIL，显示 "function not defined"

**步骤 3：编写最小实现**

```python
def function(input):
    return expected
```

**步骤 4：运行测试验证通过**

运行：`pytest tests/path/test.py::test_name -v`
预期：PASS

**步骤 5：提交**

```bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
```
```

## 记住

- 始终提供精确文件路径
- 计划中包含完整代码（不是"添加验证"）
- 包含预期输出的精确命令
- 使用 @ 语法引用相关技能
- DRY、YAGNI、TDD、频繁提交

## 执行交接

保存计划后，提供执行选择：

**"计划完成并保存到 `docs/plans/.md`。两种执行选项："**

**1. 子代理驱动（当前会话）** - 我为每个任务分派新的子代理，任务间审查，快速迭代

**2. 并行会话（独立）** - 在工作树中打开新会话，使用 executing-plans 批量执行并设置检查点

**选择哪种方式？**

**如果选择子代理驱动**：
- **必需子技能**：使用 superpowers:subagent-driven-development
- 留在当前会话
- 每个任务使用新子代理 + 代码审查

**如果选择并行会话**：
- 引导他们在工作树中打开新会话
- **必需子技能**：新会话使用 superpowers:executing-plans

## 计划示例

### 简单功能

```markdown
### 任务 1：创建用户模型

**文件**：
- 创建：`src/models/user.py`
- 测试：`tests/models/test_user.py`

**步骤 1：编写用户模型测试**

```python
import pytest
from user import User

def test_create_user():
    user = User("Alice", "alice@example.com")
    assert user.name == "Alice"
    assert user.email == "alice@example.com"

def test_invalid_email():
    with pytest.raises(ValueError):
        User("Bob", "invalid-email")
```

**步骤 2：运行测试验证失败**

```bash
pytest tests/models/test_user.py -v
# 预期：ImportError 或 ModuleNotFoundError
```

**步骤 3：实现用户模型**

```python
import re

class User:
    def __init__(self, name: str, email: str):
        if not self._validate_email(email):
            raise ValueError("Invalid email format")
        self.name = name
        self.email = email

    @staticmethod
    def _validate_email(email: str) -> bool:
        pattern = r'^[\w\.-]+@[\w\.-]+\.\w+$'
        return re.match(pattern, email) is not None
```

**步骤 4：运行测试验证通过**

```bash
pytest tests/models/test_user.py -v
# 预期：2 passed
```

**步骤 5：提交**

```bash
git add src/models/user.py tests/models/test_user.py
git commit -m "feat: add user model with email validation"
```
```

### 复杂功能

```markdown
### 任务 3：实现 API 认证中间件

**文件**：
- 创建：`src/middleware/auth.py`
- 修改：`src/app.py:45-60`
- 测试：`tests/middleware/test_auth.py`

**步骤 1：编写认证测试**

```python
import pytest
from middleware.auth import authenticate
from fastapi import Request

@pytest.mark.asyncio
async def test_valid_token():
    token = "valid-token-123"
    request = Request(headers={"Authorization": f"Bearer {token}"})
    result = await authenticate(request)
    assert result == True

@pytest.mark.asyncio
async def test_missing_token():
    request = Request(headers={})
    with pytest.raises(HTTPException) as exc:
        await authenticate(request)
    assert exc.value.status_code == 401
```

**步骤 2：运行测试验证失败**

```bash
pytest tests/middleware/test_auth.py -v
# 预期：ImportError
```

**步骤 3：实现认证中间件**

```python
from fastapi import Request, HTTPException
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials

security = HTTPBearer()

async def authenticate(request: Request) -> bool:
    try:
        credentials: HTTPAuthorizationCredentials = await security(request)
        token = credentials.credentials

        # 验证 token
        if not validate_token(token):
            raise HTTPException(status_code=401, detail="Invalid token")

        return True
    except Exception:
        raise HTTPException(status_code=401, detail="Missing or invalid token")

def validate_token(token: str) -> bool:
    # Token 验证逻辑
    valid_tokens = {"valid-token-123"}
    return token in valid_tokens
```

**步骤 4：集成到应用**

```python
# src/app.py
from middleware.auth import authenticate

@app.api_route("/protected")
@authenticate  # 添加认证装饰器
async def protected_endpoint():
    return {"message": "Access granted"}
```

**步骤 5：运行测试验证通过**

```bash
pytest tests/middleware/test_auth.py -v
# 预期：2 passed
```

**步骤 6：提交**

```bash
git add src/middleware/auth.py src/app.py tests/middleware/test_auth.py
git commit -m "feat: add JWT authentication middleware"
```
```

## 完整计划模板

```markdown
# [功能名称] 实施计划

> **对于 Claude**：必需子技能：使用 superpowers:executing-plans 逐步实施此计划。

**目标**：[一句话描述]

**架构**：[2-3 句话]

**技术栈**：[关键技术]

**依赖**：
- [ ] 依赖 1 已安装
- [ ] 依赖 2 已配置

**背景**：
- 当前实现：[现状]
- 问题陈述：[为什么需要此功能]
- 成功标准：[如何验证完成]

---

## 任务分解

### 任务 1：[第一个组件]
[详细步骤...]

### 任务 2：[第二个组件]
[详细步骤...]

...

## 验证清单

完成此计划后：
- [ ] 所有测试通过
- [ ] 代码符合项目风格
- [ ] 文档已更新
- [ ] 功能符合要求
```

## 最佳实践

### 1. 具体 > 抽象

**好的**：
```markdown
创建文件 `src/models/user.py`，实现以下类：
```python
class User:
    def __init__(self, name: str, email: str):
        ...
```
```

**不好的**：
```markdown
创建用户模型，处理验证。
```

### 2. 包含完整代码

**好的**：
```markdown
实现完整的函数：
```python
def function(param):
    # 完整实现
    return result
```
```

**不好的**：
```markdown
添加验证逻辑（3-5 行）
```

### 3. 精确命令

**好的**：
```markdown
运行：`pytest tests/test_user.py::test_create_user -v`
预期：PASS
```

**不好的**：
```markdown
运行测试验证功能
```

## 与其他技能的集成

**工作流程**：
1. **brainstorming** - 设计功能
2. **using-git-worktrees** - 创建隔离环境
3. **writing-plans** - 编写详细计划 ⬅️ 这里
4. **executing-plans** 或 **subagent-driven-development** - 实施
5. **requesting-code-review** - 审查实施
6. **finishing-a-development-branch** - 完成并清理

## 常见陷阱

**避免**：
- ❌ 计划过于抽象（"添加验证"）
- ❌ 跳过步骤（"测试并实现"）
- ❌ 假设上下文（"修改 API 处理程序"）
- ❌ 缺少验证步骤

**推荐**：
- ✅ 具体文件路径和行号
- ✅ 计划中包含完整代码
- ✅ 每个任务 2-5 分钟
- ✅ 包含验证和提交步骤

## 关键原则

- **精确路径**：始终提供精确文件路径
- **完整代码**：计划中包含完整代码
- **小步快跑**：每个任务 2-5 分钟
- **验证每步**：每个步骤都有验证
- **频繁提交**：每个任务后提交
- **引用技能**：使用 @ 语法引用相关技能

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [hhhh124hhhh](https://github.com/hhhh124hhhh)
- **Source:** [hhhh124hhhh/SkillMate](https://github.com/hhhh124hhhh/SkillMate)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-hhhh124hhhh-skillmate-writing-plans
- Seller: https://agentstack.voostack.com/s/hhhh124hhhh
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.