专题 K：Claude Code 工程化工作流

延展阅读 | 从 Vibe Coding 到工程级交付

这个专题讲什么

你用 Claude Code 写代码，Vibe 起来很爽——描述需求，AI 哗哗生成，Demo 跑起来那一刻很有成就感。

但当你从「做一个能跑的原型」进阶到「交付一个能维护的产品」时，问题就来了：AI 写了一堆代码但没有测试、改一处崩三处、需求描述模糊导致结果南辕北辙、对话太长 Claude 开始「忘记」早期决策、复杂任务单次对话根本搞不定。

这个专题要解决的核心问题是：如何把 Claude Code 从一个聪明的实习生，训练成一支有纪律的开发团队。 我们将系统性地构建一套可重复、可验证、可协作的工程化工作流。

一、心智基础：AI 的能力边界与正确协作姿势

AI 擅长什么

把 Claude Code 想象成一个极其聪明但需要明确指令的高级工程师：

几秒钟内读完几千行代码并找到你需要的部分
根据描述快速生成代码框架和样板
发现明显的语法错误、常见安全漏洞、性能反模式
批量执行重复性工作：重命名变量、格式化代码、生成文档注释
按给定规范进行代码审查，比人更耐心和全面

有明确规则、可以自动化的工作，AI 都能做得很好。

AI 不擅长什么

理解业务逻辑：除非你详细告诉它，否则它不知道你们公司的订单流程
技术选型和架构决策：需要权衡利弊的决策，需要你的经验
团队的隐性规范：「所有 API 都要加日志」「错误码必须用枚举」，AI 不会主动知道
判断「真正完成」：AI 可能觉得「看起来差不多了」就停下来

正确协作姿势

你的职责：想清楚做什么 → 做决策 → 把关质量 → 验证结果
AI 的职责：理解上下文 → 执行编码 → 查找信息 → 发现问题

你是指挥官（Commander），AI 是执行者（Executor）。你负责方向和判断，AI 负责速度和广度。

二、项目知识库：让 AI 理解你的项目

CLAUDE.md：项目的「使用说明书」

在项目根目录创建 CLAUDE.md（或 AGENTS.md），这是 Claude Code 启动时首先读取的文件。一个高质量的 CLAUDE.md 包含：

markdown

# 项目概述
在线教育平台，课程管理、用户学习、作业提交。

# 技术栈
- 前端：React 18 + TypeScript + Vite
- 后端：Node.js + Express + PostgreSQL

# 项目结构
src/
├── components/  # PascalCase
├── pages/       # 页面组件
├── api/         # API 调用层
└── utils/       # camelCase

# 代码规范
- 禁止使用 any 类型
- 所有 API 调用必须有错误处理
- 数据库操作使用参数化查询

# 开发流程
1. 从 main 创建功能分支
2. 每完成一个独立功能立即 git commit
3. 提 PR 等待审查

关键原则：如果你发现自己重复两次同样的指令，就把它写进 CLAUDE.md。

分层规范体系

对于更复杂的项目：

.claude/
├── rules/
│   ├── 01-coding-standards.md   # 编码规范
│   ├── 02-api-design.md         # API 设计规范
│   ├── 03-testing.md            # 测试规范
│   ├── 04-git-workflow.md       # Git 工作流
│   └── 05-security.md           # 安全规范

技术决策记录（ADR）

在 docs/decisions/ 目录下维护技术决策记录，让 AI 理解「为什么当初这样设计」：

markdown

# ADR-001: 选择 PostgreSQL 作为数据库
## 状态：已采纳
## 决策：选择 PostgreSQL
## 理由：
1. 更好的 JSON 支持，适合存储课程内容
2. 更强大的全文搜索功能
3. 团队成员更熟悉

让项目知识从人脑转移到文档，AI 才能成为真正的「团队成员」而非「外包」。

三、Spec Coding：用规范驱动开发

从 Vibe 到 Spec 的进化

OpenAI 研究员 Sean Grove 在 2025 年 AI Engineer World's Fair 上提出了一个观点：

「代码是意图的有损投影。规范才是真正的『新代码』。」

