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

一、前言

历经 10 天时间，写下了 2.5 万行代码，实现了提效 36%的成果，进行基于 Claude Code 的 Spec Coding（规格驱动编码）深度实战，借助 2,754 次工具调用，我们不但完成了从 0 到 1 的前端项目搭建，还在“约束+示范+视觉”的三层规范体系状况下，摸清楚了 AI 编程的真实能力边界，本文会就这场实战展开复盘，剖析怎样运用结构化工作流消除 AI 的不确定性，重新构建开发者的核心竞争力。

二、Spec Coding，它所指的究竟是什么呢，是Spec Coding工作流呀。

人们都知道，Spec Coding（规格驱动编码）的核心观念是，在着手编写代码以前，要先撰写规格文档。借助 openspec 工具，每一项功能变更都会历经以下阶段：

Spec 工作流的实际价值

降低返工情况：于proposal阶段清晰明确为何以及如何去做，防止在实施完毕后才发觉方向出现偏差。适宜复杂功能：针对那些需要跨越多个文件以及多个层次的功能，tasks分组能使AI专注于当下步骤。具备可审计性：每个Change的完整决策链（即proposal→design→specs→tasks）会留存记录，便于进行回溯。

三、项目是什么

企业级中后台搭建有个标准样式，其中涵盖表格、表单这类常见核心功能，还有卡片列表以及数据看板等，该项目是从无到有搭建，直至完成下面这些全部功能，整个过程运用Claude Code来辅助进行开发。

四、数据概览

于此次运用Claude Code开展Spec Coding的从零至一项目探寻进程里，我们积攒起一份完备的原始数据，下述所有数字皆源自Claude Code针对109个.jsonl会话文件的整体数据统计。

2,754次工具调用的分布被揭示了AI的“工作方式”，其中，AI自主完成了738次文件读取，完成了550次代码编辑，完成了662次终端命令执行，还完成了208次任务进度标记，这些几乎对一个研发日常工作的全部动作类型都做到了覆盖。

五、开发时间线：10 天的演进过程

阶段一：设计阶段

事先，我们做完了产品方向的认定，以及 UI 设计文稿、产品 PRD 的给出。期间主要借助 Cursor 添加设计标准项 Rules，径直从概念交流直至造出高保真 UI 文稿（HTML 文件），接着造出标准的 PRD 需求说明，涵盖系统全部核心页面。此状态的收获是一组能够直接用以发展对齐的视觉参照，也是往后 AI 生成代码之际的关键上下文源头。

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

这段时间，我们主要采用问答样式展开互动，将重点置于项目基础设施的构建以及对简单需求的试验，在此期间我们针对架构方面的问题向AI进行询问，随后由AI给出相应方案，待我们做出决定之后再予以施行。于这个进程当中，AI助力我们去熟悉技术栈，搭建起项目结构，配置好开发环境，并且完成了首个核心列表页面的创编，顺利连通了前后端的数据链路。

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

在整个项目开发的各个阶段之中，此阶段的强度是最高的阶段了，我们为工作流程引入了“规格驱动编码”也就是“Spec Coding”，大约80%那么长的所有功能代码都是在此阶段完成的，我们不再是以简单的方式给AI下达指令了，而是先和AI一起共同定义清晰的那种由文字构成的功能规格也就是“Specification”，之后AI依据这份如同“蓝图”的规格来自行开展编码工作，通过这样的一种特别的方式，我们高效率地完成了涵盖授权管理、数据分析看板、文档树状结构等多项较为复杂的功能的开发工作。

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

于最末阶段之时，工作重心迁至功能迭代以及系统重构，还有生产环境的部署排障。我们搭配ＡＩ，针对既有功能开展了多轮层进式优化，举例来说，完善化了核心业务流程，对侧边栏导航予以了重新构建，修复了登录跳转逻辑等诸般事宜。与此同时，我们针对项目首页开展了深度层次的代码重构作业，以此化解了前期快速迭代进程里积攒下来的技术债。最终，于部署阶段当中，我们遭遇了复杂纷纭的构建问题，经由与ＡＩ的多轮缜密分析以及反复尝试，最终精准定位并妥善解决了该问题，顺遂达成应用部署上线之实效。

六、典型案例案例一：AI 驱动产品设计

不存在产品经理，不存在UI设计师的情况下，一名工程师怎样借助AI独立自主地达成由产品定义起始，接着通过高保真原型，最后到研发展开文档那样的整个流程呢。

背景：

在传统的那种意义模式之下，从数字零开始一直到数字一去着手开发一个面向企业层级的知识问答平台而言，总共是需要有三个不同方面的承担角色的，分别是产品经理这边，其职责在于需求剖析以及用户路径规划还有PRD文档撰写，再者是UI设计师，其工作内容是交互稿设计以及高保真设计稿制作，最后是工程师，其任务是进行编码实现。而在这个项目的设计进程当中，借助于让人工智能在不同的发展阶段去扮演不一样的角色，从而将全部的这三个职责范畴都涵盖住了。

