附录 B：提示词与模板合集¶

这一章是“复制就能用”的提示词库。所有提示词都遵循同一个结构：角色 + 输入 + 任务 + 约束 + 输出格式 + 停止条件。你可以按项目替换占位符。

0. 提示词写作的六个要素¶

1. 角色：你是谁（资深产品经理/架构师/测试工程师）
2. 输入：读哪些文件、哪些是事实、哪些是假设
3. 任务：具体做什么，不要做什么
4. 约束：边界、规范、禁止事项
5. 输出：文件路径、格式、结构
6. 停止条件：什么时候停下来问人

反例：

帮我做一个任务管理系统。

正例：

你是资深架构师。请基于 @docs/00-discovery/spec.md 和
@docs/00-discovery/user-story.csv 生成技术设计。
只覆盖 P0/P1 故事，不发明新需求。
输出 docs/01-design/tech-design.md，按 @模板/tech-design.md 的结构。
遇到契约缺失，列入“未决问题”，不要猜。

1. 通用：项目启动¶

1.1 生成 `CLAUDE.md`¶

你是本项目的主程。请阅读以下文件：
- README.md
- docs/00-discovery/spec.md
- docs/01-design/tech-design.md
- Makefile / package.json / go.mod

请生成/更新 `CLAUDE.md`，要求：
1. 控制在 250 行以内。
2. 包含：项目一句话、技术栈、目录、常用命令、编码约定、禁止事项、完成定义。
3. 命令必须是可以直接复制执行的。
4. 详细内容用链接指向 docs/，不要粘贴全文。
5. 不要写“请努力”“要仔细”这类无法执行的指令。
6. 输出后自查：新成员看完能否独立跑起来？

1.2 项目上下文摘要¶

请阅读 @CLAUDE.md、@docs/00-discovery/spec.md、@docs/01-design/tech-design.md，
输出一份 20 行以内的项目摘要，包含：
- 产品目标
- 核心用户
- 技术栈
- 当前阶段
- 最重要的 3 个约束
- 下一步要做什么
不要输出文件内容，只输出摘要。

2. 需求阶段¶

2.1 需求访谈¶

你是资深产品经理兼需求分析师。请阅读 @docs/00-discovery/raw-notes.md。

现在不要写方案。请一次性提出最多 12 个澄清问题，覆盖：
目标用户、核心场景、非目标、数据实体、权限、集成、合规、
成功指标、上线约束、运维。

要求：
1. 每个问题给 2-3 个可选答案，标出推荐项和理由。
2. 优先问“答案会显著改变技术方案”的问题。
3. 能从原始记录推断的不要重复问。
4. 输出表格：编号、问题、选项、推荐、影响。

2.2 生成规格¶

你是资深产品经理。请基于以下材料生成 `docs/00-discovery/spec.md`：
- 原始记录：@docs/00-discovery/raw-notes.md
- 访谈回答：@docs/00-discovery/interview-answers.md
- 模板：@模板/spec.md

要求：
1. 严格按模板结构。
2. 每个功能需求用 FR-xxx 编号，规则必须可测试。
3. 每个功能需求至少写一个异常分支。
4. 明确“非目标”和“范围之外”。
5. 不发明未提供的信息；不确定的列入“假设与待确认问题”。
6. 输出前自查：有没有矛盾？有没有不可测试的形容词？

2.3 需求批判¶

你是苛刻的需求评审专家。请审查 @docs/00-discovery/spec.md。

找出：
1. 模糊、不可测试的需求（给原文和改写建议）
2. 互相矛盾的需求
3. 缺失的异常流程（失败、超时、权限不足、空数据）
4. 缺失的权限边界
5. 范围蔓延风险
6. 技术上不可行/成本过高的地方
7. 应该拆分的过大需求

输出表格：编号、位置、问题、影响、建议。
不要改文件。

2.4 拆分用户故事¶

你是资深敏捷教练。请基于 @docs/00-discovery/spec.md 拆分用户故事。

要求：
1. 格式：作为…我希望…以便…
2. 每个故事至少 1 个正常路径 + 2 个异常路径的 Given/When/Then。
3. 标注：模块、优先级、依赖、数据实体、故事点。
4. 每个故事必须能独立开发、测试、演示。
5. 不按技术层拆，按用户价值拆。
6. 超过 8 个故事点继续拆。
7. 先输出 Markdown 表格，再输出 CSV 行。

