实战笔记：为 Go 项目 issue2md 量身定制 plan.md 模板（含 Constitution Check）

# Plan: [功能名称 / Bug 名称]

> Status: Draft  
> Owner: AI Agent / [Your Name]  
> Related Spec: `./spec.md`  
> Related Constitution: `./constitution.md`  
> Last Updated: [YYYY-MM-DD]

---

## 1. 背景与目标 (Background & Goal)

### 1.1 背景
简要说明当前需求、问题来源或上下文。

示例：
- 需要支持将 GitHub issue 内容转换为 Markdown 文件
- 当前 issue body 渲染逻辑未处理空内容
- CLI 输出路径规则不清晰，导致结果文件位置不可预测

### 1.2 目标
明确这次变更要达成的结果。

示例：
- 支持 issue 标题、正文和元信息的 Markdown 输出
- 修复空 body 场景下的渲染异常
- 统一输出路径行为并补充测试覆盖

### 1.3 非目标 (Non-Goals)
明确这次**不做什么**，防止范围膨胀。

示例：
- 不引入新的 CLI 框架
- 不重构整个 GitHub 客户端
- 不支持尚未在 `spec.md` 中定义的输出格式

keywords: `goal`, `scope`, `non-goals`

---

## 2. 需求理解 (Requirement Understanding)

用简洁条目描述你对需求的理解，确保实现前先对齐。

- 输入是什么？
- 输出是什么？
- 用户可见行为是什么？
- 是否影响现有接口、命令或文件格式？
- 是否有兼容性要求？

示例：
- 输入为 GitHub issue 数据或 issue URL
- 输出为规范化 Markdown 文本或 `.md` 文件
- 用户希望在命令行执行后得到稳定、可预测的 Markdown 输出
- 不能破坏现有命令参数行为

---

## 3. 上下文审查结果 (Context Review)

在开始设计方案前，先列出已审查的文件、模块和结论。

### 3.1 已审查内容
- `./spec.md`
- `./constitution.md`
- `./CLAUDE.md`
- `./cmd/...`
- `./internal/...`
- 相关测试文件
- 与 GitHub API / Markdown 渲染 / 文件输出相关实现

### 3.2 当前实现观察
总结当前实现方式、已有结构和限制。

示例：
- Markdown 渲染逻辑目前与 GitHub 拉取逻辑耦合
- 文件输出路径在 CLI 层直接拼接
- 测试覆盖了正常路径，但缺少空输入和异常响应测试

### 3.3 待确认问题
列出仍不明确、可能影响方案的点。

示例：
- 输出文件命名规则是否应完全由用户指定？
- 空 issue body 是输出空段落，还是直接省略？
- 是否需要保留现有 Markdown 模板格式？

keywords: `review`, `context`, `constraints`

---

## 4. Constitution Check (合宪性审查)

> **GATE:** 必须在进入技术设计前通过。  
> 若任一门禁未通过，必须在“复杂性追踪”中说明理由与权衡。

### 4.1 简单性门禁 (第一条)
- [ ] 是否优先使用 Go 标准库？
- [ ] 是否避免了不必要的抽象？
- [ ] 是否只实现 `spec.md` 已明确要求的功能？
- [ ] 是否避免了为未来需求预留未经确认的扩展点？

### 4.2 测试先行门禁 (第二条)
- [ ] 是否计划先写失败测试，再写实现？
- [ ] 是否优先采用表格驱动测试？
- [ ] 是否优先考虑真实依赖、fake object 或 `httptest`，而不是过度 Mock？

### 4.3 明确性门禁 (第三条)
- [ ] 是否所有错误路径都将被显式处理？
- [ ] 是否明确避免使用全局变量？
- [ ] 是否明确依赖注入方式？
- [ ] 是否计划对公共 API 或复杂逻辑补充必要注释？

### 4.4 单一职责门禁 (第四条)
- [ ] 是否保持包职责清晰？
- [ ] 是否避免将 GitHub API 访问、Markdown 转换、文件输出混杂在同一职责中？
- [ ] 是否避免定义大而全的接口？

### 4.5 审查结论
- [ ] 通过
- [ ] 有例外（必须填写下方复杂性追踪）

keywords: `constitution check`, `gate`, `compliance`

---

## 5. 复杂性追踪 (Complexity Tracking)

如果方案必须突破某些宪法约束，必须在此说明。

### 5.1 未通过项
- [示例] 为兼容现有调用链，本次暂时保留某处耦合结构
- [示例] 由于标准库缺乏某项必要能力，拟引入极小第三方依赖

### 5.2 原因说明
解释为什么不能采用更简单、更直接、更合宪的方案。

### 5.3 替代方案比较
列出至少一个备选方案，并说明为何未采用。

### 5.4 风险与后续处理
说明该复杂性会带来什么风险，后续是否需要偿还技术债。

keywords: `trade-off`, `risk`, `alternative`

---

## 6. 技术方案设计 (Technical Design)

### 6.1 总体思路
用简洁语言描述实现路径。

示例：
- 在 `internal/github` 中补充 issue 获取逻辑
- 在 `internal/markdown` 中封装 Markdown 渲染
- 在 `cmd/...` 或应用编排层组织输入、转换与输出流程

### 6.2 涉及文件
列出可能修改或新增的文件。

示例：
- `cmd/issue2md/main.go`
- `internal/github/client.go`
- `internal/markdown/render.go`
- `internal/output/write.go`
- `internal/.../..._test.go`

### 6.3 模块职责划分
明确每个包/文件负责什么，确保单一职责。

| 模块 | 职责 |
|---|---|
| `internal/github` | 与 GitHub API 交互，获取 issue 数据 |
| `internal/markdown` | 将 issue 数据转换为 Markdown 文本 |
| `internal/output` | 负责写入文件或输出到指定目标 |
| `cmd/...` | 参数解析与执行编排 |

