nex/docs/prompts/README.md

Prompts

面向 AI 大模型的执行型提示词集合。每份提示词都应能被单独复制使用，并驱动 AI 以一致的方式完成收集、分析、确认、执行和收尾。

提示词

文件	用途
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，作为统一编写规范