---
description: harness-plan 的原生规划协议。吸收 brainstorming、grill-me、writing-plans 的方法论精华，但不运行时依赖外部 skill。
---

# harness-plan 原生规划协议

本文件定义 `/harness-plan` 的内置 planning kernel。它吸收外部 skill 的有效做法，但正式流程不调用 Superpowers、grill-me 或 writing-plans，也不读取或同步 `docs/superpowers/` 作为计划产物。

核心原则：**流程更轻，质量门槛更硬**。删掉外部 skill 检查、Adapter Mode、降级和草稿同步；保留需求澄清、逐问决策、方案对比、任务自检和测试优先。

## 协议一：clarification-protocol

用于阶段 4，目标是把需求从“用户意图”收敛成可审核设计输入。

必须输出以下五类结论。用 `harness_events.py append` 追加 `decision` / `issue` 事件，完整的人类可读结论放进事件 `note`；执行日志仅由事件渲染器派生：

| 输出 | 要求 |
|------|------|
| 风险识别 | 列出会影响实现、测试、数据、兼容性或交付判断的风险 |
| 复用机会 | 明确可复用的既有模块、接口、测试、迁移脚本或历史知识 |
| 替代方案 | 给出 2-3 个可行方案；简单需求可给 1 个主方案 + 1 个不选方案 |
| 推荐方案 | 明确推荐选项和理由，不让用户从空白处决策 |
| 用户确认的关键决策 | 只记录真正影响范围、行为、兼容性或风险的决策 |

执行纪律：

1. 先消费阶段 1 的 context pack、阶段 3 的代码探索结果和项目规则。
2. 能由代码、历史知识、配置、现有文档回答的问题，不问用户。
3. 需要用户裁决时，交给 `decision-grilling-protocol`。
4. 影响面检查必须覆盖用户未显式提到的参数、数据、接口、权限、兼容性、模块引用和测试影响。
5. 低风险工程判断可由 AI 推荐并记录后继续；高风险或业务语义判断必须等待用户确认。
6. **歧义优先检查**：否定、对比、动作对象、范围或保留/删除关系存在多种合理解释时，只做足以定位现状的最小取证，然后先给出推荐理解并确认；不得先沿某一种猜测深挖完整代码路径。
7. 探索中发现的无关问题仅以非阻断 `issue` 记录，不加入当前决策树，不扩展设计范围。

## 协议二：decision-grilling-protocol

用于阶段 4 的用户澄清问题。它借鉴 grill-me 的逐问决策树，但采用有限问题预算，避免仪式化盘问。

### 问题预算

| 场景 | 用户问题上限 |
|------|:---:|
| 信息充分、无必须裁决的问题 | 0 |
| 简单修复 | 0-1 |
| 普通需求 | 1-3 |
| 高风险需求（auth、支付、数据迁移、并发、安全、不可逆删除、用户可见行为变化） | 5-7 |

超过预算仍无法收敛时，不要继续追问；必须输出“未决决策清单”，标记阻塞项，并请用户裁决是否缩小范围或暂停。

用户纠正了最初理解时，立即丢弃错误探索假设；简单修复最多再进行一次定向确认，不因旧探索结果追加连锁问题。

### 提问格式

每次只问一个问题，且必须包含推荐答案：

```markdown
### 需要确认：<决策主题>

我的推荐：<推荐答案>

理由：<为什么这个选择更适合当前代码、历史上下文和风险约束>

取舍：<代价、风险、未来扩展限制>

请确认是否采用该推荐，或指出要调整的方向。
```

### 自动采用与必须确认

可自动采用推荐并记录：
- 文件组织、命名、任务顺序、测试拆分
- 是否复用现有 helper、adapter、测试 fixture
- 不改变用户可见行为的内部实现细节

必须用户确认：
- 需求范围增删、延期或拆分
- 权限、安全、支付、审计、数据迁移、删除行为
- API 契约、错误码、前端兼容、用户可见行为变化
- 不可逆操作或可能影响历史数据的方案

不确定归类时，按“必须确认”处理。

## 协议三：implementation-planning-protocol

用于阶段 6，目标是把已审核设计转成 harness 可执行计划，而不是生成外部超细步骤文档。

### 产物分工

| 产物 | 定位 | 详细度 |
|------|------|--------|
| `<change-name>-plan.md` | 任务真相源 | 简洁任务表：任务、涉及文件、依赖 |
| `<change-name>-implementation-detail.md` | 执行参考 | 按复杂度自适应：关键接口、顺序、坑点、测试策略 |
| `<change-name>-test-scenarios.md` | 测试真相源 | 4 维度测试场景 + 覆盖检查 |

`implementation-detail.md` 必须存在，但不再强制写成 2-5 分钟粒度、逐行代码片段或逐 commit 指令。简单任务可以短，复杂任务必须细。

简单修复的四份产物采用“单点事实、引用不复述”：设计写行为契约，plan 写任务与依赖，detail 写关键修改点与命令，scenarios 写可验证用例。不得复制同一段背景、风险或结论来增加篇幅。

### 计划质量门槛

任务拆分必须满足：

- 每个任务有明确目标、涉及文件和依赖。
- 不出现 `TBD`、`TODO`、`稍后实现`、`补充测试`、`适当处理错误` 等占位表达。
- 不引用尚未定义的类型、函数、接口或迁移文件。
- 层序依赖清晰：数据/契约先于业务实现，业务实现先于接口暴露，验证场景覆盖关键路径。
- 测试方向明确：单元、接口、数据兼容、集成至少说明适用与不适用原因。
- 如果设计范围发生收缩，先按 `change-name` 同步规则处理名称和路径。

### implementation-detail 自适应规则

| 复杂度 | 内容要求 |
|--------|----------|
| 简单修复 | 关键文件、修改点、验证命令、容易误判的边界 |
| 中等功能 | 模块顺序、接口/数据约束、测试策略、回滚/兼容注意事项 |
| 高风险构建 | 迁移顺序、失败恢复、权限/安全边界、并发/幂等、评审关注点 |

禁止为了“看起来完整”生成机械微步骤；也禁止因为“只是参考”而写空泛描述。

## 自检

阶段 4 和阶段 6 完成后，必须自检：

```markdown
### 原生规划协议自检
- clarification-protocol：风险 / 复用 / 替代方案 / 推荐方案 / 关键决策均已记录
- decision-grilling-protocol：用户问题未超预算；每问包含推荐答案；能自查的问题未打扰用户
- implementation-planning-protocol：plan 简表、implementation-detail、test-scenarios 三件套一致，无占位符
```

自检结论直接展示给用户即可，**不要**再追加一条 `verification` 事件——「协议自检通过」不改变
任何结论，只增加监控噪声（roadmap 12 号「事件规则」）。真正影响行为的东西照常留痕：关键决策
追加 `decision`，发现的冲突与阻塞追加 `issue`。渲染器在 `phase.end` 后生成执行日志。