2.5 需求追溯检查¶

请检查 @docs/00-discovery/spec.md、user-story.csv、user-story-details.md 的一致性。

输出：
1. 每个 FR 是否至少有一个用户故事
2. 每个用户故事是否有验收标准
3. 每个验收标准是否可测试
4. 是否有故事没有对应 FR
5. 是否有 FR 没有故事
6. 依赖是否有循环
7. 缺失项矩阵

不要改文件，只输出检查结果。

3. UI 阶段¶

3.1 页面清单¶

你是资深 UI/UX 设计师。请阅读：
- @docs/00-discovery/spec.md
- @docs/00-discovery/user-story.csv
- @docs/02-ui/design-tokens.json

输出页面清单：
| 页面 ID | 名称 | 路由 | 故事 | 主要组件 | 状态 |

状态至少包括：默认、加载、空、错误、无权限、成功反馈。
不要画图，只输出清单和信息架构。

3.2 设计系统¶

你是设计系统专家。请为以下产品生成设计 token：
- 产品：<描述>
- 气质：<专业/清爽/活泼/…>
- 用户：<描述>
- 支持浅色模式；深色模式可选

输出：
1. 颜色（品牌 50-900、中性 0-900、语义色）
2. 字体（family、字号、字重、行高）
3. 间距（4px 基准）
4. 圆角、阴影
5. 使用规则
6. 对比度检查
输出 JSON + CSS 变量两版。

3.3 从 Figma 提取规格¶

请读取我在 Figma 中选中的 frame。

输出严格按以下结构：
1. 页面结构树（最多 4 层，标注角色）
2. 布局参数（flex/grid、宽高、间距、对齐）
3. 使用的 token（颜色/字体/间距/圆角/阴影）
4. 组件实例及变体
5. 状态清单（默认/加载/空/错误/无权限）
6. 响应式规则（1440/1024/390）
7. 交互说明（hover/focus/点击/拖拽）
8. 不确定的地方（列出，不要猜）

不要生成代码。

3.4 设计批判¶

你是苛刻的设计评审专家。请审查 @docs/02-ui/screens/<page>.png 和 @docs/02-ui/ui-spec.md。

找出：
1. 信息层级不清
2. 视觉不一致
3. 缺失状态
4. 可访问性问题（对比度、键盘、触控目标）
5. 响应式问题
6. 文案问题
7. 过度设计

输出表格：问题、位置、严重度、建议。
不要改文件。

4. 前端阶段¶

4.1 静态原型¶

你是资深前端工程师。请生成静态 HTML/CSS 原型：
- 页面：<P-xxx>
- 规格：@docs/02-ui/ui-spec.md#<anchor>
- token：@docs/02-ui/design-tokens.json
- 设计稿：@docs/02-ui/screens/<file>.png

要求：
1. 单文件 HTML，可直接浏览器打开。
2. 引入 tokens.css，不写死颜色/间距。
3. 语义化 HTML5。
4. 通过 ?state=default|loading|empty|error 切换状态。
5. 1440/1024/390 三个断点。
6. 不引入框架。
7. 内联 SVG 图标。
8. hover/focus 样式。
9. 输出后自查：魔法值、div 滥用、缺失状态。

4.2 Vue 页面¶

你是资深 Vue 3 + TypeScript 工程师。请实现 <P-xxx> 页面。

输入：
- UI 规格：@docs/02-ui/ui-spec.md#<anchor>
- OpenAPI：@docs/01-design/api/openapi.yaml
- 生成类型：@frontend/src/api/types.ts
- 现有组件：@frontend/src/components/ui/
- 项目约定：@CLAUDE.md

要求：
1. 只改 <授权文件>。
2. 处理 loading/empty/error/no-permission。
3. 颜色/间距用 CSS 变量。
4. 使用 useAsync 统一请求。
5. 不直接 fetch/axios，用 src/api/<module>.ts。
6. 写 Vitest 测试，覆盖四种状态。
7. 运行 typecheck/test/lint，全绿。
8. 输出改动清单和测试结果。

4.3 接 API¶