在实践中，这意味着两种不同的开发模式：

场景	推荐模式
快速原型验证	Vibe Coding
一次性脚本/工具	Vibe Coding
生产级功能开发	Spec Coding
多人协作项目	Spec Coding
需要长期维护的代码	Spec Coding

Vibe Coding：描述需求 → AI 直接写代码 → 跑起来看看 → 不对再改
Spec Coding：描述需求 → 写规范文档 → AI 读取规范 → 按规范生成代码 → 验证

Spec Coding 不是否定 Vibe Coding，而是在正确的时间选择正确的模式。

Spec Coding 工作流四步法

第一步：产品验证三步法

灵魂三问：用户是谁？痛点在哪？为何用你？
MVP 思维：能验证假设的最简版本是什么？
快速验证：用最小成本验证核心假设

第二步：编写 AI 友好的 PRD

第一部分：文档信息（版本号、阶段、干系人）
第二部分：需求背景与目标（SMART 目标）
第三部分：方案概述（Mermaid 流程图）
第四部分：细节方案（页面原型、交互说明、边缘 Case）
第五部分：上线计划（排期、灰度策略）

第三步：与 AI 确认理解

把 PRD 交给 AI 后，不要让它直接写代码。使用确认模板：

请复述你的理解：
1. 目标用户是谁？
2. 核心功能有哪些？（按优先级排列）
3. 明确不做哪些功能？
4. 你认为有哪些潜在的风险或模糊点？

第四步：AI 生成 Spec → 你审查 → AI 编码

你的 PRD → AI 生成技术 Spec → 你审查确认 → AI 按 Spec 编码 → 测试验证

四、Superpowers：强制工程纪律

为什么需要 Superpowers

Claude Code 本身像一个「聪明的实习生」——能写代码，但不一定会写测试；能做功能，但可能跳过规划。

Superpowers（GitHub 50,000+ Star）是一套开源技能集合，给它强制配备了一位「资深导师」。

安装：

bash

/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

标准工程化流程

1. Brainstorming（头脑风暴）
   ↓ 苏格拉底式提问，编码前澄清需求

2. Design Document（设计文档）
   ↓ 分段展示设计，每段等待确认

3. Writing Plans（编写计划）
   ↓ 将大任务分解为 2-5 分钟的小任务

4. TDD（测试驱动开发）
   ↓ RED → GREEN → REFACTOR

5. Subagent Development（子代理执行）
   ↓ 每个任务独立子代理，两阶段审查

6. Code Review（代码审查）
   ↓ 质量把关

7. Verification（完成前验证）
   ↓ 跑测试、查 lint、确认文档

TDD 实战对比

没有 Superpowers 时：

"实现用户认证模块"
→ Claude 直接开始写代码
→ 可能写测试，也可能不写（看心情）

有 Superpowers 时：

"用 TDD 方式实现用户认证模块"
→ 🔴 RED：先写测试
→ 🟢 GREEN：最少代码使测试通过
→ 🔵 REFACTOR：重构代码，保持测试通过
→ 循环直到所有功能完成

核心技能速查

技能名称	触发方式	作用
`brainstorming`	需求模糊时自动触发	苏格拉底式提问澄清需求
`writing-plans`	提到「制定计划」	大任务分解为小步骤
`executing-plans`	配合 writing-plans	执行计划，检查点暂停
`test-driven-development`	提到「TDD」	强制 RED-GREEN-REFACTOR
`systematic-debugging`	提到「bug」「不工作」	四阶段根因分析
`verification-before-completion`	任务完成时自动触发	跑测试、查 lint

核心认知：Superpowers 不让 AI 更聪明，而是让 AI 更有纪律。

五、Skills 生态：封装可复用能力

Skills 是什么

Skills 是存储在文件系统中的「技能包」——本质上是结构化的 Markdown 指令文件。Claude Code 启动时扫描 Skills 目录，按需加载到上下文。

对比维度	每次都写提示词	使用 Skills
复用性	每次重复描述	写一次，反复用
Token 消耗	每次全量占用	三层加载，节省 80%+
团队共享	无法共享	Git 版本控制
维护性	散落在对话里	集中管理

