mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-01 15:03:57 +08:00
c3ddf7e322
- Add docs directory with VitePress configuration - Add GitHub Actions workflow for docs build and deploy - Support bilingual (English/Chinese) documentation - Include search, custom theme, and responsive design
284 lines
9.2 KiB
Markdown
284 lines
9.2 KiB
Markdown
# Spec 规范系统
|
||
|
||
## 一句话定位
|
||
|
||
**Spec 规范系统是项目约束的自动注入机制** — 通过 YAML 前置元数据定义的规范文档，在 AI 会话开始时自动加载相关约束，让 AI 遵守项目编码规范和架构要求。
|
||
|
||
## 解决的痛点
|
||
|
||
| 痛点 | 现状 | Spec 规范系统方案 |
|
||
| --- | --- | --- |
|
||
| **AI 不遵守规范** | CLAUDE.md 写了规范，AI 经常忽略 | 规范按 `readMode: required` 自动强制加载 |
|
||
| **规范难以维护** | 所有约束堆在一个文件里 | 按维度 (specs/personal) 和类别 (exploration/planning/execution) 分离 |
|
||
| **规范加载不智能** | 每次会话都要手动复制粘贴 | 根据用户 Prompt 关键词自动匹配相关规范 |
|
||
| **规范粒度太粗** | 只能全项目或全无 | 支持分类 (general/exploration/planning/execution) 按需加载 |
|
||
|
||
## 核心概念速览
|
||
|
||
| 概念 | 说明 | 位置/命令 |
|
||
| --- | --- | --- |
|
||
| **Dimension (维度)** | 规范所属的分类空间 | `specs` (项目规范) / `personal` (个人偏好) |
|
||
| **Category (类别)** | 工作流阶段分类 | `general` / `exploration` / `planning` / `execution` |
|
||
| **readMode (读取模式)** | 加载策略 | `required` (强制加载) / `optional` (关键词匹配时加载) |
|
||
| **priority (优先级)** | 规范展示顺序 | `critical` / `high` / `medium` / `low` |
|
||
| **keywords (关键词)** | 用于自动匹配的标签 | YAML 数组，与用户 Prompt 关键词取交集 |
|
||
| **Spec Index** | 规范索引缓存 | `.ccw/.spec-index/{dimension}.index.json` |
|
||
|
||
## Spec 文件结构
|
||
|
||
### 规范文件模板
|
||
|
||
```markdown
|
||
---
|
||
title: "文档标题"
|
||
dimension: "specs" # 规范维度: specs | personal
|
||
category: "general" # 工作流类别: general | exploration | planning | execution
|
||
keywords:
|
||
- keyword1
|
||
- keyword2
|
||
readMode: "required" # 读取模式: required | optional
|
||
priority: "high" # 优先级: critical | high | medium | low
|
||
---
|
||
|
||
# 规范内容（Markdown 正文）
|
||
|
||
这里是规范的具体内容...
|
||
```
|
||
|
||
### 规范目录结构
|
||
|
||
```
|
||
.cw/
|
||
├── specs/ # 项目规范（维度：specs）
|
||
│ ├── coding-conventions.md
|
||
│ ├── architecture-constraints.md
|
||
│ └── api-design-guidelines.md
|
||
├── personal/ # 个人偏好（维度：personal）
|
||
│ ├── coding-style.md
|
||
│ └── review-preferences.md
|
||
└── .spec-index/ # 索引缓存（自动生成）
|
||
├── specs.index.json
|
||
└── personal.index.json
|
||
```
|
||
|
||
## 使用场景
|
||
|
||
| 场景 | 说明 | 配置示例 |
|
||
| --- | --- | --- |
|
||
| **编码规范** | 强制 AI 遵守项目代码风格 | `dimension: specs`, `readMode: required` |
|
||
| **架构约束** | 定义模块边界和依赖规则 | `dimension: specs`, `category: planning` |
|
||
| **API 设计** | 规范 API 设计原则 | `dimension: specs`, `keywords: [api, rest, graphql]` |
|
||
| **个人偏好** | 个人的代码风格偏好 | `dimension: personal`, `readMode: optional` |
|
||
|
||
## 操作步骤
|
||
|
||
### 初始化 Spec 系统
|
||
|
||
```bash
|
||
# 在项目根目录初始化规范系统
|
||
ccw spec init
|
||
```
|
||
|
||
**输出**:
|
||
```
|
||
Initializing spec system...
|
||
|
||
Directories created:
|
||
+ .cw/specs/
|
||
+ .cw/personal/
|
||
+ .cw/.spec-index/
|
||
|
||
Seed files created:
|
||
+ .cw/specs/coding-conventions.md
|
||
+ .cw/specs/architecture-constraints.md
|
||
```
|
||
|
||
### 创建规范文件
|
||
|
||
```bash
|
||
# 手动创建规范文件
|
||
cat > .cw/specs/api-design.md << 'EOF'
|
||
---
|
||
title: "API Design Guidelines"
|
||
dimension: "specs"
|
||
category: "planning"
|
||
keywords:
|
||
- api
|
||
- rest
|
||
- endpoint
|
||
- http
|
||
readMode: "optional"
|
||
priority: "high"
|
||
---
|
||
|
||
# API 设计规范
|
||
|
||
## RESTful 约定
|
||
- 使用名词表示资源
|
||
- 使用 HTTP 方法表示操作
|
||
- 统一错误响应格式
|
||
|
||
## 命名约定
|
||
- 路径使用 kebab-case
|
||
- 查询参数使用 camelCase
|
||
EOF
|
||
```
|
||
|
||
### 加载规范
|
||
|
||
**CLI 模式**（查看规范内容）:
|
||
|
||
```bash
|
||
# 列出所有规范
|
||
ccw spec list
|
||
|
||
# 按维度列出
|
||
ccw spec list --dimension specs
|
||
|
||
# 加载特定类别的规范
|
||
ccw spec load --category planning
|
||
|
||
# 按关键词加载规范
|
||
ccw spec load --keywords "api rest"
|
||
|
||
# 重建索引缓存
|
||
ccw spec rebuild
|
||
```
|
||
|
||
**Hook 模式**（自动注入到 AI 上下文）:
|
||
|
||
在 `settings.json` 中配置 hook:
|
||
|
||
```json
|
||
{
|
||
"hooks": {
|
||
"prePrompt": [
|
||
{
|
||
"type": "command",
|
||
"command": "ccw",
|
||
"args": ["spec", "load", "--stdin"]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
## 配置说明
|
||
|
||
### YAML 前置元数据字段
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `title` | string | 是 | 规范文档标题 |
|
||
| `dimension` | string | 是 | 维度：`specs` 或 `personal` |
|
||
| `category` | string | 否 | 类别：`general` / `exploration` / `planning` / `execution` |
|
||
| `keywords` | string[] | 是 | 关键词列表，用于自动匹配 |
|
||
| `readMode` | string | 是 | `required`（强制）或 `optional`（可选） |
|
||
| `priority` | string | 否 | 优先级：`critical` / `high` / `medium` / `low` |
|
||
|
||
### 类别 (category) 说明
|
||
|
||
| 类别 | 加载时机 | 适用场景 |
|
||
| --- | --- | --- |
|
||
| `general` | 始终加载（当 readMode=required） | 通用规范，如编码风格、命名约定 |
|
||
| `exploration` | 探索阶段 | 架构探索、技术选型指南 |
|
||
| `planning` | 规划阶段 | 设计模式、模块划分原则 |
|
||
| `execution` | 执行阶段 | 具体实现规范、测试要求 |
|
||
|
||
## 规范加载机制
|
||
|
||
### 加载流程
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ Spec 加载流程 │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ 1. 用户输入 Prompt │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ 2. 关键词提取 (extractKeywords) │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ 3. 读取索引缓存 (getDimensionIndex) │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ 4. 过滤规范 (filterSpecs) │
|
||
│ ├─ required: 全部加载 │
|
||
│ └─ optional: 关键词匹配时加载 │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ 5. 加载内容 (loadSpecContent) │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ 6. 按优先级合并 (mergeByPriority) │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ 7. 格式化输出 (CLI markdown / Hook JSON) │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 关键词匹配规则
|
||
|
||
- **英文关键词**: 转小写，移除停用词，取长度 >= 3 的词
|
||
- **中文关键词**: 提取连续 CJK 字符序列
|
||
- **匹配逻辑**: 用户关键词与规范关键词取交集，有交集即匹配
|
||
|
||
### 优先级合并顺序
|
||
|
||
```
|
||
critical > high > medium > low
|
||
```
|
||
|
||
同优先级内按 `dimension` 优先级：`specs` > `personal`
|
||
|
||
## 常见问题
|
||
|
||
### Q1: 规范文件修改后没有生效？
|
||
|
||
A: 规范内容通过索引缓存加载，修改后需要重建索引：
|
||
|
||
```bash
|
||
ccw spec rebuild
|
||
```
|
||
|
||
### Q2: 如何调试规范加载过程？
|
||
|
||
A: 使用 `--debug` 参数查看加载详情：
|
||
|
||
```bash
|
||
ccw spec load --keywords "auth" --debug
|
||
```
|
||
|
||
输出示例：
|
||
```
|
||
[specs] scanned=5 required=2 matched=1
|
||
Loaded: coding-conventions (required)
|
||
Loaded: auth-security (matched: auth)
|
||
Total: scanned=10 loaded=3
|
||
```
|
||
|
||
### Q3: required 和 optional 的区别？
|
||
|
||
A:
|
||
- `required`: 无论用户输入什么，都会加载（适用于通用规范）
|
||
- `optional`: 只有当用户 Prompt 包含匹配关键词时才加载（适用于特定场景规范）
|
||
|
||
### Q4: 个人偏好和项目规范冲突怎么办？
|
||
|
||
A: 优先级顺序为 `specs` > `personal`。项目规范会覆盖个人偏好。
|
||
|
||
## 相关功能
|
||
|
||
- [Memory 记忆系统](./memory.md) — 跨会话知识持久化
|
||
- [CLI 调用系统](./cli.md) — ccw spec 命令
|
||
- [系统设置](./system-settings.md) — Hook 配置
|
||
|
||
## 进阶阅读
|
||
|
||
- 规范索引实现: `ccw/src/tools/spec-index-builder.ts`
|
||
- 规范加载器: `ccw/src/tools/spec-loader.ts`
|
||
- 关键词提取: `ccw/src/tools/spec-keyword-extractor.ts`
|
||
- Dashboard Spec 管理: `ccw/frontend/src/pages/SpecsSettingsPage.tsx`
|