请把 <页面/组件> 从 mock 数据切换到真实 API。

输入：
- API：@docs/01-design/api/openapi.yaml#<operationId>
- 类型：@frontend/src/api/types.ts
- 现有 client：@frontend/src/api/client.ts

要求：
1. 使用统一 API client。
2. 类型来自 OpenAPI 生成文件，不手写重复类型。
3. 处理 loading/empty/error/no-permission。
4. 错误显示具体信息，保留用户输入。
5. 提交中禁用按钮。
6. 成功后更新本地状态，不整页刷新。
7. 补测试。

4.4 组件重构¶

请把 <组件> 中重复的 <部分> 抽成 <新组件>。

约束：
- 不改变视觉和交互。
- Props/Emits 用 TypeScript 定义。
- 新组件放在 <路径>。
- 补单元测试。
- 运行 typecheck/lint/test。
- 输出前后对比和测试结果。

4.5 前端审查¶

你是前端代码审查专家。请审查 <文件/分支>。

检查：
1. 魔法颜色/间距
2. 五种状态
3. 未取消的请求
4. 直接使用 axios/fetch
5. 可访问性
6. 重复组件
7. any/@ts-ignore
8. 测试覆盖行为
9. 密钥泄露

输出表格：文件、行号、问题、严重度、建议。
不要改代码。

5. 后端 / 技术设计阶段¶

5.1 技术选型 ADR¶

你是资深架构师。请为 <项目> 选择后端技术栈。

输入：
- 需求：@docs/00-discovery/spec.md
- 团队：<人数/经验>
- 约束：<时间/预算/部署环境>
- 候选：Go / Java / Rust

请输出 ADR：
1. 背景
2. 决策
3. 理由
4. 备选方案及不选原因
5. 后果（优点/缺点/风险）
6. 迁移/退出策略

5.2 技术设计¶

你是资深架构师。请基于以下输入生成技术设计：
- 需求：@docs/00-discovery/spec.md
- 用户故事：@docs/00-discovery/user-story.csv
- 故事细节：@docs/00-discovery/user-story-details.md
- UI：@docs/02-ui/ui-spec.md
- 技术选型：@docs/01-design/adr/<adr>.md

输出：
1. docs/01-design/tech-design.md
2. docs/01-design/api/openapi.yaml
3. docs/01-design/db/schema.sql
4. docs/01-design/feature-implementation.md
5. docs/01-design/file-ownership.md
6. docs/01-design/test-strategy.md
7. docs/01-design/deployment.md
8. 更新 CLAUDE.md

约束：
- 不发明需求；不确定的列入“未决问题”。
- 统一错误格式/分页格式。
- 考虑多租户、审计、软删除。
- 请求隔离规则具体。
- 每个决策说明理由和替代方案。
- 输出前自查：故事是否有 API/表/测试。

5.3 架构批判¶

你是苛刻的架构评审专家。请审查：
- @docs/01-design/tech-design.md
- @docs/01-design/api/openapi.yaml
- @docs/01-design/db/schema.sql
- @docs/01-design/feature-implementation.md

找出：
1. 无法支撑需求的缺口
2. 前后端契约不一致
3. DB 约束/索引/迁移风险
4. 权限漏洞
5. 并发/事务/幂等风险
6. 单点/扩展性问题
7. 测试盲区
8. 过度设计
9. 文件所有权冲突
10. 缺失回滚

输出表格：编号、位置、问题、影响、建议、严重度。

5.4 API 契约生成¶

你是 API 设计专家。请为以下用户故事生成 OpenAPI 3.1 契约：
@docs/00-discovery/user-story-details.md#<story>

要求：
1. 统一错误格式 `{error:{code,message,request_id,details}}`。
2. 统一分页格式。
3. 所有字段有类型/约束/示例。
4. 所有错误响应有 schema。
5. 写操作支持 Idempotency-Key（如适用）。
6. 时间用 ISO 8601 UTC。
7. 输出 operationId、summary、security。
8. 通过 redocly/spectral lint。

5.5 数据库设计¶

你是数据库设计专家。请基于以下故事生成 schema：
@docs/00-discovery/user-story-details.md#<story>