安装必备 Skills

bash

# 应用商店搜索器（60K+ 订阅）
npx skills add vercel-labs/skills@find-skills -g -y

# 前端设计美化
npx skills add anthropics/skills/frontend-design -g

创建自定义 Skill

如果你发现自己重复两次同样的指令，就创建一个 Skill。

~/.claude/skills/review-pr/
└── SKILL.md

markdown

---
name: review-pr
description: 审查 Pull Request。当用户提到 PR、review、代码审查时触发。
---

## 审查流程
1. **代码风格**：命名是否清晰、是否符合团队规范
2. **安全性**：SQL 注入、XSS、敏感信息泄露
3. **测试**：是否有足够测试、是否覆盖边界
4. **性能**：N+1 查询、不必要的重渲染

每个问题标注严重程度（🔴严重 🟡建议 🟢优化）

Skills vs MCP：一个常被混淆的概念

维度	Skills	MCP
本质	知识和流程（「怎么做」）	工具和接口（「能用什么」）
提供什么	工作流、检查清单、最佳实践	访问 GitHub、数据库、外部 API
存储	Markdown 文件	MCP Server
关系	Skills 定流程，MCP 提供能力	互补，非替代

形象比喻：MCP 是给工作人员配备的工具（扳手、电脑），Skills 是给工作人员的操作手册。

六、Agent Teams：多 AI 并行协作

单 AI 的瓶颈

单个 Claude 实例的局限：

串行瓶颈：一次只能做一件事
上下文拥挤：对话越长，早期信息越容易被淹没
单一视角：没有「同事」可以讨论
效率天花板：无法通过并行加速

Agent Teams 的核心机制

通过多实例并行协作：

真正的并行：前端 UI、后端 API、数据库设计同时进行
独立上下文：每个成员都有 200K token 上下文窗口
团队通信：成员之间可以直接通信，互相验证
效率倍增：Anthropic 内部测试显示大型重构效率提升约 50%

实战场景：大规模项目重构

任务：单体应用拆分为微服务

Agent A（架构师）：整体拆分方案设计
Agent B（后端 A）：用户服务拆分
Agent C（后端 B）：订单服务拆分
Agent D（前端）：适配新 API 网关
Agent E（测试）：端到端测试

流程：
1. A 输出方案 → 所有成员读取
2. B、C 并行拆分各自服务
3. D 等待新 API 后开始适配
4. E 部署后运行集成测试
5. 发现问题 → Agent 间通信协调

七、长时运行：让 AI 持续工作

核心问题：AI 为什么「过早停止」

LLM 有一个根本缺陷——它无法准确判断自己的工作是否真正完成。它可能因为「感觉差不多了」就停下来。

解决方案：让 AI 在一个循环中工作。每次它想退出时，外部系统检查：真的完成了吗？符合客观标准了吗？如果没有，重新注入任务。

Ralph Wiggum：官方长时运行方案

以《辛普森一家》中「永不放弃」的角色命名。

bash

/plugin marketplace add anthropics/claude-code
/plugin install ralph-wiggum@claude-code-plugins

核心机制——Stop Hook：

Claude 想要退出
    ↓
Stop Hook 拦截
    ↓
检查：输出了完成标记吗？
    ├── 是 → 允许退出
    └── 否 → 重新注入任务，继续下一轮

使用范式

bash

/ralph-wiggum:ralph-loop "
构建完整的 todo API，分阶段执行：

阶段 1 - 基础功能：CRUD 端点
阶段 2 - 输入验证：标题不能为空
阶段 3 - 测试：覆盖率 > 80%

验收标准：
- npm test 全部通过
- npm run lint 通过

完成后输出：<promise>TODO_API_COMPLETE</promise>
" --max-iterations 50 --completion-promise "TODO_API_COMPLETE"

Prompt 黄金法则

不好的 Prompt：

写一个 todo API

→ AI 可能写个基础框架就说完成了。

好的 Prompt：分阶段描述任务、列出验收标准、指定唯一完成标记。

适合 vs 不适合

适合（有明确标准）	不适合（需人类判断）
测试框架迁移	架构设计决策
大规模重构	安全相关代码
批量添加类型	需求模糊的任务
文档生成	创意性设计

