docs: 优化 prompts 提示词，面向 AI 精简 token 并新增书写原则
This commit is contained in:
@@ -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