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

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

---

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

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

### 1.1 启动 Scoping (定界)
**适用场景**：新需求启动时。
```text
【模式】规范驱动 + 接口先行。禁止直接写代码。
【必须遵守】agents.md / spec/contracting.md / docs/spec-product-zh.md

【任务背景】
- 模块: <module_name>
- 目标: <一句话描述功能>
- 依赖: <外部系统或模块清单>

【输出要求】
请在 spec/<module_name>/ 下输出 Scoping 结果：
1) 模块边界：明确覆盖与不覆盖的范围。
2) 依赖接口清单 (Consumer-First)：重点列出你需要的外部服务接口草案。
3) 产出物计划：确认将生成的 spec 文件列表 (requirements, openapi.provider/deps, design, tasks)。

输出完成后停止，等待确认。
```

### 1.2 生成 Requirements (需求)
**适用场景**：Scoping 确认后。
```text
请生成 spec/<module_name>/requirements.md。

要求：
1) 包含用户故事 [US-...] 和验收标准 [AC-...] (使用 EARS 语法)。
2) 必须包含 Traceability 表，将 AC 映射到预期的 API Endpoint。
3) 考虑降级、超时、幂等及多租户隔离 (若适用)。

完成后停止，待确认后请执行 spec-only commit。
```

### 1.3 生成 OpenAPI (契约)
**适用场景**：需求确认后。建议分两步：deps (依赖) -> provider (提供)。
```text
请生成 spec/<module_name>/openapi.provider.yaml (或 openapi.deps.yaml)。

要求：
1) 在 info 下标记 x-contract-level: L0。
2) 100% 对齐 requirements.md 中的 AC。
3) 包含 operationId、结构化错误模型及必要的状态码。
4) 若涉及流式，请定义 SSE 事件模型 (message/final/error)。

完成后停止，待确认后请执行 spec-only commit。
```

---

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

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

### 2.1 开启并行窗口 (分工指令)
**适用场景**：将任务分发给不同的 AI 窗口。
```text
【执行任务】Phase <X> (TASK-001 ~ TASK-00N)
【硬规则】
1. 严格按 spec/<module_name>/tasks.md 顺序执行。
2. 禁止修改其它窗口负责的文件或目录。
3. 每完成一个原子任务必须执行：最小自测 (mvn test / pytest) -> git commit -> 更新 progress.md。
4. 代码/注释必须包含关联的 [AC-...] 标注。
5. 严禁执行 git push，所有提交保留在本地 main 分支。

现在开始执行第一个任务：<task_desc>。
```

### 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 是否同步更新。”