安全机制

json

{
  "maxIterations": 50,
  "rateLimitPerHour": 100,
  "completionPromise": "TASK_COMPLETE",
  "costAlertThresholds": [10, 50, 100]
}

硬性限制：达到最大迭代次数强制停止
速率限制：防止 API 账单失控
成本预警：花费达阈值时暂停通知

真实案例

YC 黑客松过夜 6 项目：团队设置 Ralph Loop，200 次迭代，第二天 6 个可演示项目，API 成本 $297
Boris Cherny 的 30 天：Claude Code 负责人用 Ralph + Opus，30 天 259 个 PR，497 次提交，100% AI 完成

八、实战工作流模板

场景一：从零开始的新项目

1. 规划项目结构
「功能包括用户注册登录、任务 CRUD、分类标签、提醒。
请推荐技术栈、设计目录结构、规划数据库表结构」

2. 搭建基础框架
「按规划创建项目目录、初始化配置、创建基础代码」

3. TDD 逐个实现功能
「用 TDD 方式实现用户注册：邮箱密码注册、密码加密、JWT」

4. 每完成一个模块立即 commit

关键点：一开始就建立 CLAUDE.md，每完成模块就测试验证。

场景二：成熟项目加新功能

1. 了解项目结构
「需要加优惠券功能。分析项目结构，找到订单代码，
看看满减、折扣怎么实现的」

2. 制定计划
「参考满减实现方式，制定优惠券实现计划」

3. 模仿现有风格实现
「保持相同代码风格和目录结构，逐步实现」

关键点：先理解再动手，保持代码风格一致。

场景三：Bug 修复

1. 收集信息并定位
「点击提交订单后页面卡住。报错：TypeError at checkout.js:45
分析原因、找相关代码、检查数据流」

2. 分析根因
「user 对象从哪来，什么时候会是 undefined」

3. 实施修复
「加防御性代码、user 不存在时跳登录、加错误提示」

4. 预防
「检查项目中还有没有类似问题」

场景四：代码重构

1. 确定目标
「三个函数重复代码多（分页、排序、筛选），提重构方案，评估风险」

2. 准备安全网
「先为这三个函数写测试」

3. 逐步重构
「先提取公共函数，再优化数据结构，最后更新调用处」

4. 验证
「跑全部测试，检查代码质量」

九、成本与安全：工程化的底线

Token 经济学

核心原则：上下文越大，花费越高。

优化策略：
- 指定文件路径比模糊描述更好
- 指明功能范围比笼统说「项目有问题」更聚焦
- 删除客套话，直接说任务
- 使用 CLAUDE.md 减少重复指令的 token 消耗
- Skills 三层加载：启动只加载元数据（30-50 tokens/skill）
  假设 100 个 Skills，启动仅 3,000-5,000 tokens

安全清单

□ 所有用户输入必须验证和转义（防范 XSS、SQL 注入）
□ 数据库操作使用参数化查询
□ 敏感信息（密码、token、API key）不得写入日志
□ 环境变量通过 .env.example 同步，禁止提交真实值
□ .gitignore 包含 node_modules/、dist/、.env
□ AI 生成代码必须人工审查后才能合入主分支
□ 安全相关代码（认证、授权、加密）不适用 Ralph Loop

团队协作规范

1. 共享 CLAUDE.md 和 .claude/rules/，Git 同步
2. 共享 .claude/skills/，统一技能标准
3. 统一 Conventional Commits 提交规范
4. 代码审查重点检查 AI 代码的安全性和边界处理
5. 定期回顾优化 Skills 和 MCP 配置

总结：工程化的七个核心原则

项目知识文档化：CLAUDE.md → .claude/rules/ → ADR。隐性知识显性化。
规范驱动开发：先写 Spec 再写代码。Vibe 做原型，Spec 做产品。
流程纪律工具化：不靠「自觉」，用 Superpowers 强制流程。
可复用能力封装：重复两次写进 CLAUDE.md，重复三次做成 Skill。
能力边界清晰化：Skills 管「怎么做」，MCP 管「能用什么」。
长任务自动化：有明确标准的用 Ralph，需人工判断的保持交互。
成本与安全意识：Token 即成本，上下文即资源，安全不可妥协。