让 AI 扮演产品经理：

于 Rules 里植入「首席产品专家」Persona 提示词，把 AI 从工程师的「急于执行」模式转变为产品经理的「先想清楚」模式，跟 AI 聊明白我们想要做什么。

让 AI 扮演 UI 设计师：

在Rules里对设计规范予以定义，借由对话式生成的方式，逐页去产出高保真HTML文件，并非源码。

让 AI 生成研发可读的 PRD：

在产品经理这个角色的基础之上，把 HTML 设计稿当作上下文，最终生成 PRD，该 PRD 会精确到组件行为的级别。

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

交付一个关于已有系统上按增量模式的，完整功能模块，SDD 要怎样去保证就那个「增量」功能可以快速地去开发，并且还得通过系统性地提升前后端相连接进行调试的效率。比如说其中存在一个关于 SSD 需求的开发，内容是「定时任务管理」这个完整的模块，而且还要去对接 6 个后端的接口。这一回，是 SDD 工作流头一回被完整地运用到新功能模块的开发过程当中，同时这也是去验证「SDD + MCP」模式下前后端联调能够提高效率的关键场景。

页面功能开展开发工作，从 opsx:new 进行到 archive ，其中人工下达的指令数量小于 10 条，且 AI 代码所占的比例为 100% ，并且完成并且交付完整的任务管理模块，该模块包含独立路由以及完整的 CRUD ，还有执行记录以及检索结果。

前端与后端进行联调时，SDD加上MCP的联调路径是这样的，接口URL，指向MCP直连文档，通过它一次性获取字段、枚举、必填项，之后接口文件一次生成，最终联调一次就通过了，6个接口都没有出现联调返工。

研发效率方面，在同一天，额外交付了两个完整的模块，还有3个独立且完整的模块，并且在单日就全部开发完成了，要是按照纯人工进行开发的话，当天的人效提升了3倍。

案例三：SDD 驱动系统重构

重构与新功能的根本差异：

新功能开发呈现出「从无到有」的特性，AI 能够大胆地进行生成操作，一旦出现错误便予以删除，然后重新再来。重构则如同「在活体系统上实施手术」，这种具备高风险的情况，对 AI 执行提出了全然不同的要求，这要求不仅涵盖要明确知晓需要修改的内容，还包括更要清楚不能修改的部分，以及按照怎样的顺序去进行修改。而 SDD 的价值恰恰就体现在这里，即在动手改动代码之前，需将这三件事情全部清晰地书写出来。

知识问答首页重构：

架构方面存在债务情况，具体表现为，有许许多多个首页业务组件，它们与公共组件混合放置在一起，还有，useChat会导出20多个方法，其中存在4种无关职责相互混合的状况，另外，ChatInterface会接收17个props，这些参数在传递过程中呈现出3层传递的情形。

执行TASKS：9组，其中包含34个子任务，分别从「grep确认组件当前归属」开始，之后沿着「按新分层迁移」的方向，再到「更新所有import路径」，接着进行「tsc类型检查」，最后开展「冒烟验证」，每一步都存在明确的输入以及验收标准。

执行得出的结果是，34个任务整体都已然完成了，其中还包含着4个验证任务，AI在整个过程里都是独自进行执行的，人工进行干预的指令数量小于5条。7个业务组件跟公共组件达成了解耦，useChat被拆分成了3个具有单一职责的hook，ChatInterface从原本的17个props减少到了6至8个。

案例四：复杂问题排障

非全部与编程有关的问题，AI皆能够予以解决，什么样的工程问题，于结构方面超越了AI的能力界限呢？在此列举一个所碰到的场景。

其中有一天，遭遇到一个测试环境构建失败的状况，结果其过程大约历经 4 小时，涉及 7 个会话，进行了 15 次以上方案尝试，下达了 59 条指令，是整个项目当中单日指令数量最多的那一天，同时也是 AI 独立解决能力最为受限的一天。

在这一天，具备且呈现出一个值得予以特别注意的显著特征，那就是，AI 所进行的每一次分析，其结果都是正确无误的，然而，实际存在的问题并非在于 AI 的分析能力存在欠缺不足，而是在于所面对问题在结构方面所展现出的特征，已然超出了 AI 自身所拥有的信息涵盖范围以及相应的反馈机制。

最后确认的原因：

最终解法（4 小时探索后得出）：

七、代码规范落地现象，CLAUDE.md以及Rules的实际效果规范体系设计思路，呈现出三层结构的状态。

