# 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，作为统一编写规范