必装工具速查

工具	用途	安装
Superpowers	工程化开发流程	`/plugin install superpowers@superpowers-marketplace`
Ralph Wiggum	长时运行任务	`/plugin install ralph-wiggum@claude-code-plugins`
find-skills	技能搜索器	`npx skills add vercel-labs/skills@find-skills -g -y`
frontend-design	前端设计美化	`npx skills add anthropics/skills/frontend-design -g`

参考资源

最后的话：Claude Code 工程化工作流的本质，不是让 AI 替代你思考，而是把你宝贵的精力从重复性劳动中解放出来，专注于真正需要人类判断力的决策——架构设计、产品方向、质量把关。 工具会变，但「想清楚再动手」的工程思维永远不会过时。

专题 K：Claude Code 工程化工作流 ​

这个专题讲什么 ​

一、心智基础：AI 的能力边界与正确协作姿势 ​

AI 擅长什么 ​

AI 不擅长什么 ​

正确协作姿势 ​

二、项目知识库：让 AI 理解你的项目 ​

CLAUDE.md：项目的「使用说明书」 ​

分层规范体系 ​

技术决策记录（ADR） ​

三、Spec Coding：用规范驱动开发 ​

从 Vibe 到 Spec 的进化 ​

Spec Coding 工作流四步法 ​

四、Superpowers：强制工程纪律 ​

为什么需要 Superpowers ​

标准工程化流程 ​

TDD 实战对比 ​

核心技能速查 ​

五、Skills 生态：封装可复用能力 ​

Skills 是什么 ​

安装必备 Skills ​

创建自定义 Skill ​

Skills vs MCP：一个常被混淆的概念 ​

六、Agent Teams：多 AI 并行协作 ​

单 AI 的瓶颈 ​

Agent Teams 的核心机制 ​

实战场景：大规模项目重构 ​

七、长时运行：让 AI 持续工作 ​

核心问题：AI 为什么「过早停止」 ​

Ralph Wiggum：官方长时运行方案 ​

使用范式 ​

Prompt 黄金法则 ​

适合 vs 不适合 ​

安全机制 ​

真实案例 ​

八、实战工作流模板 ​

场景一：从零开始的新项目 ​

场景二：成熟项目加新功能 ​

场景三：Bug 修复 ​

场景四：代码重构 ​

九、成本与安全：工程化的底线 ​

Token 经济学 ​

安全清单 ​

团队协作规范 ​

总结：工程化的七个核心原则 ​

必装工具速查 ​

参考资源 ​

课程讨论

专题 K：Claude Code 工程化工作流

这个专题讲什么

一、心智基础：AI 的能力边界与正确协作姿势

AI 擅长什么

AI 不擅长什么

正确协作姿势

二、项目知识库：让 AI 理解你的项目

CLAUDE.md：项目的「使用说明书」

分层规范体系

技术决策记录（ADR）

三、Spec Coding：用规范驱动开发

从 Vibe 到 Spec 的进化

Spec Coding 工作流四步法

四、Superpowers：强制工程纪律

为什么需要 Superpowers

标准工程化流程

TDD 实战对比

核心技能速查

五、Skills 生态：封装可复用能力

Skills 是什么

安装必备 Skills

创建自定义 Skill

Skills vs MCP：一个常被混淆的概念

六、Agent Teams：多 AI 并行协作

单 AI 的瓶颈

Agent Teams 的核心机制

实战场景：大规模项目重构

七、长时运行：让 AI 持续工作

核心问题：AI 为什么「过早停止」

Ralph Wiggum：官方长时运行方案

使用范式

Prompt 黄金法则

适合 vs 不适合

安全机制

真实案例

八、实战工作流模板

场景一：从零开始的新项目

场景二：成熟项目加新功能

场景三：Bug 修复

场景四：代码重构

九、成本与安全：工程化的底线

Token 经济学

安全清单

团队协作规范

总结：工程化的七个核心原则

必装工具速查

参考资源