用 Claude Code 做 Spec Coding：从规范工作流到 AI 编程边界

AI 编程最容易被误解成“把需求丢给模型，让它直接写代码”。这种方式在小改动上很好用，例如改文案、补样式、修一个判断条件；但只要需求变复杂，问题就会出现：AI 可能理解偏了目标，也可能生成符合语法但不符合团队规范的代码，还可能在跨文件重构时改坏原有逻辑。

Spec Coding 要解决的正是这个问题。

它的核心不是让 AI 写得更快，而是把“要做什么、为什么做、怎么验收、按什么顺序做”提前写清楚。AI 在确定的边界里执行，开发者负责定义边界、补齐上下文、检查结果。

一个基于 Claude Code 的企业级中后台项目实践中，10 天完成了从 0 到 1 的前端搭建，累计净增约 25,546 行代码，使用 217 条人工指令驱动 2,754 次工具调用，效率提升约 36%。这些数据更重要的意义不在于“AI 写了多少代码”，而在于展示了一套可以落地的 AI 编程协作方式。

Spec Coding 是什么

Spec Coding，也可以理解为 SDD（Specification-Driven Development，规格驱动开发），强调在编码前先沉淀规格。规格不是普通需求描述，而是一组能直接指导实现和验收的工程文档。

在 OpenSpec 这类工具中，一次功能变更通常会被拆成四类文档：

它的工作流可以抽象成这样：

flowchart LR
    A[提出变更需求] --> B[编写 proposal]
    B --> C[补充 design]
    C --> D[定义 specs]
    D --> E[拆分 tasks]
    E --> F[AI 按任务编码]
    F --> G[类型检查 / 单测 / 冒烟验证]
    G --> H{是否通过}
    H -- 否 --> E
    H -- 是 --> I[归档变更]

这套流程会增加前置成本，但它降低了后置返工。复杂功能里，AI 最怕目标不清和上下文缺失；Spec 的作用就是把“隐含在开发者脑子里的信息”显式写出来。

尤其是跨多个页面、多个服务、多个组件的需求，单纯一句“帮我实现定时任务管理”会让 AI 自行猜测很多细节，而 Spec 会把需求变成可执行清单：

# change: add-scheduled-task-management

## Why

需要在管理后台提供定时任务配置、执行记录查询和检索结果查看能力，方便运营人员管理周期性数据处理任务。

## What

- 新增定时任务管理路由
- 支持任务列表查询、创建、编辑、删除
- 支持查看任务执行记录
- 支持查看单次执行的检索结果
- 对接 6 个后端接口

## Non-goals

- 不实现任务调度引擎
- 不改动后端接口协议
- 不影响已有权限模型

## Acceptance Criteria

- 任务列表支持按名称、状态、创建时间筛选
- 创建和编辑表单字段校验与接口文档一致
- 删除操作需要二次确认
- 所有接口类型定义完整，不使用 any
- pnpm typecheck 通过

当需求变成这种形式后，AI 的执行空间被收窄，错误也更容易被发现。

项目背景与数据概览

实践对象是一个企业级知识问答平台的中后台前端，包含常见管理端能力：

• 表格列表
• 表单创建与编辑
• 卡片列表
• 数据分析看板
• 授权管理
• 文档树结构
• 定时任务管理
• 前后端接口联调
• 生产构建与部署排障

核心数据如下：

2,754 次工具调用的分布也很有参考价值：

这些数字说明，AI 在 Claude Code 里不是只做“补全代码”，而是在模拟一个工程师日常会做的动作：看代码、改代码、跑命令、记录进度、根据结果继续调整。

10 天开发节奏

整个过程可以分为四个阶段。

项目早期采用问答式协作：开发者提出架构问题，AI 给出方案，开发者决策后让 AI 执行。这种方式适合项目初始化，因为那时主要问题是“选什么技术栈、目录怎么组织、怎么跑起来”。

功能复杂度上来后，协作方式切换为 Spec Coding。此时不再直接说“帮我写一个页面”，而是先让 AI 和开发者共同整理规格，再由 AI 按任务清单逐步实现。

到了打磨和部署阶段，AI 的作用又发生变化：它更多承担重构助手和排障助手的角色。开发者需要给它日志、错误信息、环境差异和验证结果，AI 根据这些信息提出假设并修改方案。

案例一：让 AI 参与产品设计

从 0 到 1 做中后台时，代码并不是第一个问题。更早的问题是：这个系统面向谁、核心路径是什么、页面长什么样、研发如何理解需求。

