# 规范文件整理流程

## 使用方式

将下方提示词完整复制给 AI 工具，即可启动一次规范文件的全面审查和整理。

---

## 提示词

```
请对 openspec/specs/ 下的所有规范文件进行审查和整理，按以下流程执行：

## 第一步：全面阅读

1. 逐个读取 openspec/specs/ 下每个子目录的 spec.md，理解每个规范的覆盖范围
2. 读取项目源码，理解实际代码实现
3. 读取 openspec/config.yaml，了解项目约束和规范

## 第二步：对比分析

将每个规范与实际代码对比，按以下维度逐项检查：

### A. 过时检查
- 规范描述的功能/组件/样式是否在当前代码中仍然存在
- 规范引用的文件路径、类名、API 接口是否与代码一致
- 规范描述的交互流程是否仍是当前的实现方式

### B. 重复检查
- 不同规范是否描述了相同的组件/功能/场景
- 场景级别的重复（A 规范的 Scenario 与 B 规范的 Scenario 重复）
- 概念级别的重复（A 规范整体描述的就是 B 规范已覆盖的内容）

### C. 错位检查
- A 规范中是否有场景应该属于 B 规范
- 某个 Requirement 是否放在了错误的功能域下

### D. 合并检查
- 描述同一类主题的规范是否分散在多个文件中
- 某个规范是否可以作为子集被另一个更大的规范吸收

### E. 命名检查
- 规范名称是否准确反映其实际内容
- 命名是否遵循统一的前缀约定（平台前缀：admin- / developer- / console-）
- 名称是否便于 AI 工具搜索匹配（暴露关键业务词和组件名）

### 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 个时，建议做一次全面审查
- 新增规范前，先搜索现有规范名称和内容，确认是否有可复用/扩展的规范