AI 编程能力边界探索：基于 Claude Code 的 Spec Coding 项目实战

来源：SegmentFault - AI编程能力边界探索：基于 Claude Code 的 Spec Coding 项目实战｜得物技术 替代来源：CSDN - AI编程能力边界探索

一、前言

10 天，2.5 万行代码，提效 36%

基于 Claude Code 的 Spec Coding（规格驱动编码）深度实战。通过 2,754 次工具调用，完成了从 0 到 1 的前端项目搭建，并在"约束+示范+视觉"的三层规范体系下，摸清了 AI 编程的真实能力边界。

二、Spec Coding 工作流

什么是 Spec Coding

Spec Coding 的核心思想是：在写代码之前，先写规格文档。通过 OpenSpec 工具，每个功能变更都经历以下阶段：

Proposal → Design → Specs → Tasks

Spec 工作流的实际价值

• 减少返工：在 proposal 阶段明确为什么以及怎么做，避免实现完才发现方向不对
• 适合复杂功能：对于需要跨多个文件多个层次的功能，tasks 分组让 AI 聚焦在当前步骤
• 可审计：每个 Change 的完整决策链都留有记录，方便回溯

三、项目概览

一个标准企业级中后台搭建，包括：

• 表格、表单、卡片列表、数据看板等中后台核心功能
• 全程使用 Claude Code 辅助开发

四、数据概览

所有数字来自 Claude Code 对 109 个 .jsonl 会话文件的整体数据统计：

指标	数值
开发周期	10 天
净增代码	25,546 行
人工指令	217 条
工具调用	2,754 次
整体提效	36%

工具调用分布

• 738 次文件读取
• 550 次代码编辑
• 662 次终端命令执行
• 208 次任务进度标记

五、开发时间线

阶段一：设计阶段

使用 Cursor + 设计规范 Rules，从概念沟通到生成高保真 UI 稿（HTML 文件），再生成标准 PRD 需求描述。

阶段二：项目搭建（2 个工作日，20 条指令）

以问答式交互为主，聚焦于项目基础设施搭建和简单需求的尝试。AI 帮助熟悉技术栈、搭建项目结构、配置开发环境。

阶段三：功能开发（4 个工作日，89 条指令）

引入 Spec Coding 工作流，约 80% 的功能代码在此阶段完成。先与 AI 共同定义清晰的功能规格，然后 AI 基于"蓝图"自主编码。

阶段四：细节打磨与生产部署（4 个工作日，108 条指令）

功能迭代、系统重构和生产环境部署排障。对已有功能进行多轮优化，最终成功将应用部署上线。

六、典型案例

案例一：AI 驱动产品设计

没有产品经理、没有 UI 设计师，一个工程师如何用 AI 独立完成从产品定义到高保真原型、再到研发文档的全流程。

让 AI 扮演产品经理：在 Rules 中植入「首席产品专家」Persona 提示词，将 AI 切换为"先想清楚"模式。

让 AI 扮演 UI 设计师：通过对话式生成逐页产出高保真 HTML 文件。

让 AI 生成研发可读的 PRD：基于产品经理角色，将 HTML 设计稿作为上下文，生成精确到组件行为级别的 PRD。

案例二：SDD 驱动前端功能研发

SDD（Spec-Driven Development）+ MCP 前后端联调提效关键场景。

• 页面功能开发：人工指令 < 10 条，AI 代码占比 100%
• 前后端联调：SDD + MCP 联调路径，6 个接口零联调返工
• 研发效率：同日额外交付两个完整模块，单日人效提升 3 倍

案例三：SDD 驱动系统重构

重构与新功能的根本差异：新功能开发是"从无到有"，AI 可以大胆生成；重构是"在活体系统上动手术"，风险截然不同。

知识问答首页重构：

• 34 个子任务全部完成（含 4 个验证任务）
• AI 全程独立执行，人工干预 < 5 条指令
• 7 个业务组件与公共组件完成解耦
• useChat 从 20+ 方法拆为 3 个单职责 hook
• ChatInterface 从 17 个 props 缩减至 6-8 个

案例四：复杂问题排障

问题：测试环境构建失败，过程约 4 小时，7 个会话、15+ 次方案尝试、59 条指令。

