catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-03-01 15:03:57 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: add VitePress documentation site

Browse Source 
- 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
This commit is contained in:
catlog22
2026-02-28 16:14:09 +08:00
parent ab65caec45
commit c3ddf7e322
136 changed files with 34486 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

283
docs/zh/features/spec.md Normal file
View File

@@ -0,0 +1,283 @@
# 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`