传统流程通常需要产品经理输出 PRD（Product Requirements Document，产品需求文档），UI（User Interface，用户界面）设计师输出设计稿，工程师再编码。使用 AI 时，可以通过不同 Persona 提示词让它在不同阶段承担不同职责。

产品专家 Persona

让 AI 做产品设计时，不能让它保持“工程师模式”。工程师模式容易马上拆接口、建目录、写代码，而产品阶段需要先问目标。

可以在 Rules 中加入类似约束：

# Product Expert Rule

你现在扮演首席产品专家。

在输出页面方案前，必须先完成：

1. 明确目标用户
2. 明确核心业务目标
3. 梳理主要用户路径
4. 列出页面信息架构
5. 标注哪些需求属于当前版本，哪些需求暂不实现

禁止在需求未澄清前直接给出代码实现。

这样做的意义是把 AI 从“急于执行”切换成“先定义问题”。对于没有专职产品角色的小团队，这一步能帮助工程师补齐需求结构。

生成高保真 HTML 设计稿

AI 生成 UI 时，不一定要直接生成业务源码。更稳妥的方式是先生成可预览的 HTML 文件，把视觉、布局、信息层级固定下来。

设计规则可以这样写：

# UI Design Rule

输出目标是高保真 HTML 原型，不是 React 业务代码。

要求：

- 使用 Ant Design 风格的后台系统视觉语言
- 页面宽度、间距、颜色、字体层级保持一致
- 每个页面都要包含真实业务字段，不使用 lorem ipsum
- 表格、表单、筛选区、操作按钮需要体现完整交互状态
- HTML 文件可以直接在浏览器中打开预览

HTML 设计稿有两个好处：

1. 人可以直接看，不需要启动项目。
2. AI 后续编码时可以读取 HTML 结构和样式，减少纯文字描述带来的歧义。

从设计稿反推研发 PRD

有了 HTML 原型后，可以继续让 AI 生成组件行为级 PRD：

# PRD Template

## 页面目标

说明页面解决什么业务问题。

## 页面入口

说明路由、菜单位置、权限要求。

## 页面结构

- 搜索区
- 操作区
- 数据表格
- 弹窗 / 抽屉
- 空状态 / 加载状态 / 错误状态

## 字段说明

| 字段 | 类型 | 是否必填 | 来源 | 校验规则 |
|---|---|---|---|---|

## 交互行为

描述点击、提交、删除、刷新、跳转等行为。

## 接口依赖

列出 API（Application Programming Interface，应用程序接口）地址、入参、出参和错误处理。

这样生成的 PRD 不是泛泛描述，而是能直接进入开发阶段的上下文材料。

案例二：用 SDD 交付前端功能模块

定时任务管理模块是一个典型的中等复杂度需求：它不是单个页面改动，而是一个完整功能模块，需要独立路由、完整 CRUD（Create、Read、Update、Delete，增删改查）、执行记录、检索结果，还要对接 6 个后端接口。

如果用即时问答方式，很可能会出现这些问题：

• 接口字段复制遗漏
• 枚举值理解不一致
• 页面状态处理不完整
• 文件分层随意
• 联调阶段反复修改类型定义

SDD 的做法是把功能先拆成变更，再按任务执行。

sequenceDiagram
    participant Dev as 开发者
    participant AI as Claude Code
    participant Spec as OpenSpec
    participant MCP as MCP 接口文档
    participant Code as 前端代码

    Dev->>AI: 描述定时任务管理需求
    AI->>Spec: 生成 proposal / design / specs / tasks
    Dev->>Spec: 审核并修正规格
    AI->>MCP: 根据接口 URL 拉取文档
    MCP-->>AI: 返回字段、枚举、必填项、响应结构
    AI->>Code: 生成 services / types / hooks / components / page
    AI->>Code: 运行类型检查和构建验证
    Dev->>AI: 根据验收结果补充修正

一次标准的 tasks 可以拆到足够具体：

## Tasks

- [ ] 新增路由和菜单配置
- [ ] 根据接口文档生成 interface.ts
- [ ] 根据接口文档生成 service.ts
- [ ] 创建 useTaskList hook，封装查询、分页、刷新
- [ ] 创建 TaskSearchForm 组件
- [ ] 创建 TaskTable 组件
- [ ] 创建 TaskEditDrawer 组件
- [ ] 创建 ExecutionRecordDrawer 组件
- [ ] 创建 SearchResultDrawer 组件
- [ ] 接入创建、编辑、删除、启停操作
- [ ] 补充 loading、empty、error 状态
- [ ] 执行 pnpm typecheck
- [ ] 执行页面冒烟验证

