lanyuanxiaoyao
56ecc73d1b
将 cli-config、config-priority、env-config 合并入 config-management； 将 tdesign-integration、recharts-integration、frontend-config-ui、 frontend-testing、stats-dashboard 合并入新的 frontend/spec.md； 清理其余 spec 中的冗余标记，补充缺失场景。
107 lines
4.4 KiB
Markdown
107 lines
4.4 KiB
Markdown
# 规范文件整理流程
|
||
|
||
## 使用方式
|
||
|
||
将下方提示词完整复制给 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 个时，建议做一次全面审查
|
||
- 新增规范前，先搜索现有规范名称和内容，确认是否有可复用/扩展的规范
|