Claude-Code-Workflow/docs/zh/features/spec.md

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 文件结构

规范文件模板

---
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 系统

# 在项目根目录初始化规范系统
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

创建规范文件

# 手动创建规范文件
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 模式（查看规范内容）:

# 列出所有规范
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:

{
  "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: 规范内容通过索引缓存加载，修改后需要重建索引：

ccw spec rebuild

Q2: 如何调试规范加载过程？

A: 使用 --debug 参数查看加载详情：

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 记忆系统 — 跨会话知识持久化
• CLI 调用系统 — ccw spec 命令
• 系统设置 — 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