这个模块的实践结果是：从变更创建到归档，人工指令少于 10 条，AI 完成交付完整任务管理模块。借助 MCP（Model Context Protocol，模型上下文协议）直连接口文档，6 个接口联调基本一次通过，字段类型和注释不需要大量人工校对。

同一天还额外交付了两个完整模块。按纯人工开发估算，当天人效约提升 3 倍。

案例三：用 SDD 做系统重构

新功能开发和重构不是同一种问题。

新功能是“从无到有”，AI 生成错了可以删掉重来。重构是在已有系统里移动结构、拆分职责、保持行为不变，它更像在运行中的系统上做手术。此时 AI 不仅要知道改什么，还要知道不能改什么，以及每一步改完如何确认没有破坏原行为。

知识问答首页存在几个典型架构债务：

重构 Spec 的重点不是描述“优化首页”，而是定义边界：

## Refactor Goals

- 拆分首页业务组件和公共组件
- 将 useChat 拆成多个单职责 hook
- 降低 ChatInterface props 数量
- 保持页面交互行为不变

## Non-goals

- 不修改接口协议
- 不调整视觉样式
- 不改变路由结构
- 不新增业务功能

任务拆分也要强调“先确认，再迁移，再验证”：

## Tasks

- [ ] 使用 grep 确认当前首页组件引用关系
- [ ] 标记业务组件和公共组件归属
- [ ] 创建新的分层目录
- [ ] 迁移业务组件
- [ ] 迁移公共组件
- [ ] 更新所有 import 路径
- [ ] 将 useChat 拆分为消息、会话、上传等单职责 hook
- [ ] 调整 ChatInterface props
- [ ] 执行 tsc 类型检查
- [ ] 执行页面冒烟验证

实际执行中，9 组共 34 个子任务全部完成，包含 4 个验证任务。AI 全程独立执行，人工干预少于 5 条指令。重构后，7 个业务组件与公共组件完成解耦，useChat 拆成 3 个单职责 hook，ChatInterface 的 props 从 17 个缩减到 6 到 8 个。

重构能否交给 AI，不取决于代码量，而取决于规格是否能把风险讲清楚。目标越明确，禁区越明确，验证步骤越明确，AI 越适合执行。

案例四：复杂构建问题排障

并不是所有编程问题都适合让 AI 独立解决。一个测试环境构建失败的问题，累计花了约 4 小时，经历 7 个会话、15 次以上方案尝试、59 条指令，是整个项目中 AI 最受限制的一天。

问题的难点不在于 AI 分析能力弱，而在于信息结构对 AI 不友好：

最终定位到三个根因：

1. .npmrc 里历史遗留的 omit=optional 跳过了可选依赖，导致 @tailwindcss/oxide-linux-x64-gnu 没有正确安装，而它是 Tailwind CSS v4 的 native binding。
2. Prisma v6 的 postinstall 需要下载 engine，在境外下载失败时没有显式报错，也没有及时超时，而是沉默等待。
3. macOS arm64 生成的 pnpm lockfile 与 Linux x64 构建环境存在 native package 差异；切回 npm 后 lockfile 又被忽略，安装结果不稳定。

最终处理方式是锁定关键依赖、统一包管理器、显式配置 Prisma engine 镜像，并删除会影响 optional dependency 的历史配置：

{
  "dependencies": {
    "tailwindcss": "4.1.11"
  }
}

# CI 环境变量
export PRISMA_ENGINES_MIRROR=https://registry.npmmirror.com/-/binary/prisma

# 统一使用 pnpm
pnpm install --frozen-lockfile
pnpm build

# .npmrc 中删除这类历史配置
# omit=optional

这类问题暴露了 AI 的边界：当问题跨越本地、CI、依赖安装脚本、网络环境和历史配置时，AI 可以帮助分析每一个局部，但很难主动看见完整系统状态。开发者需要负责收集事实、缩小变量、设计验证路径。

CLAUDE.md 和 Rules：让 AI 遵守团队规范

AI 生成代码不稳定，很多时候不是模型能力不够，而是团队没有给它清晰规范。规范不能只写“代码要优雅”，而要写成 AI 可以执行的规则、示范和视觉参考。