要求：
1. 主键/外键/唯一约束。
2. 高频查询索引。
3. 软删除/审计/多租户字段。
4. 状态字段和检查约束。
5. 迁移文件名和顺序。
6. 大表变更策略。
7. 回滚方案。
输出 PostgreSQL DDL + 设计说明。

6. 编码阶段¶

6.1 Agent 任务书¶

# Agent 任务书：<STORY_ID> <标题>

## 角色
你是 <后端/前端/测试> 工程师，负责 <STORY_ID>。

## 目标
<一句话目标>

## 必读
- CLAUDE.md
- docs/01-design/api/openapi.yaml#<operationId>
- docs/01-design/db/schema.sql#<table>
- docs/01-design/feature-implementation.md#<anchor>
- docs/01-design/file-ownership.md

## 文件所有权
可改：
- <path>
禁止改：
- <path>

## 契约
- API：<operationId>
- 错误码：<list>
- 幂等：<策略>
- 事务：<边界>

## 验收标准
<AC-1 ~ AC-n>

## 测试要求
- <unit>
- <integration>
- 命令：<command>

## 完成定义
- 编译通过
- 测试全绿
- lint/vet 通过
- 生成报告
- 更新 CSV
- 提交 Git

## 停止条件
- 契约冲突 → 输出 CR
- 需要改共享文件 → 输出变更请求
- 测试无法通过 → 附日志
- 需求缺失 → 列出问题

6.2 后端实现¶

请实现 <STORY_ID> 的后端功能。

输入：
- 任务书：<粘贴或引用>
- 契约：@docs/01-design/api/openapi.yaml#<operationId>
- 实现细节：@docs/01-design/feature-implementation.md#<anchor>

流程：
1. 读契约，列出实现计划（≤10 步），等我确认。
2. 先写 failing test。
3. 实现最小代码让测试通过。
4. 补边界/权限/错误码测试。
5. 跑 `go test -race ./...`、`go vet ./...`、lint。
6. 生成功能报告。
7. 更新 CSV（用脚本）。
8. 提交。

禁止：
- 改未授权文件
- 删/跳过测试
- 改契约
- 输出密钥/令牌

6.3 前端实现¶

请实现 <STORY_ID> 的前端功能。

输入：
- UI：@docs/02-ui/ui-spec.md#<anchor>
- API 类型：@frontend/src/api/types.ts
- 组件库：@frontend/src/components/ui/
- 任务书：<粘贴或引用>

流程：
1. 列出组件拆解和状态清单。
2. 实现页面/组件。
3. 处理 loading/empty/error/no-permission。
4. 接 API，使用统一 client。
5. 写 Vitest 测试。
6. 跑 typecheck/lint/test/build。
7. 截图（Chrome MCP）并保存到 docs/04-qa/screens/。
8. 生成报告。

6.4 集成¶

你是集成工程师。请按顺序合并以下分支：
<分支列表>

要求：
1. 每次合并后跑 make test / make lint。
2. 冲突时停止，输出冲突文件和原因，不要盲目 ours/theirs。
3. 合并后跑全量测试 + race。
4. 更新 CSV。
5. 生成集成报告。
6. 测试失败时定位到故事，通知对应 Agent，不要自己改业务逻辑。

6.5 Bug 修复¶

请修复 <BUG_ID>。

输入：
- 缺陷：docs/04-qa/defects.md#<anchor>
- 失败 manifest：docs/04-qa/manifests/<story>.json
- 截图：<path>
- 日志：<关键日志，不要全量>

要求：
1. 先写复现测试。
2. 修根因，不要只改表面。
3. 跑相关测试 + 全量测试。
4. 更新缺陷状态和修复提交。
5. 不改无关文件。
6. 输出根因、修复、测试结果。

6.6 代码审查¶

你是资深代码审查员。请审查 <分支/PR>。

输入：
- diff：<git diff>
- 故事：<details>
- 契约：<openapi>
- 实现细节：<feature-implementation>

按维度审查：
1. 契约一致性
2. 权限与安全
3. 事务/并发/幂等
4. 错误处理
5. 测试质量
6. 可观测性
7. 可维护性
8. 未授权文件改动
9. 敏感信息泄露

输出 P0/P1/P2 问题，附文件/行号/建议。
不要改代码。

7. 测试阶段¶

7.1 E2E¶

