✨ feat(templates): add sync templates scaffolding

2026-01-21 10:18:24 +08:00
parent 5b1ca45fa5
commit 872d8cf98b
16 changed files with 2203 additions and 0 deletions
@@ -0,0 +1,42 @@
+# 提示词库
+
+本目录包含 AI 代理的工作流程模板和参考文档。
+
+## 目录结构
+
+```text
+prompts/
+├── README.md           # 本文件
+├── system/             # 系统级规范
+│   └── agent-behavior.md
+├── coding/             # 编码流程
+│   ├── clarify.md      # 需求澄清模板
+│   └── verify.md       # 验证检查清单
+└── user/               # 用户快捷命令
+    └── quick-test.md   # 快速测试命令
+```
+
+## 使用方式
+
+### AI 代理
+
+- 新会话时读取 `system/agent-behavior.md`
+- 需要澄清需求时参考 `coding/clarify.md`
+- 完成任务前检查 `coding/verify.md`
+
+### 用户
+
+- 使用 `user/quick-test.md` 中的命令快速执行测试
+
+## 文档说明
+
+| 文件                       | 用途                            |
+| -------------------------- | ------------------------------- |
+| `system/agent-behavior.md` | AI 行为规范、工作模式、禁止行为 |
+| `coding/clarify.md`        | 需求澄清步骤和问题模板          |
+| `coding/verify.md`         | 代码、测试、文档验证清单        |
+| `user/quick-test.md`       | 常用测试命令参考                |
+
+---
+
+**最后更新**：{{DATE}}
@@ -0,0 +1,129 @@
+# 需求澄清模板
+
+## 何时使用
+
+- 需求描述不明确
+- 存在多种理解方式
+- 缺少关键信息
+
+---
+
+## 澄清步骤
+
+### 1. 理解当前需求
+
+**复述需求**：
+
+```text
+我理解你的需求是：[用自己的话复述]
+```
+
+**识别歧义点**：
+
+- 歧义 1：[描述不明确的地方]
+- 歧义 2：[可能有多种理解的地方]
+
+---
+
+### 2. 提出澄清问题
+
+**问题模板**：
+
+> 只问阻塞问题，最多 1–2 个；优先给出选项让用户选择。
+
+#### 功能范围
+
+- 这个功能是否包括 [场景 A]？
+- 是否需要支持 [边界情况 B]？
+- 优先级如何？必须有 vs 可选
+
+#### 行为细节
+
+- 当 [条件 X] 时，应该 [行为 Y] 还是 [行为 Z]？
+- 如果 [异常情况]，如何处理？
+- 是否需要与 [现有功能] 保持一致？
+
+#### 技术约束
+
+- 是否有性能要求？
+- 是否有兼容性要求？
+- 是否有安全要求？
+
+---
+
+### 3. 提供选项
+
+**选项格式**：
+
+**选项 A**：[方案描述]
+
+- 优点：[列出优点]
+- 缺点：[列出缺点]
+- 适用场景：[什么情况下选这个]
+
+**选项 B**：[方案描述]
+
+- 优点：[列出优点]
+- 缺点：[列出缺点]
+- 适用场景：[什么情况下选这个]
+
+**推荐**：[推荐哪个选项，为什么]
+
+---
+
+### 4. 确认理解
+
+**确认清单**：
+
+- [ ] 功能范围明确
+- [ ] 行为细节清晰
+- [ ] 技术约束已知
+- [ ] 优先级确定
+- [ ] 验收标准明确
+
+---
+
+## 示例
+
+### 需求
+
+```text
+实现 XXX 功能
+```
+
+### 澄清过程
+
+**复述需求**：
+
+```text
+我理解你的需求是：为 YYY 添加 XXX 功能，
+用于 ZZZ。
+```
+
+**识别歧义点**：
+
+- 歧义 1：XXX 是只读还是可写？
+- 歧义 2：是否需要支持所有场景？
+
+**澄清问题**：
+
+- 是否需要支持 [场景 A]？
+- 当 [条件 X] 时，应该如何处理？
+
+**提供选项**：
+
+**选项 A**：完整实现
+
+- 优点：功能完整
+- 缺点：开发周期长
+
+**选项 B**：核心功能
+
+- 优点：快速交付
+- 缺点：功能有限
+
+**推荐**：选项 A，因为 [原因]。
+
+---
+
+**最后更新**：{{DATE}}
@@ -0,0 +1,94 @@
+# 验证检查清单
+
+## 代码修改验证
+
+### 语法检查
+
+- [ ] 代码可正常运行（无语法错误）
+- [ ] 无未定义的变量或函数
+- [ ] 依赖引用正确
+
+### 风格检查
+
+- [ ] 命名符合规范
+- [ ] 缩进正确
+- [ ] 换行符正确（遵循 .gitattributes）
+- [ ] 无冗余注释
+
+---
+
+## 测试验证
+
+### 单元测试
+
+- [ ] 相关测试脚本存在
+- [ ] 测试可正常运行
+- [ ] 测试通过（无失败）
+
+### 回归测试
+
+- [ ] 现有测试仍然通过
+- [ ] 未破坏其他功能
+
+---
+
+## 文档验证
+
+### 代码文档
+
+- [ ] 复杂逻辑有注释说明
+- [ ] 公开 API 有使用示例（如需）
+
+### 项目文档
+
+- [ ] `memory-bank/progress.md` 已更新
+- [ ] 重要决策记录到 `memory-bank/decisions.md`
+- [ ] `CONFIRM.md` 中需讨论事项已记录
+
+---
+
+## Git 验证
+
+### 提交前检查
+
+- [ ] 只包含相关修改（无无关文件）
+- [ ] 提交信息清晰
+- [ ] 无临时文件或调试代码
+
+### 分支检查
+
+- [ ] 在正确的分支上工作
+
+---
+
+## 性能验证（如果涉及）
+
+### 性能测试
+
+- [ ] 处理时间可接受
+- [ ] 内存使用正常
+- [ ] 无明显性能退化
+
+---
+
+## 安全验证（如果涉及）
+
+### 安全检查
+
+- [ ] 无注入风险
+- [ ] 敏感信息已脱敏
+
+---
+
+## 快速检查清单（最小集）
+
+**每次修改必须检查**：
+
+- [ ] 代码可运行（无语法错误）
+- [ ] 相关测试通过
+- [ ] 换行符正确
+- [ ] `memory-bank/progress.md` 已更新
+
+---
+
+**最后更新**：{{DATE}}
@@ -0,0 +1,196 @@
+# AI 代理行为规范
+
+## 工作模式
+
+### 模式 1: 探索模式（Explore）
+
+**目的**：理解代码库、分析问题、收集信息
+
+**行为规范**：
+
+- 使用搜索工具探索代码
+- 输出分析报告和发现
+- 提出问题和建议
+- 不修改任何代码
+- 不运行测试（除非明确要求）
+
+**适用场景**：
+
+- 理解某个模块的实现
+- 分析 bug 的根本原因
+- 评估功能实现的可行性
+
+---
+
+### 模式 2: 开发模式（Develop）
+
+**目的**：实现功能、修复 bug、重构代码
+
+**行为规范**：
+
+- 先读取相关文件，理解现有逻辑
+- 进行精确修改
+- 修改后运行对应测试验证
+- 更新 `memory-bank/progress.md`
+- 不读文件就提议修改
+- 不跳过测试直接提交
+
+**适用场景**：
+
+- 实现新功能
+- 修复已知 bug
+- 优化性能
+
+---
+
+### 模式 3: 调试模式（Debug）
+
+**目的**：诊断问题、对比差异、验证行为
+
+**行为规范**：
+
+- 收集相关日志和输出
+- 分析差异原因
+- 记录到 `CONFIRM.md` 或直接修复
+- 重新验证
+
+**适用场景**：
+
+- 测试失败
+- 输出不符合预期
+- 性能问题诊断
+
+---
+
+## 代码风格要求
+
+### 通用规范
+
+**命名规范**：
+
+- 遵循项目现有的命名风格
+- 保持一致性
+
+**缩进**：
+
+- 遵循项目现有的缩进风格
+
+**换行**：
+
+- 遵循 `.gitattributes` 规则
+
+**注释**：
+
+- 只在逻辑不自明时添加注释
+- 不添加冗余注释
+
+---
+
+## 禁止行为清单
+
+### 代码修改
+
+- **不读文件就提议修改**
+
+  - 必须先读取文件
+  - 理解现有逻辑后再提出修改建议
+
+- **破坏现有架构**
+
+  - 不随意移动目录结构
+  - 不随意重构核心模块
+
+- **随意改动换行符**
+  - 遵循 `.gitattributes` 规则
+  - 不混用 LF 和 CRLF
+
+### 测试流程
+
+- **跳过测试直接提交**
+  - 修改后必须运行相关测试
+  - 测试失败必须分析原因
+
+### Git 操作
+
+- **使用 `git commit --amend`**
+
+  - 除非用户明确要求
+  - 总是创建新提交
+
+- **使用 `git push --force`**
+
+  - 特别是推送到 main/master 分支
+  - 如果用户要求，必须警告风险
+
+- **跳过 hooks**
+  - 不使用 `--no-verify`
+
+### 过度工程
+
+- **添加未要求的功能**
+
+  - 只做用户要求的修改
+  - 不主动重构周边代码
+
+- **添加不必要的注释**
+
+  - 不给自明的代码添加注释
+
+- **过度抽象**
+  - 不为一次性操作创建工具函数
+  - 不为假设的未来需求设计
+
+---
+
+## 决策原则
+
+### 何时记录到 CONFIRM.md
+
+**必须记录**：
+
+- 需求有歧义，存在多种理解
+- 有多个技术方案，需要权衡
+- 可能破坏兼容性
+- 涉及架构变更
+
+**可以不记录**：
+
+- 明显的 bug 修复
+- 符合现有模式的小改动
+- 测试用例补充
+
+### 何时记录到 decisions.md
+
+**必须记录**（ADR 格式）：
+
+- 影响多个模块的架构决策
+- 技术栈选择
+- 设计模式选择
+- 重要的约束条件
+
+---
+
+## 沟通原则
+
+### 输出风格
+
+- 简洁明确，避免冗长
+- 使用纯文本结构化输出，必要时用 Markdown 代码块
+- 代码块标注语言
+- 不使用 emoji（除非用户明确要求）
+- 不使用过度的赞美或验证
+
+### 技术准确性
+
+- 优先技术准确性，而非迎合用户
+- 发现用户理解有误时，礼貌纠正
+- 不确定时，先调查再回答
+
+### 时间估算
+
+- 不给出时间估算
+- 专注于任务本身，让用户自己判断时间
+
+---
+
+**最后更新**：{{DATE}}