这个项目采用三层规范体系：

flowchart TB
    A[开发者意图] --> B[约束层 .claude/rules]
    A --> C[示范层 .claude/code-design]
    A --> D[视觉层 .claude/ui-design]

    B --> E[禁止什么 / 必须怎样]
    C --> F[标准代码长什么样]
    D --> G[页面视觉长什么样]

    E --> H[Claude Code 输出]
    F --> H
    G --> H

第一层：约束层

约束层告诉 AI 哪些事情必须遵守，哪些事情禁止做。

.claude/rules/
├── ts.md           # TypeScript 规范：禁止 any、使用可选链等
├── code-names.md   # 命名规范：kebab-case / camelCase / PascalCase
├── comment.md      # 注释规范：JSDoc、文件头上下文
├── lint.md         # 代码风格：单引号、文件末尾换行等
├── style.md        # 样式规范：Tailwind CSS、样式文件组织
├── pages.md        # 页面目录结构：constants / services / hooks / components
└── service.md      # API 生成规范：fetch{Name}Api、UniversalResp 泛型等

约束层适合写硬规则，例如：

# TypeScript Rule

- 禁止使用 any
- 接口响应必须定义 Res 类型
- 接口请求参数必须定义 Req 类型
- 访问可空字段时使用 ?. 和 ??
- 不允许在页面组件中直接写接口请求逻辑

第二层：示范层

只告诉 AI “不能怎样”还不够。它可能生成合法但不符合团队风格的代码。示范层提供标准模板，让 AI 照着团队习惯生成。

.claude/code-design/
├── pro-table/           # 列表页模板：搜索、分页、批量操作、行操作
├── pro-form/            # 表单页模板：创建 / 编辑双模式、字段验证
├── editable-pro-table/  # 可编辑表格模板
├── drawer/              # 抽屉组件模板
├── component/           # 通用组件模板：README、Props、示例
└── utils/               # 工具函数模板

例如让 AI 生成列表页时，指令不应该只是：

生成一个知识空间列表页。

更好的指令是：

参考 .claude/code-design/pro-table 的结构，生成知识空间列表页。

要求：

- 页面目录按 constants / services / hooks / components 分层
- 接口函数命名遵守 fetch{Name}Api
- 搜索、分页、刷新逻辑放在 hook 中
- 表格列定义和操作按钮拆到独立文件

示范层能减少多轮调整。AI 不需要猜“团队喜欢什么结构”，它可以直接读取标准实现。

第三层：视觉层

视觉层存放 HTML 设计稿，让 AI 在实现页面时对齐布局、颜色、间距和组件结构。

.claude/ui-design/
├── knowledge-spaces.html
├── search-strategy.html
├── space-detail.html
└── ...

纯文字描述“做一个好看的后台页面”没有意义。HTML 设计稿能给 AI 明确参照，尤其适合复杂页面布局、卡片信息密度、筛选区和表格操作区组合。

三层规范的效果很明显：

但规范不是万能的。实践中仍然需要人工纠偏：

经验很直接：规范文件是约束，不是能力。只有约束层时，AI 知道不能做什么；加入示范层和视觉层后，AI 才知道标准产出应该长什么样。

MCP：解决 AI 的信息断层

AI 辅助前端开发中有两个高频信息断层。

第一个是接口文档断层。接口文档在 API 平台里，AI 无法直接访问，开发者只能复制字段到对话里，容易漏字段、漏枚举、漏必填项。

第二个是需求文档断层。PRD、设计说明、技术方案存放在云文档里，每次都要打开、复制、粘贴，会打断开发节奏。

MCP 可以把这些外部系统接入 AI 工作流。

接口文档直连

接口文档 MCP 可以让 AI 根据接口 URL 拉取完整文档，包括：

• 入参字段
• 出参结构
• 枚举定义
• 必填项
• 字段注释
• 错误码
• Mock 数据

接口接入流程变成这样：

flowchart LR
    A[开发者提供接口 URL] --> B[AI 调用 MCP]
    B --> C[拉取接口文档]
    C --> D[生成 interface.ts]
    D --> E[生成 service.ts]
    E --> F[生成页面调用逻辑]
    F --> G[联调验证]

在这个项目中，接口文档 MCP 被调用 21 次，完成 39 个接口联调，覆盖了多数接口的初次接入和后续更新场景。后端接口未生效时，还可以同步生成 Mock 数据，降低前端对后端进度的依赖。

云文档直读