你是 E2E 测试工程师。请用 Chrome MCP 验证 <STORY_ID>。

环境：
- 前端：<url>
- API：<url>
- 测试账号：<从环境变量读取>
- 数据前缀：e2e-<run_id>-<story>-

步骤：
1. 登录。
2. 进入 <页面>。
3. <操作>
4. 断言 <预期>。
5. 异常路径：<...>
6. 每一步：关键截图保存，JS 断言，写入 manifest。
7. 结束检查 console/network/5xx。
8. 生成 docs/04-qa/manifests/<story>.json。
9. 输出摘要，不贴大段 HTML。

约束：
- 只操作测试数据。
- 截图只保存，不回读模型。
- 失败保留现场，不继续瞎点。

7.2 测试质量审查¶

你是测试审查专家。请审查 <测试文件/目录>。

检查：
1. 是否真的会失败（是否有有效断言）
2. 是否覆盖正常/异常/权限/边界
3. 是否使用真实依赖（集成测试）
4. 是否有并发测试
5. 是否有跳过/删除测试
6. 是否只调用不断言
7. 是否有硬编码测试数据

输出问题列表 + 建议补充的用例。

7.3 Word 报告生成¶

请基于 @docs/04-qa/manifests/<story>.json 生成 Word 验收报告。

要求：
1. 使用 scripts/build_test_report.py。
2. 包含：封面、概要、环境、验收标准覆盖、步骤+截图、控制台/网络错误、缺陷、结论。
3. 中文字体设置为 Microsoft YaHei。
4. 截图宽度 6.2 英寸。
5. 敏感信息脱敏。
6. 输出 docs/04-qa/e2e-report-<env>-<date>.docx。
7. 生成后检查图片数量和文件大小。

7.4 人工走查辅助¶

请把 <Word 报告> 中的可疑点整理成清单：
- 截图与预期不一致
- 错误提示不清晰
- 缺少状态
- 文案问题
- 性能问题
- 权限异常

每条给：页码/步骤、问题、建议、严重度。
不要改代码。

8. 部署与线上¶

8.1 部署准备（不执行）¶

你是发布工程师。请准备 <env> 发布，但不要执行。

输入：
- 版本：<commit/tag>
- 变更：<release notes>
- 回滚版本：<previous>
- 迁移：<files>

输出：
1. 发布前检查清单逐项结果
2. 将要执行的命令（按顺序）
3. 每步验证方法
4. 回滚命令
5. 风险和注意事项

等我回复“批准发布”后再执行。

8.2 部署执行¶

请把 <tag> 部署到 <env>。

前提：
- CI 全绿
- 人工已批准
- 目标：<cluster/service/bucket>

步骤：
1. 确认 `aws sts get-caller-identity` 是 <env> 账号。
2. 构建/推送镜像。
3. 更新服务并等待稳定。
4. 前端构建/同步/失效。
5. 冒烟：/healthz、/readyz、首页 200。
6. 输出镜像 tag、任务定义版本、时间、冒烟结果。
7. 更新发布记录和 CSV。

约束：
- 不操作其他环境。
- 不改 IaC。
- 凭证/权限错误立即停止。

8.3 线上验证¶

你是生产验证工程师。请用 Chrome MCP 在生产验证 <STORY_ID>。

环境：
- URL：<prod>
- 版本：<version>
- 测试账号/租户：<...>
- 数据前缀：e2e-<run_id>-<story>-

安全约束：
1. 只操作测试租户/带前缀数据。
2. 不删除/修改非本次数据。
3. 不触发支付/群发/真实通知。
4. 不修改权限/配置。
5. 报告脱敏。
6. 遇到真实数据立即停止。

步骤：<...>
输出：manifest、截图、Word 报告、摘要。
失败时：保留证据，停止写操作，报告是否回滚。

8.4 事故复盘¶

你是事故复盘负责人。请基于以下信息生成复盘：
- 时间线
- 影响面
- 根因
- 处置过程
- 证据（日志/指标/request_id）

输出：
1. 事故摘要
2. 时间线
3. 根因分析（5 Whys）
4. 做得好/待改进
5. 行动项（负责人/截止日期）
6. 防止复发的测试/监控/流程变更
不要指责任何人，聚焦系统改进。