根因分析（这类问题超出 AI 能力边界）：

• .npmrc 历史副作用导致 native binding 被跳过
• Prisma v6 境外下载沉默卡死（无错误、无超时）
• pnpm 跨平台 lockfile 不一致

最终解法：锁定 tailwindcss 版本、配置 PRISMA_ENGINES_MIRROR、统一使用 pnpm。

七、规范体系：三层结构

每层解决不同问题：

层次	位置	作用
第一层：约束层	.claude/rules/	告诉 AI「禁止什么、必须怎样」
第二层：示范层	.claude/code-design/	告诉 AI「标准产出长什么样」
第三层：视觉层	.claude/ui-design/	告诉 AI「页面应该长什么样」

第一层：约束层（.claude/rules/）

7 个规范文件约束不同维度：

• ts.md — TypeScript 规范
• code-names.md — 命名规范
• comment.md — 注释规范
• lint.md — 代码风格
• style.md — 样式规范
• pages.md — 页面目录结构
• service.md — API 接口规范

第二层：示范层（.claude/code-design/）

预置"标准模板代码"，AI 生成新页面时可直接参照：

• pro-table/ — 通用列表页模板
• pro-form/ — 通用表单页模板
• editable-pro-table/ — 可编辑表格模板
• drawer/ — 抽屉组件模板

第三层：视觉层（.claude/ui-design/）

存放 HTML 设计稿，AI 可读取其中的结构和样式信息。

规范约束的实际效果

正面效果：

• 所有接口函数均以 fetch{Name}Api 命名，205 个文件保持高度一致
• constants/、services/、hooks/、components/ 分层在每个新页面中被正确创建
• CRUD 页面均参照 pro-table 模板，代码结构高度一致

需要人工干预的案例：

• 2/24 — AI 将所有代码写在单文件中，未按规范分层
• 2/27 — AI 错误使用 .less 后缀，项目实际使用 SCSS

八、MCP 工具

MCP 一：接口文档直连

AI 可以根据接口 URL 自动拉取完整接口文档——包括入参、出参、枚举值、必填项。

• 累计调用 21 次，完成 39 个接口联调
• interface.ts 类型定义质量高，字段注释完整

MCP 二：飞书云文档直读

AI 可以直接读取飞书云文档内容，无需用户手工复制粘贴。

九、AI 能力边界框架

AI 是一个"顶级执行者"

AI 是一个极度服从、无限耐心、但没有内部业务知识常识的"顶级执行者"。

• 极度服从：AI 会一字不差地执行你写的规范，不会主动质疑
• 无限耐心：34 个任务的重构、跨会话的上下文恢复，AI 做起来没有摩擦成本
• 没有内部业务常识：AI 不知道你们公司的部署环境，不知道接口版本变化

按需求颗粒度选择协作模式

需求颗粒度	协作模式	场景
小颗粒	对话式	改文案、修显隐逻辑、调 CSS
中颗粒标准化	Rules/Skills	标准 CRUD、简单业务组件
中大颗粒复杂	OpenSpec SDD	重构核心逻辑、复杂业务模块

AI 失效的三种模式

模式一：规范真空

• 任务涉及的领域没有规范约束
• 应对：在 CLAUDE.md 或 code-design 中补充规范

模式二：信息孤岛

• AI 掌握的信息是当前会话快照，看不到系统外状态
• 应对：跨平台、跨环境的依赖在架构设计阶段提前锁定

模式三：任务目标模糊

• AI 把"该问人的问题"当成"执行问题"来解决
• 应对：Spec 工作流的 proposal 阶段强制要求先描述"Why"

十、开发者角色的重构

AI Coding 不是让开发者"消失"，而是让开发者的工作向上迁移：

• 规范设计能力成为核心竞争力
• 系统性思维变得更重要
• 质量意识前移：在方案设计/任务执行阶段就介入

一句话总结

AI Coding 的本质不仅仅是"用 AI 写代码"，而是用结构化的规范和工作流把不确定性消除在执行之前——AI 负责在确定性空间里高速执行，人负责维护和扩展那个确定性空间的边界。

规范是杠杆，AI 是力，Spec 工作流是支点。