规范驱动开发

在让 Claude 动手之前，先在 CLAUDE.md 中定义你想要什么。一次结构化良好的迭代顶得上 8 次随意的尝试。CLAUDE.md 就是你的规范文件，将它视为与 Claude 的契约。

---

核心模式

传统方式:              规范驱动:
─────────             ──────────
提示 → 代码            规范 → 提示 → 代码 → 验证
  │                     │               │       │
  └─ 只能希望            └── 契约        └── 遵循规范
     符合预期                 已定义            └── 对照规范检查

提示

规范成为唯一的事实来源：约束 Claude 构建的内容、为团队记录决策、并使验证完整性成为可能。

---

工作流程

1. 在 CLAUDE.md 中编写规范
2. Claude 在会话开始时自动读取规范
3. 引用规范让 Claude 实现
4. 对照规范中的验收标准进行验证

第一步：编写规范

在开始任何实现请求之前，在 CLAUDE.md 中添加规范：

## 功能：用户认证

### 能力
- 必须：邮箱/密码登录
- 必须：JWT 令牌生成
- 必须：使用 bcrypt 哈希密码
- 应该：记住我功能
- 禁止：存储明文密码

### 技术栈
- 必需：bcrypt, jsonwebtoken
- 禁用：passport.js（对此场景过于重量级）

### 验收标准
- [ ] 用户可以用有效凭据登录
- [ ] 无效凭据返回 401
- [ ] 令牌在 24 小时后过期（记住我则 7 天）
- [ ] 密码使用 cost factor 12 进行哈希

第二步：引用规范

按照 CLAUDE.md 中的规范实现用户认证功能。
严格遵循验收标准。

Claude 会自动读取 CLAUDE.md 并遵循规范。

第三步：验证

实现完成后，对照验证：

对照用户认证规范审查实现。
逐一勾选已满足的验收标准。
列出任何差距。

第四步：按需更新规范

如果在实现过程中需求变更：

更新用户认证规范，增加：
- 必须：速率限制（每分钟最多 5 次尝试）
然后实现速率限制。

---

任务粒度：为 Agent 确定合适的工作量

警告

Agent 在垂直切片上表现最好 — 薄而完整的端到端单元，穿越所有层级但只实现一个完整的用户行为。例如 “通过邮件重置密码”，而不是 “认证系统”。

经验法则：一个 Agent 会话 = 一个垂直切片。如果任务描述需要在两个用户行为之间用 “和” 连接，就应该拆分。

规范质量检查清单

在将任何任务交给 Agent 之前运行此检查：

维度	要问的问题	危险信号
问题清晰度	问题描述是否无歧义？	“改善性能”
可测试标准	完成与否能否自动验证？	“运行良好”
范围边界	明确排除了什么？	没有列出任何排除项
可观察的完成	对用户来说 “完成” 是什么样？	仅有内部描述
需求清晰度	规范中是否没有实现细节？	“用 Redis 做缓存”
术语一致	全文用语是否统一？	“用户” 和 “账号” 混用

如果有 2 个以上维度不合格，需要修改规范后再让 Agent 处理。

# 太大、太模糊：
"给应用添加用户认证"

# 一个垂直切片：
"用户可以用邮箱+密码登录。
- POST /auth/login 成功返回 JWT，失败返回 401
- 无效凭据显示 '邮箱或密码不正确'（不指明哪个错了）
- 会话在 24 小时后过期
- 不在范围内：OAuth、密码重置、记住我"

---

规范模板

功能规范（最常用）

## 功能：[名称]

### 描述
[2-3 句说明功能目的]

### 能力
- 必须：[必需功能]
- 必须：[另一个需求]
- 应该：[最好有]
- 禁止：[明确排除]

### 技术栈
- 必需：[lib1, lib2, lib3]
- 禁用：[lib4, lib5]

### 验收标准
- [ ] 标准 1：[具体、可测试的条件]
- [ ] 标准 2：[另一个条件]
- [ ] 标准 3：[边缘情况处理]

### API 契约（如适用）
- 端点：POST /api/[resource]
- 请求：{ field1: string, field2: number }
- 响应：{ id: string, created: timestamp }
- 错误：400（验证）、404（未找到）、500（服务器）

架构规范

## 架构：[组件名]

### 目的
[此组件存在的原因]

### 边界
- 负责：[该组件的职责]
- 委托给：[其他组件处理的事务]
- 不做：[明确的非职责]

### 依赖
- 上游：[调用此组件的组件]
- 下游：[此组件调用的组件]

### 约束
- 性能：[响应时间、吞吐量]
- 安全：[认证要求、数据处理]
- 可扩展性：[预期负载、限制]

API 规范

## API：[端点名称]

### 端点
`POST /api/v1/[resource]`

### 认证
需要 Bearer 令牌。权限范围：`read:resource`, `write:resource`

### 请求体
{
  "field1": "string (必需, 最大 255 字符)",
  "field2": "number (可选, 默认: 0)",
  "nested": {
    "subfield": "boolean"
  }
}

### 错误码
| 状态码 | 含义 | 响应体 |
|-------|------|--------|
| 400 | 验证失败 | `{ "errors": [...] }` |
| 401 | 未认证 | `{ "message": "..." }` |
| 403 | 未授权 | `{ "message": "..." }` |
| 404 | 资源未找到 | `{ "message": "..." }` |