9. 上下文与项目管理¶

9.1 会话启动¶

请先阅读 @CLAUDE.md，然后阅读 <当前故事相关文件>。
用 10 行以内总结：
- 当前任务
- 契约要点
- 你的文件边界
- 完成标准
- 你不确定的地方
等我确认后再开始。

9.2 上下文压缩¶

请把当前会话的进展总结成一份交接文档：
- 已完成
- 未完成
- 关键决策
- 修改的文件
- 测试状态
- 下一步
- 风险
输出到 docs/03-dev/handoff-<story>-<date>.md。

9.3 任务拆分¶

请把 <STORY_ID> 拆成可由一个 Agent 在 1-2 小时内完成的步骤。
每步包含：
- 目标
- 修改文件
- 测试
- 完成信号
- 依赖
不要按技术层拆得太碎，按可验证的增量拆。

9.4 变更请求¶

请为以下契约变更生成 CR：
- 变更内容
- 原因
- 影响的 API/表/前端/测试
- 兼容性
- 迁移方案
- 回滚方案
输出 docs/01-design/change-requests/CR-<id>.md。

10. 模板索引¶

模板	路径	用途
规格说明书	模板/spec.md	需求阶段
用户故事 CSV	模板/user-story.csv	状态总表
故事细节	模板/user-story-details.md	实现细节
技术设计	模板/tech-design.md	架构
功能实现细节	模板/feature-implementation.md	施工图
项目宪法	模板/CLAUDE.md	AI 约定
常用命令	模板/Makefile	dev/test/lint/e2e/report
Agent 任务书	模板/agent-brief.md	并行开发
功能报告	模板/feature-report.md	每故事一份
E2E manifest	模板/e2e-manifest.json	测试证据
部署检查清单	模板/deploy-checklist.md	发布
QA 检查清单	模板/qa-checklist.md	验收

11. 提示词反模式¶

反模式	问题	修正
“帮我做个系统”	没有范围	先访谈，再 spec
“代码写好点”	不可执行	明确规范/测试/门禁
“你自己看着办”	AI 会发明	给契约和边界
“全部做完再告诉我”	无法纠偏	小步、每步验证
“不要问我，直接做”	错误累积	关键决策停下来问
“把整个仓库读一遍”	token 爆炸	`rg` 定位 + 精确引用
“截图给我看”	成本高	文本/JS 优先
“测试过了就行”	可能是假测试	审查测试 + E2E
“先上线再说”	事故	门禁 + 回滚
“AI 说完成了”	没有证据	DoD + 证据链

返回：完整导读｜附录 A

附录 B：提示词与模板合集¶

0. 提示词写作的六个要素¶

1. 通用：项目启动¶

1.1 生成 CLAUDE.md¶

1.2 项目上下文摘要¶

2. 需求阶段¶

2.1 需求访谈¶

2.2 生成规格¶

2.3 需求批判¶

2.4 拆分用户故事¶

2.5 需求追溯检查¶

3. UI 阶段¶

3.1 页面清单¶

3.2 设计系统¶

3.3 从 Figma 提取规格¶

3.4 设计批判¶

4. 前端阶段¶

4.1 静态原型¶

4.2 Vue 页面¶

4.3 接 API¶

4.4 组件重构¶

4.5 前端审查¶

5. 后端 / 技术设计阶段¶

5.1 技术选型 ADR¶

5.2 技术设计¶

5.3 架构批判¶

5.4 API 契约生成¶

5.5 数据库设计¶

6. 编码阶段¶

6.1 Agent 任务书¶

6.2 后端实现¶

6.3 前端实现¶

6.4 集成¶

6.5 Bug 修复¶

6.6 代码审查¶

7. 测试阶段¶

7.1 E2E¶

7.2 测试质量审查¶

7.3 Word 报告生成¶

7.4 人工走查辅助¶

8. 部署与线上¶

8.1 部署准备（不执行）¶

8.2 部署执行¶

8.3 线上验证¶

8.4 事故复盘¶

9. 上下文与项目管理¶

9.1 会话启动¶

9.2 上下文压缩¶

9.3 任务拆分¶

9.4 变更请求¶

10. 模板索引¶

11. 提示词反模式¶

1.1 生成 `CLAUDE.md`¶