这个项目搭建起来的规范体系展现出的是三个层次相互之间协同起来进行约束这般的情况，每一个层次所解决的是不一样的问题。

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

为什么需要三层？

仅仅存在「约束层」的境况下，AI 明晰规则然而欠缺参考实现，于复杂场景中极易生成符合规则却不符合团队风格的代码。当加入「示范层」以及「视觉层」之后，AI 能够径直对齐团队的标准产出，进而减少「虽合法却不地道」的代码。

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

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

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

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

针对项目平常会出现的那些场景，预先设置好完整的那个「标准模板代码」，人工智能在制作新页面之际能够直接去参照，往后还能够切换成skills。

.claude/code-design/
├── pro-table/          # 通用列表页模板（含搜索、分页、批量操作、行操作）
├── pro-form/           # 通用表单页模板（含创建/编辑双模式、字段验证）
├── editable-pro-table/ # 可编辑表格模板（含行内编辑、添加/保存/删除）
├── drawer/             # 抽屉组件模板（含标准打开/关闭逻辑）
├── compontent/         # 通用组件模板（含 README、Props 定义、使用示例）
└── utils/              # 工具函数模板

示范代码的功用不是仅仅局限于「纯粹看个样式」哪那般简单。就拿 pro-table 来讲，当开发者吩咐 AI「参照 .claude/code-design/pro-table 去生成知识治理列表页面」之际，AI 马上承袭了这个模式，一回便能够产出契合团队风格的代码，根本用不着历经多轮的调整。

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

注意存放 HTML 设计稿，覆盖主要页面的视觉参考：

.claude/ui-design/
├── knowledge-spaces.html  # 知识空间列表页设计稿
├── search-strategy.html   # 检索配置页设计稿
├── space-detail.html      # 空间详情页设计稿
└── xxx设计稿

这些HTML文件，能够直接于浏览器当中打开进行预览，AI同样能够读取其中的结构以及样式信息，通过实践来看，在提供HTML设计稿之后，AI所生成的UI，与设计意图的吻合度显著高于纯文字描述，特别是在布局结构、颜色方案、间距配置等这些细节方面。

规范约束的实际效果

正面效果（规范被遵循的案例）：

需要人工干预的案例：

结论：

规范体系针对AI的约束存有效果，然而呀，规范文件仅是「约束」并非「能力」，当仅有「约束层」之际，AI晓得不能怎样去做什么，可是一旦碰到复杂场景之时，依旧有可能生成不够地道的代码，在加入「示范层」以及「视觉层」以后，AI具备了对齐的锚点，输出质量以及一致性显著提高了。

八、MCP 工具：消除信息断层

在借助 AI 来辅助前端开发之时，存在着两类属于高频信息断层的情况，于这个项目里面进行了接入操作。

接口文档出现断层状况，即接口文档处在 API 平台，AI 没办法直接进行访问，只能依靠用户手动去复制字段，这样一来容易出现遗漏情况，而且会存在版本不一致的现象。需求文档也是如此状况，PRD、设计文档处在飞书云文档里，每次用到的时候都需要用户先打开，接着复制，然后粘贴到对话框，如此这般会打断思路。

MCP 一：接口文档直连

凭借此工具，AI 能够依照接口 URL 自行拉取完整接口文档，其中涵盖入参字段、出参结构、枚举值定义、必填项标注。总共被调用达 21 次，达成 39 个接口联调 ，几乎覆盖了所有接口的初次接入以及更新迭代情景。在服务端接口尚未生效之际，而且支持同步生成 mock 数据 ，进而减少后端依赖。interface.ts 类型定义质量相当高 ，字段注释完备 ，无需人工进行校对。

MCP 二：飞书云文档直读

借助这个MCP工具，AI能够直接读取飞书云文档里包含的内容，像PRD、设计说明以及技术文档等等诸如这类情况的啦，并不需要用户亲自手工去打开，随后再进行复制，接着又粘贴这样一系列的操作哦。

典型应用场景：

九、AI Spec Coding 的经验总结，重新去理解一下，「AI 辅助编程」到底意味着什么 ，这是什么。

被广泛流传着讲法的是，「AI 是你的 Copilot」。这样一个用来比方的说法，在日常进行补全这个层面是能够成立的，不过呢，在经历了 Spec Coding方面的实践以后，我更加倾向于另外的一个模型，那就是说 ，AI 是一个在服从方面表现得极其到位、在耐心程度方面是无限的，然而却不存在内部的业务知识以及常识的「顶级执行者 」。

这个比喻捕捉了三个关键特征：

毫无保留地极度服从，即：AI 会按照你所写的规范，丝毫不差地去执行，不会主动去质疑“如此这般做是否合理”。这既是一种优势，可也是一种风险——规范要是写得越精准，那么执行起来就越可靠；可要是规范存在歧义，AI 会去挑选一个“看上去好像合理”的解释，而并非停下来向你问询。

