一、前言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的从0到1项目探索中我们积累了一份完整的原始数据以下所有数字均来自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 一起对已有功能进行了多轮优化例如完善了核心业务流程、重构了侧边栏导航、修复了登录跳转逻辑等。同时我们也对项目首页进行了深度的代码重构解决了前期快速迭代中积累的技术债。最后在部署阶段我们遇到了复杂的构建问题通过与 AI 的多轮分析和尝试最终定位并解决了问题成功将应用部署上线。六、典型案例案例一AI 驱动产品设计没有产品经理、没有 UI 设计师一个工程师如何用 AI 独立完成从产品定义到高保真原型、再到研发文档的全流程。背景传统意义上从 0 到 1 开发一个企业级知识问答平台需要三个角色产品经理需求分析 用户路径 PRD、UI 设计师交互稿 高保真设计稿、工程师编码实现。这个项目设计过程中通过让 AI 在不同阶段扮演不同角色覆盖了全部三个职责。让 AI 扮演产品经理在 Rules 中植入「首席产品专家」Persona 提示词将 AI 从工程师的「急于执行」模式切换为产品经理的「先想清楚」模式与 AI 聊清楚我们想干什么。让 AI 扮演 UI 设计师在 Rules 中定义设计规范通过对话式生成逐页产出高保真 HTML 文件而不是源码让 AI 生成研发可读的 PRD基于产品经理角色将 HTML 设计稿作为上下文最后生成精确到组件行为级别的 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 个单职责 hookChatInterface 从 17 个 props 缩减至 6-8 个。案例四复杂问题排障并不是所有编程相关的问题AI都可以解决哪类工程问题从结构上超出了 AI 的能力边界这里举一个遇到的场景。其中有一天遇到一个测试环境构建失败的问题结果过程约 4 小时7 个会话、15 次方案尝试、59 条指令。整个项目单日指令最多的一天也是 AI 独立解决能力最受限的一天。这一天有一个值得注意的特征AI 每次分析都是正确的——问题不在于 AI 的分析能力不足而在于问题的结构性特征超出了 AI 的信息范围和反馈机制云服务器构建时发生本地无法复现 每次验证方案必须提交代码等待 CI一轮约 10 分钟AI 分析的是日志截图无法感知「现在的 CI 环境还有哪些隐性配置」。多根因互相掩盖解决一层才暴露下一层 AI 每次分析都正确但正确分析的只是当前暴露的那一层问题全貌无法被单次分析覆盖。隐性行为无文档根因藏在依赖源码内部Prisma postinstall 境外下载没有任何显式错误引导AI 不得不深入阅读 node_modules 源码第 2319 行才能发现根因。这类「运行时行为藏在依赖内部、没有文档描述」的问题超出了 AI 通过训练数据或当前上下文主动推断的范围。最后确认的原因.npmrc 历史副作用 早期为跳过 next/swc-darwin-arm64 在 Linux 下载而加入的 omitoptional无意间也跳过了 tailwindcss/oxide-linux-x64-gnuTailwind v4 的 native bindingpostinstall 陷入循环等待Prisma v6 境外下载沉默卡死 AI 需要阅读 node_modules/prisma/fetch-engine/dist/index.js 第 2319 行才能发现这个行为——postinstall 不报错、不超时只是无限等待。pnpm 跨平台 lockfile 不一致 macOS arm64 生成的 lockfile 不含 Linux x64 的 native package切回 npm 则 lockfile 被忽略安装结果每次不同。最终解法4 小时探索后得出锁定 tailwindcss4.1.11配置PRISMA_ENGINES_MIRRORhttps://registry.npmmirror.com/-/binary/prisma。统一使用 pnpmCI 命令同步更新删除 .npmrc 中的 omitoptional。七、代码规范落地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/将项目常见场景预置完整的「标准模板代码」AI 在生成新页面时可以直接参照后续可以切换为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 与设计意图的吻合度明显高于纯文字描述尤其是布局结构、颜色方案、间距配置等细节。规范约束的实际效果正面效果规范被遵循的案例接口命名一致性所有接口函数均以 fetch{Name}Api 命名类型以 I{Name}Req/Res 格式整个项目 205 个文件保持高度一致。目录分层被遵守constants/、services/、hooks/、components/ 分层在每个新页面中都被正确创建。代码模板被继承 CURD页面均参照了 pro-table 模板的 hooks 分离方式代码结构高度一致。使用可选链几乎所有数据访问都使用了 ?. 和 ??有效避免运行时报错。需要人工干预的案例2/24AI 生成知识空间列表后将所有代码写在单文件中未按规范分层。通过一条追问后AI 重构为正确结构。2/27AI 错误地使用了 .less 后缀但项目实际配置使用 SCSS在收到错误提示后立即修正。出现 antd v5 废弃 APIdestroyOnClose、dropdownStyleAI 习惯于使用训练数据中更常见的旧 API需要通过报警信息触发修正。结论规范体系对 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 会选一个「看起来合理」的解释而不是停下来问你。无限耐心34 个任务的重构、9 组联调任务、跨会话的上下文恢复——这些在人类身上需要消耗大量意志力的事情AI 做起来没有摩擦成本。本项目 208 次 TodoWrite 调用背后是 AI 持续更新进度状态、从不嫌烦的特性。没有内部业务常识AI 不知道你们公司的部署环境是什么样的不知道这个接口上周刚换过版本不知道「这个交互做成这样用户会抱怨」。它只知道你告诉它的。这也是 3/4 生产构建排障花了大量时间的根本原因。AI 的能力边界在哪里从 10 天、2,754 次工具调用中我们归纳出一个更精确的能力边界框架而不是简单的「能做/不能做」真实项目中的并不是所有的需求都值得写一份 Spec。在真实的项目迭代中我们需要根据需求颗粒度来选择协作模式。小颗粒需求对话框即扫即改场景改个文案、修个显隐逻辑、调整 CSS 间距。策略直接在 Cursor Chat 中对话。理由沟通成本低于编写规范的成本AI 的即时反馈效率最高。中颗粒标准化需求基于Rules 或者 Skills 预设规范生成场景增加一个标准的 CRUD 页面、创建一个简单的业务组件。策略利用预设的 Cursor Rules 或 Skills如 pro-table.mdc。理由这类需求有强烈的“模式感”。只要规则定义清晰如“执行流程识别场景 - 读取示例 - 生成类型 - 完成 UI”AI 就能基于标准化模板高质量输出。中大颗粒复杂功能OpenSpec 深度协作场景重构核心逻辑、新增带有复杂业务逻辑的模块、无参考代码的新功能。策略OpenSpec 标准流 (SDD)。理由业务逻辑复杂时AI 极易产生幻觉或需求偏移。通过 Spec 强制进行“先设计后编码”可以确保 AI 的每一步都在既定轨道上且 Spec 记录了设计的决策过程对于后期维护价值巨大。AI 失效的三种模式经过本项目的实践AI Coding 的失效不是随机的而是可归类的模式一规范真空任务涉及的领域没有规范约束AI 自行填充「合理默认值」。表现生成的代码功能正确但风格/结构偏离团队约定。发生频率高尤其在新功能开发初期。应对在 CLAUDE.md 或 code-design 中补充对应规范一次修复全局生效。模式二信息孤岛AI 掌握的信息是当前会话的快照看不到系统外的状态。表现本地正常CI 失败AI 分析每次都对但解的都是当前暴露的问题。发生频率低但代价高。应对跨平台、跨环境的依赖要在架构设计阶段提前锁定环境差异要写成规范前置处理。模式三任务目标模糊AI 把「该问人的问题」当成「执行问题」来解决。表现用户说「优化一下首页」AI 悄悄改了组件结构而不是先澄清目标。发生频率中。应对Spec 工作流的 proposal 阶段强制要求先描述「Why」避免 AI 自行填充目标。开发者角色的重构AI Coding 不是让开发者「消失」而是让开发者的工作向上迁移这意味着规范设计能力成为 AI 时代开发者的核心竞争力——能写出让 AI 可靠执行的规范价值比能写出同等功能代码更高。系统性思维变得更重要——生产构建问题的排障经历说明AI 可以帮你解决每一个局部问题但无法帮你看到真实业务全局。质量意识前移——过去 Code Review 在代码写完后进行现在需要在 方案设计/任务执行 阶段就介入而不是等 AI 执行完再纠错。值得期待的方向基于本项目的数据和经验后续在以下方向可作深入探索规范体系的结构化积累每次踩坑后补充到 CLAUDE.md/rules形成团队共享的「AI 执行约束库」。目前 7 条规范文件是手动维护的下一步可以建立「踩坑→提炼规范→自动追加」的闭环。MCP 工具链的纵向延伸 本项目 MCP 仅覆盖了接口文档、飞书文档。后续针对设计稿、测试用例、发布平台、日志平台接入可以进一步形成完整的AI Coding链路。多 Agent 并行开发 本项目开发过程中发现大型任务执行等待时间较长下一步可以尝试多Agen并发生成同时开发不同功能模块。一句话总结AI Coding 的本质不仅仅是用 AI 写代码而是用结构化的规范和工作流把不确定性消除在执行之前——AI 负责在确定性空间里高速执行人负责维护和扩展那个确定性空间的边界。10 天、217 条指令、2,754 次工具调用、25,546 行净增代码——这个数字背后是一套让 AI 可以「看见」、「理解」、「遵守」团队约定的规范体系。规范是杠杆AI 是力Spec 工作流是支点。本报告由claude code基于claude code 109 个真实历史会话、2,754 次工具调用记录生成人工补充并校准数据来源~/.claude/projects/-Users-admin-Desktop-code-knowledge-qa/。往期回顾1.搜索 C 引擎回归能力建设从自测到工程化准出得物技术2.得物社区搜推公式融合调参框架-加乘树3.0实战3.深入剖析Spark UI界面参数与界面详解|得物技术4.Sentinel Java客户端限流原理解析得物技术5.社区推荐重排技术双阶段框架的实践与演进得物技术文 /阳凯关注得物技术每周更新技术干货要是觉得文章对你有帮助的话欢迎评论转发点赞未经得物技术许可严禁转载否则依法追究法律责任。