### 6.4 数据流 / 调用流
描述输入如何流转到输出。

示例：
`CLI 参数 -> GitHub 获取 issue -> Markdown 渲染 -> 文件输出`

keywords: `design`, `module`, `data flow`

---

## 7. 实施步骤 (Implementation Steps)

按顺序列出计划步骤，强调先测试后实现。

1. 补充或新增失败测试，覆盖目标场景
2. 审查测试失败原因，确认测试定义符合需求
3. 编写最小实现使测试通过
4. 重构代码，消除重复并保持职责清晰
5. 补充边界条件测试
6. 运行格式化、测试与静态检查
7. 整理变更说明与风险点

如涉及多文件改动，建议说明每一步对应的文件。

---

## 8. 测试计划 (Test Plan)

### 8.1 测试策略
说明将使用哪些测试方式：

- 单元测试
- 表格驱动测试
- 集成测试
- `httptest.Server`
- fake object

### 8.2 核心测试场景
至少列出以下几类：

- 正常路径
- 异常路径
- 边界值
- 空输入 / 缺失字段
- 外部依赖异常（如非 200 响应、超时、无效 JSON）

### 8.3 预期验证点
说明测试将验证什么。

示例：
- Markdown 输出格式是否符合预期
- 空 body 是否正确处理
- GitHub API 错误是否被包装并保留上下文
- 输出文件路径是否稳定可预测

keywords: `test plan`, `table-driven`, `httptest`

---

## 9. 风险分析 (Risk Analysis)

列出可能风险及应对方式。

| 风险 | 说明 | 应对措施 |
|---|---|---|
| 输出格式兼容性 | 修改 Markdown 结构可能影响现有使用者 | 增加回归测试，保持默认格式不变 |
| 外部 API 异常 | GitHub 响应非预期 | 补充异常响应测试与错误包装 |
| 职责耦合 | 逻辑堆积在 CLI 层 | 拆分到独立包并明确职责 |

keywords: `risk`, `mitigation`

---

## 10. 验收标准 (Acceptance Criteria)

用可验证的方式描述“何时算完成”。

- [ ] 功能满足 `spec.md` 中对应要求
- [ ] 测试先写并通过
- [ ] 新增/修改测试覆盖正常路径、异常路径与边界情况
- [ ] 实现符合 `constitution.md`
- [ ] 未引入不必要依赖
- [ ] 错误处理具有充分上下文
- [ ] 代码职责清晰、易于理解
- [ ] 输出行为与用户预期一致

keywords: `acceptance criteria`, `done`

---

## 11. 变更摘要模板 (Change Summary)

在任务完成后可回填本节。

### 11.1 实际改动
- 修改了哪些文件
- 每个改动的目的是什么

### 11.2 测试结果
- 新增了哪些测试
- 覆盖了哪些场景
- 测试是否全部通过

### 11.3 偏差说明
- 实际实现与原计划是否有偏差
- 如果有，原因是什么

### 11.4 后续建议
- 是否存在可选优化项
- 是否需要补充文档或清理技术债

学霸式拆解

一、这份 plan.md 的核心作用

1. 不是“随便写个计划”

它本质上是 AI 的实现前约束面板。

2. 它主要解决什么问题

• 防止 AI 跳过上下文审查
• 防止 AI 不做合宪性检查
• 防止 AI 直接编码导致方案跑偏
• 防止需求范围膨胀
• 防止测试滞后

3. 一句话理解

plan.md 是把“先想清楚再动手”制度化的工具。

keywords: plan, workflow, gate

二、为什么一定要有 Constitution Check

1. 因为“原则”必须转成“检查项”

如果只有 constitution.md，AI 可能知道这些原则，但不一定在每次任务中主动执行检查。

2. 加进 plan.md 后会发生什么

AI 在生成计划时，必须逐条回答：

• 简不简单？
• 有没有先测？
• 是否显式？
• 职责是否清晰？

这就把抽象原则变成了具体门禁。

3. 本质

Constitution Check = 原则的流程化执行器

keywords: constitution check, checklist

三、这份模板的结构逻辑

它的设计顺序其实非常科学：

背景目标
→ 需求理解
→ 上下文审查
→ 合宪性审查
→ 技术方案
→ 实施步骤
→ 测试计划
→ 风险分析
→ 验收标准

这个顺序符合真实工程思维。

原因

• 没有目标，方案就会漂
• 没有上下文，设计就会猜
• 没有合宪检查，方案就可能跑偏
• 没有测试计划，质量就不稳定
• 没有验收标准，完成就不可判断

四、最值得背的 4 个部分

1. Context Review

确保先读再改。
keywords: review

2. Constitution Check

确保先合宪再设计。
keywords: compliance

3. Implementation Steps

确保先测后写。
keywords: TDD

4. Acceptance Criteria

确保完成标准清晰。
keywords: done

五、推荐搭配方式

建议和这几个文件一起使用：

issue2md/
├─ constitution.md
├─ CLAUDE.md
├─ spec.md
└─ plan.md

分工记忆

• constitution.md：最高原则
• CLAUDE.md：AI 协作流程
• spec.md：需求定义
• plan.md：执行计划与合宪性检查

六、速记版

# 速记

## plan.md 的作用
- 不是普通计划
- 是实现前控制面板

## 核心模块
- 背景与目标
- 需求理解
- 上下文审查
- Constitution Check
- 技术方案
- 实施步骤
- 测试计划
- 风险分析
- 验收标准

## Constitution Check 检查什么
- 简单性
- 测试先行
- 明确性
- 单一职责

## 本质
plan.md = 把抽象原则变成可执行门禁