---

与工具集成

配合计划模式

[按 Shift+Tab 进入计划模式]

我需要实现支付处理功能。
查看 CLAUDE.md 中的规范，创建实现计划。

配合 Spec Kit（全新项目）

# 安装 Spec Kit
npx @anthropic/spec-kit init

# 使用斜杠命令
/speckit.constitution  # 定义项目护栏
/speckit.specify       # 编写功能规范
/speckit.plan          # 创建实现计划
/speckit.implement     # 按规范构建

配合 OpenSpec（既有项目）

# 安装 OpenSpec
npm install -g @fission-ai/openspec@latest
openspec init

# 使用斜杠命令
/openspec:proposal "添加暗色模式"  # 创建变更提案
/openspec:apply add-dark-mode     # 实现变更
/openspec:archive add-dark-mode   # 归档到规范

---

何时使用规范驱动

适合使用

• 新功能开发（先定义再构建）
• API 设计（契约必须明确）
• 架构决策（记录约束）
• 团队协作（共享理解）
• 复杂需求（减少歧义）

可以跳过

• 快速修复（开销不值得）
• 探索阶段（还不知道要什么）
• 原型开发（需求会变）
• 单行变更（意图明显）

---

模块化规范设计

当规范超过约 200 行时，应该拆分成多个聚焦的文件。

何时拆分

规模阈值	建议
< 100 行	单个 CLAUDE.md 即可
100-200 行	如果有明确的领域划分，考虑拆分
> 200 行	立即拆分 — 已超过认知负荷阈值
多团队项目	无论大小都按领域/负责人拆分

拆分策略

按功能拆分

CLAUDE.md              # 核心项目上下文
CLAUDE-auth.md         # 认证规范
CLAUDE-api.md          # API 端点规范
CLAUDE-billing.md      # 支付处理规范

按角色拆分

CLAUDE.md              # 共享约定
CLAUDE-frontend.md     # UI/UX 规范
CLAUDE-backend.md      # API/数据库规范
CLAUDE-infra.md        # DevOps/部署规范

按工作流拆分

CLAUDE.md              # 日常开发规则
CLAUDE-testing.md      # 测试规范
CLAUDE-release.md      # 发布流程规范
CLAUDE-security.md     # 安全要求

主 CLAUDE.md（保持精简）

# 项目：[名称]

## 技术栈
[核心技术]

## 命令
[日常命令]

## 规则
[通用规则]

## 详细规范
- 认证：参见 @CLAUDE-auth.md
- API 设计：参见 @CLAUDE-api.md
- 测试：参见 @CLAUDE-testing.md

注意

好处：Claude 可以使用 @CLAUDE-auth.md 引用特定文件，仅加载相关规范；更易维护，编辑一个领域不影响其他；更好的团队协作，每个规范文件有明确负责人。

---

操作边界

定义 AI Agent 应该自动做什么、应该先问再做什么、以及绝不能做什么。

三级体系

级别	含义	Claude Code 映射
始终	自动执行，无需询问	自动接受模式
先问	执行前获得确认	默认模式
禁止	阻止或要求计划模式	计划模式 / Hook 阻止

操作边界模板

## 边界

### 始终（自动接受）
- 代码变更后运行测试
- 用 Prettier 格式化代码
- 移动文件时更新导入
- 修复 lint 错误

### 先问（确认）
- 修改数据库 schema
- 添加新依赖
- 更改 API 契约
- 重构超过 50 行代码

### 禁止（阻止）
- 推送到生产分支
- 提交密钥或 API 密钥
- 不备份就删除数据
- 未经审查修改 CI/CD 工作流

映射到 Claude Code 权限

始终 -> 权限白名单：

{
  "permissions": {
    "allow": [
      "Bash(npm test*)",
      "Bash(npx prettier*)",
      "Bash(npx tsc*)"
    ]
  }
}

禁止 -> 计划模式 + Hooks：

#!/bin/bash
# 通过 settings.json 的 PreToolUse 事件配置
if [[ "$TOOL_NAME" == "Bash" ]] && [[ "$INPUT" =~ "git push origin main" ]]; then
  echo "已阻止：禁止直接推送到 main 分支。请使用功能分支。"
  exit 2
fi

---

反模式

模糊的规范

错误

## 功能：用户管理
- 处理用户

正确

## 功能：用户管理
### 能力
- 必须：用邮箱、密码、姓名创建用户
- 必须：更新用户资料（姓名、头像）
- 必须：软删除（标记为不活跃，不删除数据）
- 禁止：允许重复邮箱

先写代码后写规范

# 错误的工作流
1. 让 Claude 实现功能
2. 写规范记录已构建的内容

# 正确的工作流
1. 写规范定义应该构建什么
2. 让 Claude 按规范实现

忽略禁用项

# 不要忘记排除项
### 技术栈
- 必需：React, TypeScript
- 禁用：jQuery, vanilla JS, class components
         ↑ 这些约束防止技术漂移

巨型 CLAUDE.md

警告

当 CLAUDE.md 超过 300 行，混合了功能规范、API 契约、测试要求、部署流程和团队约定时，会导致：上下文效率低下（每次请求加载全部内容）、响应变慢、准确度下降（重要细节淹没在噪声中）。

解决方案：保持 CLAUDE.md 在 100 行以内（仅核心上下文），领域文件各自不超过 150 行。