# SDD + API-First 提示词指南 (Prompt Playbook)

本文档提供在“规范驱动 + 接口先行”开发生命周期中，人类与 AI 协作的标准化提示词模板。通过这些模板，可以确保即便使用不同的 AI 窗口或模型，也能产生一致的规范工件。

---

## 1. 文档生成阶段 (强模型/架构 AI)

此阶段目标是确立 SSOT。建议采用“单步确认”模式。

### 1.1 启动功能定界
**适用场景**：开始做新功能时。
**使用方法**：复制提示词，粘贴后直接在末尾输入你的需求。

```text
【工作模式】先写需求文档，再写代码。禁止直接写代码。
【必须遵守】项目根目录的 agents.md 和 docs/ 文件夹下的方法论文档

请分析我的需求，在 spec/<模块名>/ 文件夹下输出功能边界、外部接口清单、文档清单。输出完成后停止，等待我确认。

我的需求：
```

### 1.2 生成需求文档
**适用场景**：功能定界确认后。
**使用方法**：直接复制粘贴即可，无需修改。

```text
【必须遵守】项目根目录的 agents.md 和 docs/ 文件夹下的方法论文档

请生成 spec/<模块名>/requirements.md 需求文档，包含：用户故事、验收标准、接口映射表。

完成后停止，等待我确认。确认后请单独提交这个文档到 git，提交信息使用文档中的第一个 AC 编号，格式：docs: init requirements [AC-XXX-01]
```

### 1.3 生成接口定义
**适用场景**：需求文档确认后。
**使用方法**：直接复制粘贴即可，无需修改。

```text
【必须遵守】项目根目录的 agents.md 和 docs/ 文件夹下的方法论文档

请生成 spec/<模块名>/openapi.provider.yaml 接口定义文件，要求与需求文档中的验收标准完全对齐。

完成后停止，等待我确认。确认后请单独提交这个文档到 git，提交信息使用需求文档中的第一个 AC 编号，格式：docs: init openapi contract [AC-XXX-01]
```

---

## 2. 编码实现阶段 (弱模型/执行 AI)

此阶段目标是按图施工，严格遵守提交节奏。

### 2.0 项目初始化（仅主窗口执行一次）
**适用场景**：开始编码前，准备项目基础设施。
**使用方法**：直接复制粘贴即可，无需修改。
**重要提示**：此步骤仅由主窗口/管理员执行一次，其他窗口跳过此步骤。

```text
【必须读取】spec/<模块名>/ 下的规范文档（requirements.md、openapi.provider.yaml、design.md、tasks.md）

【初始化任务】
请按顺序执行以下初始化操作：
1. 检查并安装项目依赖（如 npm install、pip install 等）
2. 创建必要的目录结构（如 logs/、uploads/、temp/ 等）
3. 初始化数据库（执行迁移脚本，创建表结构）
4. 插入基础数据（如管理员账号、系统配置等）
5. 检查外部服务连接（如 Redis、消息队列、第三方 API）
6. 生成配置文件（如 .env.local，基于 .env.example）

【硬规则】
- 仅执行基础设施初始化，不实现任何业务功能
- 初始化完成后提交一次，提交信息使用需求文档中的第一个 AC 编号，格式：chore: init project infrastructure [AC-XXX-01]
- 完成后输出"初始化完成"，等待其他窗口开始并行开发

执行初始化。
```

### 2.1 生成并行开发提示词
**适用场景**：项目初始化完成后，准备多窗口并行开发。
**使用方法**：直接复制粘贴即可，无需修改。

```text
【必须读取】spec/ 下所有模块的 tasks.md 文件

请分析各模块的任务清单，为每个模块生成一个可直接使用的提示词，格式如下：

---
## 窗口 N：<模块名>

```text
【必须读取】spec/<模块名>/ 下的规范文档（requirements.md、openapi.provider.yaml、design.md、tasks.md）
【可选】如果任务复杂（≥5个子任务），按 docs/session-handoff-protocol.md 创建进度文档

【硬规则】
1. 严格按 tasks.md 顺序执行任务
2. 仅修改自己负责的模块文件，禁止修改其他模块或项目基础设施
3. 禁止初始化项目（如创建数据库、修改全局配置），项目已由管理员初始化完成
4. 每完成一个任务：运行测试 -> 提交代码（格式：feat/fix: <描述> [AC-XXX-NN]）
5. 代码注释必须包含对应的验收标准编号 [AC-XXX-NN]
6. 所有提交保留在本地，禁止 push 到远端

现在开始执行 <模块名> 的 Phase 1 任务。
```
---

生成完成后，用户可以直接复制每个窗口的提示词到对应的 AI 窗口执行。
```

### 2.2 契约与实现对齐 (L2 升级)
**适用场景**：实现接近完成，准备合并前。
```text
【契约对齐】将 openapi.provider.yaml 提升至 L2 并对齐代码。

任务：
1. 修改 info.x-contract-level 为 L2。
2. 检查代码实现，确保 DTO 校验 (Validation)、枚举、错误码与契约 100% 一致。
3. 若契约收紧 (如增加必填项)，必须同步修改代码与测试。
4. 确保 Traceability 校验通过。

完成后执行 spec-only commit 和实现 commit。
```

---

## 3. 接续与收网阶段 (全流程)

### 3.1 启用会话接续协议 (Handoff)
**适用场景**：任务复杂 (子任务 >= 5) 或需要跨窗口接力。
```text
当前任务满足复杂度阈值，必须启用接续协议。
请按 docs/session-handoff-protocol.md，在 docs/progress/ 下创建/更新 <module>-progress.md。
要求：详细记录 Next Action，必须精确到 文件:行号。
```

### 3.2 PR 门禁自检 (收网前)
**适用场景**：推送远端并发起 PR 前。
```text
请进行收网前自检：
1. 确认所有 spec 文件已完成 spec-only commit。
2. 确认所有任务在 tasks.md 中已标为 ✅。
3. 确认 provider 等级为 L2。
4. 运行本地脚本：./scripts/check-traceability.sh 和 ./scripts/check-openapi-level.sh 确保 100% 通过。

自检无误后，创建功能分支推送到远端并发起 PR。
```

---

## 4. 故障排除 (Troubleshooting)
- **Actions 报错**: “检查日志，若是环境变量缺失或离线 checkout 问题，参考 docs/setup-gitea-actions-gate.md 修复。”
- **门禁失败**: “若是 AC ID 找不到，检查 requirements.md 是否同步更新。”