293 lines
9.3 KiB
Markdown
293 lines
9.3 KiB
Markdown
# Prompts
|
||
|
||
面向 AI 大模型的执行型提示词集合。每份提示词都应能被单独复制使用，并驱动 AI 以一致的方式完成收集、分析、确认、执行和收尾。
|
||
|
||
## 提示词
|
||
|
||
| 文件 | 用途 |
|
||
| ---- | ---- |
|
||
| [prompt-smart-merge.md](prompt-smart-merge.md) | 批量合并 `dev*` 分支到目标分支，含规则探测、依赖分析、冲突处理、安全回退 |
|
||
| [prompt-spec-review.md](prompt-spec-review.md) | 审查和整理 `openspec/specs/` 下的稳定规范，提升可检索性和一致性 |
|
||
| [prompt-proposal-review.md](prompt-proposal-review.md) | 审查 proposal/design/tasks/specs 与讨论、代码现状、OpenSpec 规范的一致性 |
|
||
| [prompt-apply-review.md](prompt-apply-review.md) | 审查 apply 后代码、测试、变更文档的一致性，并补齐遗漏或回写文档 |
|
||
|
||
## 设计目标
|
||
|
||
从现有提示词提炼出的共同目标：
|
||
|
||
- 面向执行，不面向讲解
|
||
- 先收集证据，再做判断
|
||
- 先计划和确认，再做有副作用的修改
|
||
- 对缺失信息、规则冲突、上下文不足有降级路径
|
||
- 对删除、重写、提交、回退、推送等高风险动作有明确授权边界
|
||
- 执行后必须复核，形成闭环
|
||
|
||
## 命名规则
|
||
|
||
文件名格式：`prompt-{action}.md`
|
||
|
||
- `{action}` 使用明确、可搜索、无歧义的英文短语
|
||
- 用连字符连接，不使用缩写、代号或过泛词
|
||
- 优先体现动作和对象，如 `smart-merge`、`spec-review`、`apply-review`
|
||
|
||
## 通用骨架
|
||
|
||
大多数提示词应遵循以下结构；按任务类型增删章节，但顺序尽量保持一致：
|
||
|
||
```md
|
||
一句话描述任务目标
|
||
|
||
## 约束
|
||
|
||
## 1. 收集 / 准备
|
||
|
||
## 2. 分析
|
||
|
||
## 3. 报告 或 计划（用户确认）
|
||
|
||
## 4. 执行（用户确认）
|
||
|
||
## 5. 清理 / 收尾
|
||
```
|
||
|
||
适用方式：
|
||
|
||
- 审查型：`收集 → 分析 → 报告 → 计划 → 执行 → 收尾`
|
||
- 执行型：`准备 → 分析 → 计划 → 执行 → 清理`
|
||
- 纯报告型：可省略执行，但仍要保留“信息不足时如何降级”和“结果如何输出”
|
||
|
||
## 编写原则
|
||
|
||
### 1. 面向 AI，不写背景说明
|
||
|
||
- 不写业务背景、适用场景、周期性说明、方法论阐释
|
||
- 不写“为什么这么做”的长解释，直接写成规则或步骤
|
||
- 不写示例输出模板，除非输出格式本身就是约束的一部分
|
||
|
||
### 2. 证据先于结论
|
||
|
||
- 明确列出需要读取的文档、代码、测试、配置、命令结果
|
||
- 能并行的步骤明确写“并行”
|
||
- 默认优先使用当前会话信息、现有文档和仓库规则
|
||
- 只有在无法定位对象、范围或规则时，才引导 AI 向用户提问或运行补充命令
|
||
- 不要求 AI 无差别全量扫描整个仓库；先建立索引，再做定向读取
|
||
|
||
### 3. 约束集中声明
|
||
|
||
- 全局不可违反的规则统一放在 `## 约束`
|
||
- 不在后续步骤反复重复同一条规则
|
||
- 约束优先写边界、禁令、授权条件、同步要求、非目标
|
||
|
||
常见约束类型：
|
||
|
||
- 只允许修改哪些对象，不允许修改哪些对象
|
||
- 是否默认按某个 workflow 执行
|
||
- 是否以代码、文档、讨论或用户确认为准
|
||
- 何时必须使用提问工具确认
|
||
- 删除、重写前是否必须备份
|
||
- 改动后是否必须同步 README、测试、变更文档
|
||
|
||
### 4. 计划与执行分离
|
||
|
||
- 分析阶段只产出问题、风险、候选动作，不直接修改
|
||
- 执行前必须先给出计划或批次方案
|
||
- 批次计划必须能让用户看懂“改什么、为什么、影响什么、如何验证”
|
||
- 用户确认执行，不等于授权所有危险动作；额外高风险动作要单独确认
|
||
|
||
### 5. 闭环优先
|
||
|
||
- 执行后必须重新读取受影响对象并复核
|
||
- 对代码修改要说明测试或验证方式
|
||
- 对文档修改要检查相关文档之间是否同步一致
|
||
- 收尾时要列出修改文件、备份文件、验证结果和残留风险
|
||
|
||
## 各章节写法
|
||
|
||
### 目标句
|
||
|
||
第一句只做三件事：
|
||
|
||
- 说明任务对象
|
||
- 说明最终目标
|
||
- 说明执行方式或范围
|
||
|
||
要求：
|
||
|
||
- 一句话写完
|
||
- 不写背景铺垫
|
||
- 尽量包含最终产物，如“生成计划”“回写文档”“整理稳定规范”
|
||
|
||
### 约束
|
||
|
||
推荐写法：
|
||
|
||
- 作用域边界：改什么，不改什么
|
||
- 真相来源优先级：代码 / README / spec / 讨论 / 用户确认
|
||
- 风险动作边界：删除、重写、提交、推送、回退、stash、merge 等
|
||
- 同步要求：测试、README、变更文档、现有 spec 是否要同步
|
||
- 降级规则：信息不足时如何处理
|
||
|
||
避免：
|
||
|
||
- 在约束里塞步骤顺序
|
||
- 同一规则在约束和执行里重复出现多次
|
||
|
||
### 收集 / 准备
|
||
|
||
要明确三类内容：
|
||
|
||
- 读什么
|
||
- 是否并行
|
||
- 无法确定时如何补充定位
|
||
|
||
推荐做法：
|
||
|
||
- 先读仓库规则来源，如 `README.md`、配置、架构文档、近期提交、任务入口
|
||
- 先读直接相关 artifacts，再扩展到相关代码和测试
|
||
- 需要探测时，要求 AI 先探测再决定，不把仓库结构写死在提示词里
|
||
|
||
### 分析
|
||
|
||
分析部分优先使用表格表达维度、优先级和判定规则。
|
||
|
||
推荐包含：
|
||
|
||
- 优先级或维度表
|
||
- 差异分类规则
|
||
- 风险分级规则
|
||
- 是否进入待确认清单的判定条件
|
||
|
||
常见分析模式：
|
||
|
||
- `P0 / P1 / P2 / P3` 优先级
|
||
- “过时 / 重复 / 冲突 / 错位 / 命名 / 格式” 维度
|
||
- “文档要求未实现 / 代码修补未回写 / 双方冲突待确认” 差异分类
|
||
|
||
### 报告 / 计划
|
||
|
||
这是现有提示词最稳定的共性区块，建议固定包含：
|
||
|
||
- 问题总览表
|
||
- 逐项分析
|
||
- 待确认清单
|
||
- 分批执行方案
|
||
- 预期结果或目录结构
|
||
|
||
若进入计划阶段，必须写清：
|
||
|
||
- 改哪些文件或对象
|
||
- 动作类型：删除、重命名、迁移、合并、拆分、补充、回写、修复
|
||
- 修改原因
|
||
- 预期影响
|
||
- 验证方式
|
||
|
||
### 执行
|
||
|
||
执行部分要强调可操作性：
|
||
|
||
- 明确顺序执行还是可并行执行
|
||
- 明确每批执行前是否确认
|
||
- 明确删除、重写、回退前是否要备份或创建锚点
|
||
- 明确执行后最少要复核哪些点
|
||
|
||
推荐写法：
|
||
|
||
- “逐批执行”或“逐项执行”
|
||
- “每批执行后重新读取受影响文件并复核”
|
||
- “若涉及删除或重写，先创建备份文件 `{file}.bak.{timestamp}`”
|
||
|
||
### 清理 / 收尾
|
||
|
||
收尾要输出结果，不只说“完成”。
|
||
|
||
建议包含：
|
||
|
||
- 修改文件清单
|
||
- 备份文件清单
|
||
- 测试 / 构建 / 验证命令与结果
|
||
- 文档同步摘要
|
||
- 残留问题、未验证项、待确认事项
|
||
|
||
## 交互与安全规范
|
||
|
||
### 必须确认的动作
|
||
|
||
以下动作默认都要在提示词中要求 AI 使用提问工具确认：
|
||
|
||
- 删除文件或目录
|
||
- 重写文件
|
||
- 创建或恢复 stash
|
||
- 回退、reset、revert、abort
|
||
- 合并提交、推送、删分支、删远端分支、删 tag
|
||
- 任何会改变工作区现场且用户未明确授权的操作
|
||
|
||
### 授权边界要写清
|
||
|
||
提示词要明确区分：
|
||
|
||
- “确认当前计划”
|
||
- “确认执行当前批次”
|
||
- “确认某个具体危险动作”
|
||
|
||
不要把这些授权混为一谈。
|
||
|
||
### 回退路径要提前写好
|
||
|
||
对高风险流程，提示词应提供至少一种回退机制：
|
||
|
||
- 备份文件
|
||
- 安全锚点 tag
|
||
- `abort` 路径
|
||
- 终止后的现场说明
|
||
|
||
## 表达与格式
|
||
|
||
- 优先使用表格表达规则、维度、状态、输出项
|
||
- 列表优于段落
|
||
- 每句话只写一条指令
|
||
- 用 `{占位符}` 表示需要 AI 或用户填入的参数
|
||
- 步骤编号使用 `## 1.`、`## 2.`，不用“第 X 步”
|
||
- 信息展示遵循“概览 → 详情 → 原始数据”
|
||
|
||
## 仓库适配规则
|
||
|
||
- 若仓库文档已经定义命令、目录、提交格式、包管理器、工作流，提示词必须先遵守仓库文档
|
||
- 若仓库未定义，再允许 AI 根据脚本、清单文件、近期提交历史推断
|
||
- 不把当前仓库的偶然路径结构、命令名、分支名写死到所有提示词中
|
||
- 只有当提示词本身就是为当前仓库的特定流程编写时，才写入仓库专属术语和路径
|
||
|
||
## 反模式
|
||
|
||
以下写法应避免：
|
||
|
||
- 让 AI 一上来就全仓库无差别扫描
|
||
- 在未分析前直接要求修改
|
||
- 把代码现状直接当成唯一真相
|
||
- 把历史变更文档直接当成稳定规范来源
|
||
- 用抽象表述代替可执行动作
|
||
- 把多个危险动作打包成一次默认授权
|
||
- 没有备份、没有锚点、没有终止路径
|
||
- 只要求“完成修改”，不要求复核和收尾
|
||
|
||
## 编写检查清单
|
||
|
||
编写完一份提示词后，至少自检以下问题：
|
||
|
||
| 检查项 | 说明 |
|
||
| ---- | ---- |
|
||
| 目标是否单句明确 | 是否能一眼看出任务对象、目标和范围 |
|
||
| 约束是否集中 | 全局规则是否只在 `## 约束` 中声明 |
|
||
| 数据源是否具体 | 是否明确读哪些文档、代码、测试、命令结果 |
|
||
| 是否先分析再执行 | 是否存在独立的分析和计划阶段 |
|
||
| 是否有确认节点 | 高风险动作前是否要求提问工具确认 |
|
||
| 是否有降级路径 | change 不明、规则不明、上下文不足时是否有处理方式 |
|
||
| 是否可操作 | 是否给出命令、工具、路径或结构化动作 |
|
||
| 是否可验证 | 执行后是否定义复核或测试方式 |
|
||
| 是否能收尾 | 是否要求输出修改清单、备份、验证结果、残留风险 |
|
||
|
||
## 维护原则
|
||
|
||
- 新增提示词前，先判断能否复用现有提示词的结构和术语
|
||
- 修改提示词时，优先提炼共性，不为单次场景堆特例
|
||
- 若某条规则已在多个提示词中稳定出现，应回收进本 README，作为统一编写规范
|