diff --git a/AGENTS.md b/AGENTS.md index 5d73b02..03b045f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -335,34 +335,5 @@ queueClient.EnqueueTask(ctx, constants.TaskTypeXxx, payloadBytes) --- -## Codebase Search Protocol(重要!请严格遵守) -你现在拥有 **cocoindex-code (ccc)** 语义搜索工具,它是本项目最强大的代码检索方式。 - -**搜索优先级规则**: - -1. **大多数情况下优先使用 cocoindex-code semantic search**(推荐默认选择) -2. **仅在以下情况优先使用 grep**: - - 需要查找精确的函数名、变量名、结构体名、SQL 表名、错误码等 - - 需要做精确字符串匹配 - - semantic search 结果不够准确时再补充 grep - -**强烈推荐优先使用 ccc 的场景**: -- 查找业务逻辑、字段使用和修改情况(如店铺名称相关处理) -- 探索不熟悉的模块或跨文件关联逻辑 -- 找语义相似的实现(即使命名不同) -- 需要减少搜索轮次和 token 消耗时 - -**调用要求**: -- 优先调用 `ccc search` 或 `cocoindex_code_search` 工具 -- 查询请使用**自然语言描述业务目的**,例如: - - “店铺名称字段的读写、校验和保存逻辑” - - “所有涉及 shop_name / store_name 的处理流程” - - “权限校验相关的函数和中间件” - -使用 semantic search 后,请引用返回的文件路径和关键代码片段。 - -**默认原则**:如果不确定用哪个工具,**优先使用 cocoindex-code semantic search**。 - - -**详细规范和 OpenSpec 工作流请查看**: `@/openspec/AGENTS.md` \ No newline at end of file +**详细规范和 OpenSpec 工作流请查看**: `@/openspec/AGENTS.md` diff --git a/AI系统级规划提示词规范.md b/AI系统级规划提示词规范.md new file mode 100644 index 0000000..6515fb6 --- /dev/null +++ b/AI系统级规划提示词规范.md @@ -0,0 +1,522 @@ +# AI 系统级规划提示词规范 + +用途:在需要 AI 生成大功能、复杂系统或跨模块改造计划时,先粘贴本文的提示词,再补充业务背景。它的目标是让 AI 先收敛目标、边界、事实源、状态机、失败路径和验收标准,再生成不容易漂移的系统级 plan。 + +建议使用方式: + +1. 先把下面完整提示词复制给 AI。 +2. 再贴业务背景、已有代码约束、用户旅程或参考材料。 +3. 第一轮只让 AI 提澄清问题和共识摘要,不要直接进入最终 plan。 +4. 共识确认后,再要求 AI 生成完整系统级 plan。 +5. 最后要求 AI 进行反向审查,并把缺口合并回最终版。 + +## 完整提示词 + +````text +你现在不是代码执行者,而是“资深系统架构师 + 产品技术负责人 + 交付负责人”。 + +请帮我为一个功能/项目生成系统级实现计划。你的目标不是简单列任务,而是产出一份能约束后续 AI 执行、不容易漂移、能覆盖业务闭环的完整 plan。 + +在我明确说“开始实现”之前,不要写代码,不要改文件,不要进入实现。 + +# 一、工作方式 + +你必须按以下顺序工作: + +1. 先理解我提供的背景。 +2. 如果信息不足,不要直接生成最终 plan,先提出“关键澄清问题”。 +3. 澄清问题必须按优先级排序,最多分三组: + - 必须确认,否则 plan 会错 + - 建议确认,否则执行中可能漂移 + - 可以暂时由 AI 假设 +4. 当信息足够后,先输出“共识摘要”,让我确认。 +5. 共识确认后,再生成完整系统级 plan。 +6. 生成 plan 后,必须进行一次“反向审查”,找缺口、矛盾、漂移风险。 +7. 最后把审查发现合并进最终版 plan。 + +# 二、计划的核心原则 + +生成计划时必须遵守: + +- 不要只按 Model / Store / Service / Handler 拆任务。 +- 必须按“业务闭环”组织阶段。 +- 每个阶段都要回答:这个阶段让哪个用户、哪个业务流程真正可用? +- 所有计划必须明确: + - 做什么 + - 不做什么 + - 为什么现在做 + - 为什么不是以后做 + - 依赖什么 + - 如何验证完成 +- 对不确定的内容必须显式标记为“假设”或“待确认”,不能悄悄编造。 +- 不允许 scope creep。任何超出 MVP 的想法必须放到 V2 / 后置增强。 +- 必须区分: + - 事实源 + - 缓存 + - 派生数据 + - 日志/对象存储/审计材料 +- 涉及资金、权限、状态流转、异步任务、外部接口时,必须单独成节。 + +# 三、计划必须包含的章节 + +最终 plan 必须包含以下章节,不得省略。 + +## 0. 目标与边界 + +说明: + +- 项目/功能目标 +- 当前版本 MVP 范围 +- 明确不做什么 +- V2 / 后置增强 +- 关键原则 +- 核心业务闭环 + +必须写成清晰约束,例如: + +- “A 是事实源,B 只是缓存” +- “系统不保存 XXX 明文” +- “本阶段不做 XXX” +- “失败时必须 XXX” +- “用户可见结果必须 XXX” + +## 1. 角色与用户旅程 + +列出所有角色,例如: + +- 普通用户 +- 运营人员 +- 管理员 +- 第三方系统 +- 异步 worker +- 外部服务 + +每个角色都要有完整旅程: + +```text +角色 + -> 入口 + -> 操作 + -> 系统处理 + -> 状态变化 + -> 用户看到的结果 + -> 异常时如何处理 +``` + +如果某个角色没有闭环,要指出缺口。 + +## 2. 系统边界与模块职责 + +说明每个模块负责什么、不负责什么。 + +必须包含: + +- 前端职责 +- Handler/API 职责 +- Service 职责 +- Store/DB 职责 +- Worker/异步任务职责 +- 外部服务职责 +- Admin/运营后台职责 + +禁止把业务逻辑模糊地写成“后端处理”。 + +## 3. 当前代码与现状依据 + +如果你能访问代码库,必须先阅读相关文件,再写本节。 + +本节要列出: + +- 已有能力 +- 已有表/模型 +- 已有 API +- 已有服务/Store/Worker +- 可以复用的实现 +- 已知坑点 +- 与现有规范冲突的地方 + +每条重要判断都要带文件路径或明确依据。 + +如果不能访问代码库,必须说明“以下为基于用户描述的假设”。 + +## 4. 数据模型与事实源 + +必须写清楚: + +- 新增表 +- 修改表 +- 字段含义 +- 枚举值 +- 唯一约束 +- 索引 +- 软删除策略 +- 迁移策略 +- 回滚策略 +- 历史数据兼容 +- 哪些数据是事实源 +- 哪些数据只是缓存/快照/投影 + +涉及金额时必须写: + +- 金额单位 +- 精度策略 +- 是否允许负数 +- 四舍五入/截断规则 +- 资金流水是否可追溯 +- 是否允许直接改余额缓存 + +## 5. API 契约 + +列出所有接口: + +```text +METHOD /path +权限: +入参: +出参: +错误码: +状态变化: +幂等规则: +审计/日志: +``` + +必须包含: + +- 用户侧 API +- Admin API +- Webhook/API callback +- Worker 触发入口 +- 内部接口或复用点 + +新增 Handler 时必须说明文档生成器/路由注册同步要求。 + +## 6. 状态机 + +凡是有状态字段,必须写状态机。 + +格式: + +```text +状态: +- pending +- processing +- success +- failed +- cancelled + +允许流转: +pending -> processing +processing -> success +processing -> failed + +禁止流转: +success -> pending +failed -> processing + +并发规则: +- 同一资源同时只能有一个 pending +- 状态更新必须使用 WHERE status = expected +``` + +必须覆盖: + +- 正常路径 +- 失败路径 +- 取消路径 +- 重试路径 +- 人工处理路径 +- 状态不可逆规则 + +## 7. 权限与越权防护 + +必须说明: + +- 谁能访问 +- 如何识别身份 +- 如何判断资源归属 +- Handler 层做什么 +- Service 层做什么 +- Store 层是否需要过滤 +- Admin 是否有二次校验 +- 错误信息是否防止泄露资源存在性 + +要求: + +- 不得信任前端传入的用户身份、角色、权限字段。 +- 无权限和资源不存在是否统一返回,需要明确。 +- 所有敏感操作必须有审计。 + +## 8. 幂等、并发与事务 + +必须单独说明: + +- 创建类操作如何防重复 +- 状态流转如何防重复 +- 金额/库存/余额如何防并发错误 +- 异步任务是否可重复消费 +- Webhook 是否幂等 +- 请求重试会发生什么 +- 事务边界在哪里 +- 事务内禁止做什么 +- 事务提交后才做什么 + +必须写出关键策略,例如: + +```text +状态流转使用 WHERE id = ? AND status = ? +余额变更必须在同一事务内完成 +异步任务在事务提交后入队 +Webhook event_id 必须幂等 +``` + +## 9. 异步任务与外部服务 + +如果涉及外部服务或 Worker,必须写: + +- 任务类型 +- payload 结构 +- 入队时机 +- 消费逻辑 +- 重试策略 +- 幂等键 +- 失败后状态 +- 日志关键字 +- 外部服务超时策略 +- 外部服务返回未知状态时如何处理 + +禁止只写“调用第三方接口”。 + +## 10. 失败路径与异常处理矩阵 + +必须提供失败矩阵: + +| 场景 | 系统行为 | 状态变化 | 是否重试 | 用户可见结果 | Admin 如何处理 | +|---|---|---|---|---|---| + +至少覆盖: + +- 参数错误 +- 无权限 +- 资源不存在 +- 并发冲突 +- 重复请求 +- 外部接口失败 +- 外部接口超时 +- 结果未知 +- 事务失败 +- 异步任务失败 +- 数据不一致 +- 人工介入 + +## 11. Admin / 运营闭环 + +必须回答: + +- Admin 在哪里看到这件事? +- Admin 能筛选什么? +- Admin 能处理什么? +- Admin 处理后状态如何变化? +- 是否需要备注、原因、凭证? +- 是否写审计日志? +- 用户能否看到处理结果? + +如果没有 Admin 入口,必须说明为什么不需要。 + +## 12. 日志、审计与可观测性 + +必须列出: + +- 关键日志 +- 审计事件 +- 操作人 +- request_id / trace_id +- 重要状态变化 +- 外部请求/响应是否保存 +- 敏感字段如何脱敏 +- 排查问题时查哪些表、哪些日志 + +## 13. 前端 / 页面 / 交互契约 + +如果涉及前端,必须说明: + +- 页面入口 +- Tab / 弹窗 / 表单 +- 空态 +- 加载态 +- 错误态 +- 提交前确认 +- 成功后刷新哪些数据 +- 权限不足时如何展示 +- 移动端是否需要特殊处理 + +不要只写“新增页面”。 + +## 14. 分阶段实现计划 + +阶段必须按业务闭环拆,不要只按技术层拆。 + +每个 Phase 必须包含: + +```text +Phase N - 名称 + +目标: +本阶段完成后,哪个业务闭环可用: + +包含需求: +不包含: +依赖: +涉及模块: +关键表: +关键接口: +关键状态机: +关键风险: +验证方式: +完成标准: +``` + +阶段顺序必须解释为什么这样排。 + +如果有破坏性变更,必须单独阶段、单独部署、单独回滚。 + +## 15. 任务拆分 + +在系统级 plan 完成后,再拆 tasks。 + +每个 task 必须包含: + +- 任务目标 +- 修改文件范围 +- 输入依赖 +- 输出产物 +- 验证方式 +- 不允许做什么 +- 完成标准 + +不要把多个无关业务目标塞进同一个 task。 + +## 16. 验收标准 + +验收必须是可观察、可执行、可判定的。 + +格式: + +```text +1. 当用户执行 XXX 时,系统应 XXX +2. DB 中应出现 XXX +3. 日志中应出现 XXX +4. Admin 页面应能看到 XXX +5. 重复提交时不会 XXX +6. 外部服务失败时状态为 XXX +``` + +验收必须覆盖: + +- 用户主链路 +- Admin 处理链路 +- 权限拒绝 +- 幂等重复 +- 并发边界 +- 外部失败 +- 数据一致性 +- 文档/路由注册 + +如果项目不写自动化测试,则验收方式使用: + +- `go build` +- `rg` / 静态搜索 +- 数据库查询 +- curl / Postman 手工接口验证 +- Worker/API 日志 +- OpenAPI 文档生成检查 + +不要生成 `*_test.go`,除非我明确要求。 + +## 17. 风险与后置增强 + +必须分成: + +- 当前必须解决的风险 +- 可以接受但要记录的风险 +- V2 后置增强 +- 不再讨论的 rejected 方案 + +每个 rejected 方案都要写拒绝原因,防止后续 AI 反复重新考虑。 + +## 18. 反向审查 + +生成初稿后,必须审查以下问题: + +1. 是否有用户旅程断点? +2. 是否有数据事实源不清? +3. 是否有状态机缺口? +4. 是否有权限/越权风险? +5. 是否有幂等和并发风险? +6. 是否有外部服务失败路径? +7. 是否有 Admin/运营处理缺口? +8. 是否有资金/余额/库存类一致性风险? +9. 是否有接口文档/路由注册遗漏? +10. 是否有验收标准不可执行? +11. 是否有和项目规范冲突? +12. 是否有 scope creep? +13. 是否有“写入完成但读取侧没规划”的问题? +14. 是否有“后端完成但前端/运营入口缺失”的问题? + +审查后输出: + +```text +发现的问题: +影响: +修正方式: +是否已合并进最终 plan: +``` + +# 四、输出要求 + +输出必须使用中文。 + +最终输出结构: + +1. 关键澄清问题(如需要) +2. 共识摘要 +3. 完整系统级 plan +4. 分阶段计划 +5. 任务拆分 +6. MVP 验收清单 +7. 风险与后置增强 +8. 反向审查结果 + +不要空泛,不要只写原则。必须具体到业务状态、接口、数据、失败路径和验收证据。 + +# 五、我的项目特殊规范 + +以下规范必须遵守: + +- 使用中文交互、中文文档、中文注释、中文日志、中文用户错误消息。 +- 代码命名使用英文。 +- 严格遵守项目现有技术栈,不主动引入新框架或新依赖。 +- 遵守 Handler → Service → Store → Model 分层。 +- Handler 不写业务逻辑。 +- Service 承载业务规则。 +- Store 负责数据访问和事务。 +- 所有错误使用项目统一错误码。 +- 新增 Handler 必须同步路由注册和文档生成器。 +- 状态类字段用 int,类型/方式类字段用 string。 +- 所有枚举描述必须与 constants 保持一致。 +- 数据库不使用外键约束,不使用 GORM 关联标签。 +- 默认不写自动化测试,除非我明确要求。 +- 验证默认使用:go build、静态搜索、数据库查询、curl/Postman、日志、OpenAPI 文档生成检查。 + +# 六、现在请先做第一步 + +我接下来会提供功能背景。 + +你收到背景后,先不要生成最终 plan。 +请先输出: + +1. 你理解的目标 +2. 你理解的非目标 +3. 你认为必须确认的问题 +4. 你建议我补充的上下文 +5. 哪些地方可以先用假设推进 +```` diff --git a/CLAUDE.md b/CLAUDE.md index 5d73b02..5812a53 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -335,34 +335,6 @@ queueClient.EnqueueTask(ctx, constants.TaskTypeXxx, payloadBytes) --- -## Codebase Search Protocol(重要!请严格遵守) - -你现在拥有 **cocoindex-code (ccc)** 语义搜索工具,它是本项目最强大的代码检索方式。 - -**搜索优先级规则**: - -1. **大多数情况下优先使用 cocoindex-code semantic search**(推荐默认选择) -2. **仅在以下情况优先使用 grep**: - - 需要查找精确的函数名、变量名、结构体名、SQL 表名、错误码等 - - 需要做精确字符串匹配 - - semantic search 结果不够准确时再补充 grep - -**强烈推荐优先使用 ccc 的场景**: -- 查找业务逻辑、字段使用和修改情况(如店铺名称相关处理) -- 探索不熟悉的模块或跨文件关联逻辑 -- 找语义相似的实现(即使命名不同) -- 需要减少搜索轮次和 token 消耗时 - -**调用要求**: -- 优先调用 `ccc search` 或 `cocoindex_code_search` 工具 -- 查询请使用**自然语言描述业务目的**,例如: - - “店铺名称字段的读写、校验和保存逻辑” - - “所有涉及 shop_name / store_name 的处理流程” - - “权限校验相关的函数和中间件” - -使用 semantic search 后,请引用返回的文件路径和关键代码片段。 - -**默认原则**:如果不确定用哪个工具,**优先使用 cocoindex-code semantic search**。 -**详细规范和 OpenSpec 工作流请查看**: `@/openspec/AGENTS.md` \ No newline at end of file +**详细规范和 OpenSpec 工作流请查看**: `@/openspec/AGENTS.md`