docs: 优化 prompts 提示词，面向 AI 精简 token 并新增书写原则
This commit is contained in:
55
docs/prompts/README.md
Normal file
55
docs/prompts/README.md
Normal file
@@ -0,0 +1,55 @@
|
||||
# Prompts
|
||||
|
||||
面向 AI 大模型的提示词集合，每份提示词独立可用，完整复制给 AI 工具即可启动对应流程。
|
||||
|
||||
## 提示词
|
||||
|
||||
| 文件 | 用途 |
|
||||
| ---- | ---- |
|
||||
| [智能合并.md](智能合并.md) | 批量合并 dev 分支到主干，含依赖分析、冲突处理、安全回退 |
|
||||
| [规范整理.md](规范整理.md) | 审查和重构 openspec/specs/ 下的规范文件 |
|
||||
|
||||
## 书写原则
|
||||
|
||||
### 面向 AI 而非人类
|
||||
|
||||
- 不写背景知识、适用场景、定期审查节奏等"补充说明"，AI 只需要执行指令
|
||||
- 不写解释性注释（为什么用 merge 不用 rebase），直接作为约束声明
|
||||
- 不写示例输出模板，AI 自行推断格式
|
||||
|
||||
### 结构
|
||||
|
||||
```
|
||||
一句话描述任务目标
|
||||
|
||||
## 约束
|
||||
全局不可违反的规则，顶部声明，不在步骤中重复
|
||||
|
||||
## 1. 收集/准备
|
||||
## 2. 分析
|
||||
## 3. 计划（用户确认）
|
||||
## 4. 执行（用户确认）
|
||||
## 5. 清理/收尾
|
||||
```
|
||||
|
||||
编号步骤，不用"第X步"（省 token）。步骤之间有确认节点的明确标注。
|
||||
|
||||
### 精简
|
||||
|
||||
- 每句话只含一条指令，不嵌套子句
|
||||
- 表格优于列表，列表优于段落
|
||||
- 规则只声明一次，不在多处重复
|
||||
- 单文件控制在 150 行以内
|
||||
|
||||
### 安全
|
||||
|
||||
- 破坏性操作（删除、重写、推送、合并提交）执行前必须用提问工具获得用户确认
|
||||
- 提供回退机制（安全锚点、备份标记、abort 路径）
|
||||
- 危险命令的约束直接写在约束块中，不用"严禁""务必"等修饰词，用"禁止"即可
|
||||
- 信息展示分层渐进（概览 → 详情 → 原始数据），避免一次输出过多内容
|
||||
|
||||
### 可操作性
|
||||
|
||||
- 给出具体命令或工具调用方式，不抽象描述（"分析分支"→ "git diff --name-status target...branch"）
|
||||
- 标注并行/串行：可并行的步骤明确写"并行"，有副作用的操作标注"串行"
|
||||
- 用 `{占位符}` 标记需要 AI 替换的参数
|
||||
126
docs/prompts/智能合并.md
Normal file
126
docs/prompts/智能合并.md
Normal file
@@ -0,0 +1,126 @@
|
||||
请对当前项目中所有 `dev*` 分支进行智能合并到目标分支（默认 main），按以下流程执行。
|
||||
|
||||
## 约束（全局，不可违反）
|
||||
|
||||
- 所有操作（合并、推送、删除）执行前必须用提问工具获得用户确认
|
||||
- 冲突文件严禁自主编辑，仅分析方案后交用户选择
|
||||
- 全程仅使用 `git merge`，禁止 rebase（rebase 会重写目标分支历史）
|
||||
- `git add` 仅指定已解决冲突的文件路径，禁止 `git add .`/`git add -A`
|
||||
- `git reset --hard` 仅配合安全锚点 tag 使用，禁止裸用
|
||||
- 禁止自动 `git push`、`git stash`
|
||||
|
||||
## 1. 环境检查
|
||||
|
||||
- `git status` 确认工作区干净，不干净则提示用户处理
|
||||
- 确认目标分支，拉取最新：`git pull`
|
||||
- 列出 dev 分支：`git branch --list 'dev*'`，无则结束
|
||||
- 创建全局安全锚点：`git tag pre-merge-backup-{timestamp}`，报告标签名
|
||||
|
||||
## 2. 分支分析
|
||||
|
||||
对每个 dev 分支并行收集：
|
||||
|
||||
| 维度 | 内容 |
|
||||
| ------ | ---------------------------------------------------------------------------------------- |
|
||||
| 基础 | 分支名、分叉 commit、commit 数/消息、是否推远端、是否已合并（`git branch --merged`） |
|
||||
| 变更 | 文件列表（`git diff --name-status target...branch`）、所属模块、行数统计 |
|
||||
| 依赖 | 是否依赖/被依赖其他 dev 分支、是否修改公共文件（共享类型、工具函数、配置） |
|
||||
| 冲突 | dry-run 预测（逐个串行，不可并行，因需修改工作区）：`git merge --no-commit --no-ff branch` → 收集冲突 → `git merge --abort`；与其他 dev 分支文件重叠 |
|
||||
|
||||
## 3. 合并顺序
|
||||
|
||||
按以下优先级排序：已合并(跳过) → 公共/基础设施变更 → 独立模块 → 有依赖的 → 高冲突/跨模块。
|
||||
|
||||
输出计划表（分支名、模块、文件数、依赖、预估冲突、风险），用提问工具让用户确认，用户可调整顺序或排除。
|
||||
|
||||
## 4. 逐个合并
|
||||
|
||||
对每个分支重复以下流程：
|
||||
|
||||
### 准备
|
||||
|
||||
1. 确认工作区干净、当前在目标分支
|
||||
2. `git tag merge-before-{分支名}` 创建分支级安全锚点
|
||||
3. 向用户确认即将合并的分支及风险
|
||||
|
||||
### 执行
|
||||
|
||||
`git merge {分支} --no-ff`
|
||||
|
||||
- 无冲突 → 进入验证
|
||||
- 有冲突 → 进入冲突处理
|
||||
|
||||
### 冲突处理（三层渐进）
|
||||
|
||||
`git diff --name-only --diff-filter=U` 列出冲突文件，然后按以下三层逐步展开：
|
||||
|
||||
**第一层：冲突概览表**
|
||||
|
||||
向用户展示所有冲突文件的摘要，每文件一行：
|
||||
|
||||
| 文件 | 冲突区域 | 冲突类型 | 目标分支改动 | 合并分支改动 | 推荐方案 |
|
||||
| ---- | -------- | -------- | ------------ | ------------ | -------- |
|
||||
|
||||
- 冲突类型：双方修改同一区域 / 一方删除一方修改 / 文件重命名冲突等
|
||||
- 改动描述：精简到关键差异（如"新增 rateLimit 字段"而非展示原文）
|
||||
- 推荐方案：根据分析给出最合理的选项
|
||||
|
||||
用提问工具让用户选择处理方式：
|
||||
- 批量处理：对推荐方案无异议的文件一键确认
|
||||
- 逐个审查：用户指定要详细审查的文件，进入第二层
|
||||
- 放弃合并：`git merge --abort`，跳过当前分支，继续下一个
|
||||
|
||||
**第二层：单个文件详情（按需）**
|
||||
|
||||
仅展示用户指定审查的文件：
|
||||
- 冲突区域的上下文（前后几行非冲突代码）
|
||||
- HEAD 侧与分支侧的具体差异（精简 diff，非完整文件内容）
|
||||
- 方案选项：双保留 / 保留目标(--ours) / 保留分支(--theirs) / 用户编辑 / 放弃合并
|
||||
|
||||
若用户仍觉信息不足，进入第三层。
|
||||
|
||||
**第三层：原始冲突标记（按需）**
|
||||
|
||||
展示用户指定文件的完整 `<<<<<<<`/`=======`/`>>>>>>>` 原始标记内容。
|
||||
|
||||
**确认与提交**
|
||||
|
||||
1. 方案全部确定后逐个执行：
|
||||
- 双保留：AI 生成合并后的文件内容，展示给用户确认后才写入，严禁未经确认直接写入
|
||||
- 保留目标/分支：`git checkout --ours/--theirs {file}`
|
||||
- 用户编辑：等待用户编辑完成后 `git add {file}`
|
||||
2. 逐个 add 已解决文件：`git add {file}`（禁止 `git add .`）
|
||||
3. 展示 `git diff --cached --stat`，用户确认后完成提交
|
||||
|
||||
### 验证
|
||||
|
||||
- `cd backend && go build ./...`
|
||||
- `cd frontend && bun run build`
|
||||
- 失败则提供回退选项：`git reset --soft HEAD~1` 或 `git reset --hard merge-before-{分支名}`，由用户决定
|
||||
|
||||
### 断点
|
||||
|
||||
每个分支完成后询问是否继续，暂停则记录进度。
|
||||
|
||||
## 5. 推送
|
||||
|
||||
全部合并完成后：
|
||||
- `git log pre-merge-backup-*..HEAD --oneline` 展示新增提交
|
||||
- 确认后 `git push origin {目标分支}`
|
||||
|
||||
## 6. 清理
|
||||
|
||||
### 删除分支
|
||||
|
||||
输出合并结果表，逐个确认删除：
|
||||
|
||||
- 本地：`git branch -d {分支}`
|
||||
- 远端：独立确认后 `git push origin --delete {分支}`
|
||||
|
||||
### 锚点
|
||||
|
||||
询问是否保留安全锚点标签。
|
||||
|
||||
### 总结
|
||||
|
||||
输出：目标分支、安全锚点标签、成功/失败/跳过数量、冲突解决文件数、已删除分支、保留分支及原因。
|
||||
@@ -1,106 +1,58 @@
|
||||
# 规范文件整理流程
|
||||
请对 openspec/specs/ 下所有规范文件进行审查和整理，按以下流程执行。
|
||||
|
||||
## 使用方式
|
||||
## 约束
|
||||
|
||||
将下方提示词完整复制给 AI 工具，即可启动一次规范文件的全面审查和整理。
|
||||
- 规范描述"应该是什么"，不含实现细节（具体文件路径、代码引用）和变更记录（ADDED/MODIFIED、"移除以下列"等措辞）
|
||||
- 每批重构操作执行前用提问工具获得用户确认
|
||||
- 仅删除内容已完全覆盖在其他规范中的冗余规范，非冗余内容仅迁移/合并/重命名
|
||||
|
||||
---
|
||||
## 1. 收集
|
||||
|
||||
## 提示词
|
||||
并行读取以下内容：
|
||||
- `openspec/specs/` 每个子目录的 `spec.md`
|
||||
- 项目源码（backend/、frontend/），理解实际实现
|
||||
- `openspec/config.yaml`，了解项目约束
|
||||
|
||||
```
|
||||
请对 openspec/specs/ 下的所有规范文件进行审查和整理，按以下流程执行：
|
||||
## 2. 审查
|
||||
|
||||
## 第一步：全面阅读
|
||||
将每个规范与代码和命名约定对比，按以下维度逐项检查：
|
||||
|
||||
1. 逐个读取 openspec/specs/ 下每个子目录的 spec.md，理解每个规范的覆盖范围
|
||||
2. 读取项目源码，理解实际代码实现
|
||||
3. 读取 openspec/config.yaml，了解项目约束和规范
|
||||
| 维度 | 检查点 |
|
||||
| ---- | ------ |
|
||||
| 过时 | 描述的功能/组件是否仍存在于代码；引用的路径、类名、API 是否一致；交互流程是否匹配当前实现 |
|
||||
| 重复 | 不同规范是否描述同一组件/功能/场景（场景级或概念级） |
|
||||
| 错位 | 场景是否放错了功能域；Requirement 是否归属错误的规范 |
|
||||
| 合并 | 同一主题是否分散在多个规范；某个规范是否是另一个的子集 |
|
||||
| 命名 | 是否准确反映内容；是否符合命名约定（见下）；是否暴露可搜索的业务关键词 |
|
||||
| 格式 | 是否使用 SHALL/WHEN/THEN；是否混入变更记录或实现细节；是否有空目录 |
|
||||
|
||||
## 第二步：对比分析
|
||||
### 命名约定
|
||||
|
||||
将每个规范与实际代码对比，按以下维度逐项检查：
|
||||
| 类型 | 模式 | 示例 |
|
||||
| ---- | ---- | ---- |
|
||||
| 平台专属 | `{平台}-{功能}` | admin-platform、console-my-skills |
|
||||
| 跨平台组件 | `{类别}` | component-library、layout-system |
|
||||
| 技能领域 | `skill-{方面}` | skill-market、skill-status-rules |
|
||||
| 业务功能 | `{业务名词}` | account-management、chat-scenarios |
|
||||
|
||||
### A. 过时检查
|
||||
- 规范描述的功能/组件/样式是否在当前代码中仍然存在
|
||||
- 规范引用的文件路径、类名、API 接口是否与代码一致
|
||||
- 规范描述的交互流程是否仍是当前的实现方式
|
||||
命名原则：统一平台前缀（admin-/console-/developer-）、统一领域前缀（skill-）、2-3 词、避免泛化词（display/basic/general/info/data）和实现模式词（crud/list/table）。
|
||||
|
||||
### B. 重复检查
|
||||
- 不同规范是否描述了相同的组件/功能/场景
|
||||
- 场景级别的重复（A 规范的 Scenario 与 B 规范的 Scenario 重复）
|
||||
- 概念级别的重复（A 规范整体描述的就是 B 规范已覆盖的内容）
|
||||
## 3. 报告
|
||||
|
||||
### C. 错位检查
|
||||
- A 规范中是否有场景应该属于 B 规范
|
||||
- 某个 Requirement 是否放在了错误的功能域下
|
||||
输出分析结果：
|
||||
|
||||
### D. 合并检查
|
||||
- 描述同一类主题的规范是否分散在多个文件中
|
||||
- 某个规范是否可以作为子集被另一个更大的规范吸收
|
||||
1. **问题总览表**：问题类型 × 涉及规范数
|
||||
2. **逐项分析**：每个有问题的规范，说明具体问题和建议（涉及文件、冲突点、推荐操作）
|
||||
3. **重构方案**：按优先级分批：
|
||||
- P0：删除空目录和完全冗余规范
|
||||
- P1：合并重复/子集规范到主规范
|
||||
- P2：重命名不精准的规范、拆分错位内容
|
||||
- P3：修正与代码不匹配的描述、清理实现细节和变更记录
|
||||
4. **重构后目录结构**：预期的新 specs/ 目录树
|
||||
|
||||
### E. 命名检查
|
||||
- 规范名称是否准确反映其实际内容
|
||||
- 命名是否遵循统一的前缀约定（平台前缀：admin- / developer- / console-）
|
||||
- 名称是否便于 AI 工具搜索匹配（暴露关键业务词和组件名）
|
||||
## 4. 执行
|
||||
|
||||
### F. 格式检查
|
||||
- 是否使用标准的 SHALL/WHEN/THEN 规范格式
|
||||
- 是否混入了变更记录（如"移除以下列"、"ADDED Requirements"）而非功能规范
|
||||
- 是否存在空目录
|
||||
|
||||
## 第三步：输出分析报告
|
||||
|
||||
按以下结构输出：
|
||||
|
||||
1. 问题总览表（问题类型 × 涉及规范数）
|
||||
2. 逐项分析（每个有问题的规范，说明具体问题和建议）
|
||||
3. 重构方案（删除/合并/重命名/内容调整的具体操作）
|
||||
4. 重构后的规范目录结构
|
||||
|
||||
## 第四步：执行重构
|
||||
|
||||
按优先级分批执行：
|
||||
- P0：删除空目录和完全冗余的规范
|
||||
- P1：合并重复/子集规范到主规范中
|
||||
- P2：重命名不精准的规范、拆分错位的内容
|
||||
- P3：修正与代码不匹配的细节描述
|
||||
|
||||
每步执行后确认目录结构完整。
|
||||
|
||||
## 命名约定
|
||||
|
||||
规范目录命名遵循以下规则，确保 AI 工具搜索时能精准匹配：
|
||||
|
||||
| 类型 | 命名模式 | 示例 |
|
||||
|------|---------|------|
|
||||
| 平台专属功能 | `{平台}-{功能}` | `admin-platform`、`console-my-skills`、`developer-platform` |
|
||||
| 跨平台组件/架构 | `{类别}` | `component-library`、`layout-system`、`design-tokens` |
|
||||
| 技能领域 | `skill-{方面}` | `skill-market`、`skill-status-rules`、`skill-version-management` |
|
||||
| 业务功能 | `{业务名词}` | `account-management`、`chat-scenarios` |
|
||||
|
||||
命名原则（提升 AI 检索命中率）：
|
||||
- 名称中暴露可搜索的业务关键词（如 skill、modal、toast、account）
|
||||
- 同一平台的功能使用统一前缀（admin- / console- / developer-）
|
||||
- 同一领域的功能使用统一领域词前缀（skill-）
|
||||
- 避免泛化词（display → rules/behavior，basic → 删掉，general → 删掉）
|
||||
- 避免实现模式词（crud、list、table）而使用业务领域词
|
||||
- 避免同一关键词在不同规范中重复出现导致歧义（如 layout 只出现在一个规范名中）
|
||||
- 长度控制在 2-3 个词，去掉不影响检索的冗余词（info、data 等）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 补充说明
|
||||
|
||||
### 审查时的判断边界
|
||||
|
||||
- **规范 vs 代码**：规范描述"应该是什么"，不描述"代码怎么写"。如果规范中出现了具体文件路径（如 `src/data/adminData.js`），通常是实现细节而非规范，应该清理
|
||||
- **规范 vs 变更记录**：规范用 SHALL/WHEN/THEN 格式描述功能需求。如果出现"移除以下列"、"保持现有样式"、"ADDED/MODIFIED Requirements"等措辞，说明混入了变更指令，需要改写
|
||||
- **规范 vs 文档**：规范不替代 README 或开发文档，不需要描述项目背景、技术选型等宏观信息
|
||||
|
||||
### 建议的定期审查节奏
|
||||
|
||||
- 每完成一批功能变更后，对照新代码检查相关规范是否需要更新
|
||||
- 规范数量超过 30 个时，建议做一次全面审查
|
||||
- 新增规范前，先搜索现有规范名称和内容，确认是否有可复用/扩展的规范
|
||||
逐批执行重构（P0→P3），每批执行前：
|
||||
- 展示该批次的具体操作列表（源路径 → 目标路径、操作类型）
|
||||
- 用提问工具获得用户确认
|
||||
- 执行后确认目录结构完整，规范文件可正常读取
|
||||
|
||||
Reference in New Issue
Block a user