具备无限耐心，该 AI用于做34个任务的重构、9组联调任务以及进行跨会话的上下文恢复，而此类事情在人类身上原本是要耗费大量意志力。并且，在本项目208次TodoWrite调用的背后，该AI凭借持续更新进度状态且从不嫌烦的特性，做这些事毫无摩擦成本。

不具备内部业务常识，AI不清楚你们公司的部署环境是怎样的，不晓得这个接口在上周才刚更换过版本，不明白「把这个交互做成这样用户会产生抱怨」。它仅仅知晓你告知它的内容。这同样是3/4生产构建排除故障耗费大量时间的根本缘由。

AI 的能力边界在哪里

从十天，也就是有着两千七百五十四次工具的调用当中，我们归纳出来的并非是简单的做出「能做/不能做」这种断定，而是一个更为精确细致的，关于能力边界的体系框架标点符号。

处于实际项目里，并非全部的真实需求都具备书写一份规范说明的价值。于实际的项目持续推进过程当中，我们得依据需求的细化粒度状况来挑选与之适配的协作方式。

小颗粒需求：对话框即扫即改

对于中颗粒的标准化需求而言，是基于Rules来预设规范继而进行生成的，或者是基于Skills来预设规范进行生成的。

中大颗粒复杂功能：OpenSpec 深度协作

AI 失效的三种模式

经历了本项目的实际操作，AI Coding的失效并非是随机产生的，而是能够进行归类的：

模式一：规范真空

任务涉及的领域没有规范约束，AI 自行填充「合理默认值」。

模式二：信息孤岛

AI 掌握的信息是当前会话的快照，看不到系统外的状态。

模式三：任务目标模糊

AI 把「该问人的问题」当成「执行问题」来解决。

开发者角色的重构

它并非是要让开发者彻底「消失」，AI Coding所达成的是引领开发者将任务朝着更高层次进行迁移：

这意味着：

在AI时代，对于开发者而言，规范设计能力变成了核心竞争力——能够写出那种能使AI可靠执行的规范，其价值比写出具备同等功能的代码还要高。

排障经验于生产构建问题方面表明，AI虽能够协助你去处理每一个不同的局部方面的问题，倘若你缺失系统性思维，那此AI便不能助力你去察觉真实形态的业务全局，而且系统性思维此时会变得愈益关键。

质量意识往前移，以往是在代码写完之后才开展 Code Review，如今则要在方案设计阶段就参与进去，并且在任务执行阶段也要介入，并非等到 AI 执行完毕之后才去纠错。

值得期待的方向

基于本项目的数据和经验，后续在以下方向可作深入探索：

对规范体系展开结构化的积累，每一次在踩坑之后，将其补充进CLAUDE.md/rules里，进而组成团队共同分享的「AI执行约束库」。当下，7条规范文件是通过手动方式进行维护的，接下来能够构建处于「踩坑→提炼规范→自动追加」的一种闭环状态。

MCP工具链朝着纵向方向的延伸如下：在本子项目里，MCP仅仅涵盖了接口文档以及飞书文档。而在后续阶段，针对设计稿、测试用例、发布平台、日志平台的接入情况而言，可进一步构建起完整的AI Coding链路。

多智能体并行开发，于本项目开发进程里察觉，大型任务执行之际等待时间偏长，接下来能够尝试多智能体并发生成，与此同时开展不同功能模块的开发。

一句话总结

AI Coding 的本质并非单纯是借助 AI 去撰写代码，而是运用结构化的规范以及工作流，将不确定性于执行之前予以消除，其中，AI 承担在确定性空间内高速执行的职责，人则负责维护并扩展那个确定性空间的边界。

十天，二百一十七条指令，两千七百五十四次工具调用，两万五千五百四十六行净增代码，一组数字背后，是一套能让人工智能“看见”、“理解”、“遵循”团队约定的规范体系。规范为杠杆，人工智能作力，Spec工作流当支点。

这份报告是由claude code依据claude code的109个真实历史会话、2,754次工具调用记录而生成的，之后经过人工进行补充以及校准，其数据来源为：~/.claude/projects/-Users-admin-Desktop-code-knowledge-qa/。

往期回顾

探讨C++引擎回归能力构建事宜，从自我检测阶段起始，直至达成工程项目化的准确推出标准，此乃得物技术所关注的内容。

2.得物社区搜推公式融合调参框架-加乘树3.0实战

3.深入剖析Spark UI界面：参数与界面详解|得物技术

4.Sentinel Java客户端限流原理解析｜得物技术

5.社区推荐重排技术：双阶段框架的实践与演进｜得物技术

相关标签： # AI编程 # SpecCoding # 得物技术 # ClaudeCode # 开发效率