文件	用途
prompt-smart-merge.md	批量合并 `dev*` 分支到目标分支，含规则探测、依赖分析、冲突处理、安全回退
prompt-spec-review.md	审查和整理 `openspec/specs/` 下的稳定规范，提升可检索性和一致性
prompt-proposal-review.md	审查 proposal/design/tasks/specs 与讨论、代码现状、OpenSpec 规范的一致性
prompt-apply-review.md	审查 apply 后代码、测试、变更文档的一致性，并补齐遗漏或回写文档

设计目标

从现有提示词提炼出的共同目标：

面向执行，不面向讲解
先收集证据，再做判断
先计划和确认，再做有副作用的修改
对缺失信息、规则冲突、上下文不足有降级路径
对删除、重写、提交、回退、推送等高风险动作有明确授权边界
执行后必须复核，形成闭环

命名规则

文件名格式：prompt-{action}.md

{action} 使用明确、可搜索、无歧义的英文短语
用连字符连接，不使用缩写、代号或过泛词
优先体现动作和对象，如 smart-merge、spec-review、apply-review

通用骨架

大多数提示词应遵循以下结构；按任务类型增删章节，但顺序尽量保持一致：

一句话描述任务目标

## 约束

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

README.md Unescape Escape

Prompts

提示词