飞书等云文档接入 MCP 后，AI 可以直接读取 PRD、设计说明和技术文档，不再依赖人工复制粘贴。

典型用法是：

请读取这个 PRD 文档，并按当前项目规范生成 OpenSpec proposal、design、specs 和 tasks。
文档地址：https://xxx

这种方式不是为了省复制文本的时间，而是为了减少上下文丢失。需求、设计、接口、代码之间一旦能被 AI 串起来，前端开发的联调成本会明显下降。

不同颗粒度需求应该用不同协作模式

并不是所有需求都值得写 Spec。Spec 有成本，选择错误会降低效率。

可以用一个判断流程：

flowchart TD
    A[收到需求] --> B{是否只改局部?}
    B -- 是 --> C[直接对话修改]
    B -- 否 --> D{是否有标准模板?}
    D -- 是 --> E[按 Rules / Skills 生成]
    D -- 否 --> F{是否涉及多文件 / 多模块 / 业务规则?}
    F -- 是 --> G[使用 OpenSpec]
    F -- 否 --> E
    G --> H{是否存在跨环境不确定性?}
    H -- 是 --> I[开发者主导验证路径]
    H -- 否 --> J[AI 按 tasks 执行]

这个流程的关键是：不要把 Spec Coding 神化成唯一方式。小改动直接对话最快，标准页面靠模板最高效，复杂需求才需要完整 Spec。

AI 编程的三种失效模式

AI Coding 的失败通常不是随机发生的，可以归为三类。

这三类问题对应三种治理手段：

flowchart LR
    A[规范真空] --> B[补规则和示范]
    C[信息孤岛] --> D[接 MCP / 补环境文档 / 人控制验证]
    E[目标模糊] --> F[先写 proposal 和验收标准]

AI 不是不可靠，而是在没有边界时会自行补全边界。开发者的任务就是不要让它猜。

开发者角色如何变化

AI Coding 不会让开发者消失，但会改变开发者最有价值的工作。

过去，开发者大量时间花在直接编码、查 API、改重复样板代码上。引入 Claude Code 和 Spec Coding 后，工作重心会向这些方向迁移：

更具体地说，AI 时代的前端工程师需要三种能力。

规范设计能力

能写出让 AI 稳定执行的规范，比只会让 AI “帮我写代码”更重要。规范要具体到命名、目录、类型、异常处理、验收命令，而不是只写抽象原则。

系统性思维

AI 能分析局部日志，但很难主动掌握公司内部部署环境、历史配置、网络限制和跨平台差异。复杂排障仍然需要开发者建立全局视角。

质量前移意识

以前很多问题靠 Code Review 兜底；AI 大量生成代码后，等代码写完再审会变得很累。更有效的方式是在设计阶段、任务拆分阶段、接口接入阶段就把质量要求写进去。

可继续演进的方向

这套实践还有几个方向值得深入。

规范库自动积累

每次踩坑后，都应该沉淀到 rules 或 code-design 中。理想状态是形成闭环：

flowchart LR
    A[发现问题] --> B[定位根因]
    B --> C[提炼规则]
    C --> D[更新 CLAUDE.md / rules / code-design]
    D --> E[后续生成自动规避]

人工维护 7 个规则文件可以起步，但长期更适合做成团队级 AI 执行约束库。

MCP 工具链继续扩展

接口文档和云文档只是开始。设计稿、测试用例、发布平台、日志平台、监控平台都可以接入 MCP，让 AI 不再只看代码仓库，而是能读取完整工程上下文。

多 Agent 并行开发

大型任务执行时，单个 AI 会话存在等待时间。后续可以把模块拆分得更清晰，让多个 Agent 并行实现不同功能，再由开发者负责合并、验收和统一风格。

结论

AI Coding 的关键不是“让 AI 替人写代码”，而是用结构化规范和工作流把不确定性提前消除。AI 负责在确定的空间里高速执行，开发者负责定义、维护和扩展这个确定空间。

10 天、217 条指令、2,754 次工具调用、25,546 行净增代码背后，真正有效的是三件事：

1. 用 Spec Coding 把需求变成可执行、可审计的工程任务。
2. 用 CLAUDE.md、Rules、示范代码和设计稿约束 AI 输出。
3. 用 MCP 补齐接口、需求和文档上下文，减少信息断层。

规范是杠杆，AI 是执行力，Spec 工作流是支点。把三者组合起来，AI 编程才会从“偶尔惊艳”变成“稳定可用”。