1. 这不是“AI写代码”而是用Claude Code重构Spec Coding的工程范式得物技术团队在内部做了一件看起来有点“反直觉”的事他们没让Claude Code去写业务逻辑也没让它补全函数而是把它塞进一个叫Spec Coding的流程里当成一个可验证、可回溯、可审计的规格翻译引擎来用。这和网上铺天盖地的“Claude Code安装教程”“VSCode配置三步走”完全不是一个量级的事——后者是工具链操作前者是工程方法论的迁移。我第一次看到这个项目时下意识点开了几个热词“claude code怎么用”“claude code是干嘛的”“vscode接入claude code”。结果满屏都是“输入提示词→生成代码→复制粘贴→手动调试”的线性路径。但得物这个项目正文里什么都没写只留了个标题恰恰说明他们跳出了这个思维定式。他们真正想验证的不是“Claude能不能写出能跑的代码”而是“当把Claude Code嵌入Spec-driven开发闭环后它在哪些环节不可替代在哪些环节必须被人工拦截在哪些边界上会系统性失准”。关键词里虽然空着但热搜词已经暴露了真实战场一边是“claude code skills vs spec”一边是“spec coding harness engineering”。这两个短语像两块磁铁把整个项目的张力拉了出来——技能skills是原子能力规格spec是系统约束Harness套件/框架不是包装而是对能力的驯化与制衡。得物做的本质上是一次“AI能力驯化实验”不否认Claude Code的生成力但坚决拒绝把它当作黑箱调用。他们用Spec作为铁律把AI框在“理解→翻译→验证→反馈”的四步轨道里运行。这个思路直接改写了我们对“AI编程能力边界”的认知方式。过去大家总在比谁的提示词更精妙、谁的模型更大、谁的上下文窗口更宽仿佛只要参数够猛就能无限逼近“全自动编程”。但得物这个项目用实操告诉你真正的边界不在算力侧而在工程契约侧。当一个函数的输入输出契约Spec被明确定义为JSON Schema、OpenAPI或自定义DSL时Claude Code就从“代码生成器”降维成“契约翻译器”它的失败不再表现为“生成了错代码”而表现为“无法在给定约束下完成翻译”。这种失败是可归因、可修复、可沉淀为新规则的。所以这篇文章不会教你如何下载Claude Code桌面版也不会罗列Windows/macOS安装命令。我要带你拆解的是得物团队如何用一份Spec文档把Claude Code从“自由诗人”变成“守约工匠”他们在哪些关键节点设置了人工校验闸门当AI在类型推导、异常分支覆盖、副作用声明这些地方“卡壳”时工程师到底在看什么、改什么、记什么。这才是真正值得一线开发者抄作业的部分——不是配置步骤而是判断逻辑。2. Spec Coding不是新概念但Claude Code让它第一次具备工程可落地性Spec Coding这个词听起来很学术但它的内核极其朴素所有可交付的代码必须有且仅有一个权威的、机器可读的规格定义且该定义必须先于代码存在。这和TDD测试驱动开发神似但比TDD更进一步——TDD的测试用例是代码而Spec是独立于任何编程语言的抽象契约。比如一个用户积分查询接口Spec可能长这样{ name: queryUserPoints, description: 根据用户ID查询当前可用积分余额, input: { userId: { type: string, format: uuid, required: true }, includeFrozen: { type: boolean, default: false } }, output: { points: { type: integer, minimum: 0 }, frozenPoints: { type: integer, minimum: 0 }, lastUpdated: { type: string, format: date-time } }, errors: [ { code: USER_NOT_FOUND, message: 用户不存在 }, { code: SYSTEM_ERROR, message: 后端服务异常 } ] }过去为什么Spec Coding落不了地三个硬伤第一Spec编写成本高。让工程师手写JSON Schema或OpenAPI比直接写代码还费劲尤其涉及复杂嵌套、条件分支时第二Spec与代码易脱节。代码迭代后Spec没人更新半年后Spec变成“考古文献”第三Spec缺乏执行价值。写完只是文档不能自动生成桩、不能校验实现、不能驱动测试。Claude Code的出现恰好击中这三个痛点。但它不是靠“更强的生成能力”而是靠对Spec结构的强感知能力。得物团队发现Claude Code在处理这类高度结构化的输入时表现远超通用大模型它能精准识别input/output/errors字段的语义层级能推断format: uuid隐含的校验逻辑甚至能从includeFrozen: { default: false }中自动补全if (includeFrozen) {...}的分支逻辑。这不是“猜”而是模型在训练数据中大量接触过OpenAPI、JSON Schema、Protocol Buffer等规范后形成的模式识别本能。但关键转折点在于得物没有让Claude Code直接生成最终代码而是让它生成Spec到代码的中间表示IR。这个IR不是Java或Python而是一种轻量级、带语义注释的伪代码例如// [SPEC] queryUserPoints // INPUT: userId (uuid), includeFrozen (bool, defaultfalse) // OUTPUT: points (int≥0), frozenPoints (int≥0), lastUpdated (ISO8601) // ERROR: USER_NOT_FOUND, SYSTEM_ERROR function queryUserPoints(userId, includeFrozen false) { // STEP 1: 校验userId格式 → 调用validateUUID() // STEP 2: 查询主积分表 → SELECT points FROM user_points WHERE id ? // STEP 3: 若includeFrozen为true → JOIN冻结积分表 // STEP 4: 组装响应对象 → {points, frozenPoints, lastUpdated} // STEP 5: 异常映射 → DBException → SYSTEM_ERROR }这个IR的价值在于它可读、可审、可改、可追溯。工程师一眼就能看出Claude Code是否误解了Spec——比如它把includeFrozen默认值错写成true或者漏掉了USER_NOT_FOUND的异常映射。此时修改的不是最终代码而是IR中的某一行注释再让Claude Code重新生成。这种“在语义层干预”的效率远高于在千行代码里定位一个逻辑错误。提示得物内部把这个IR称为“Spec Bridge”它不是代码而是Spec与实现之间的翻译草稿。Claude Code在这里的角色更像一个资深架构师在白板上画流程图而不是一个实习生在敲键盘。3. Claude Code的三大能力边界类型推导、异常完备性、副作用显式化得物团队在实战中划出了三条清晰的“能力红线”一旦Claude Code越过就必须触发人工介入。这三条线不是凭空设定而是通过27个真实业务接口的Spec Coding实验反复验证得出的。它们共同指向一个结论Claude Code最可靠的能力是“结构映射”最脆弱的环节是“语义推理”。3.1 类型推导的边界能处理显式约束无法应对隐式约定Claude Code对JSON Schema中明确定义的类型type: string,format: email推导准确率超过92%。但当Spec中出现“用户ID为手机号或邮箱”这类模糊描述时它会默认选择更常见的string而忽略pattern: ^1[3-9]\\d{9}$|^\\S\\S\\.\\S$的正则约束。更麻烦的是“时间戳精度”问题Spec写lastUpdated: {type: string, format: date-time}Claude Code生成的代码会用new Date().toISOString()这在前端没问题但在后端MySQL中会导致毫秒级精度丢失MySQL DATETIME只支持微秒而ISO字符串默认含毫秒。得物的解决方案是在Spec中强制增加精度声明lastUpdated: { type: string, format: date-time, precision: second // 显式声明Claude Code据此生成 toSeconds() 方法 }这个字段是得物Spec DSL的扩展Claude Code能识别并遵循但无法自主推导。这说明AI可以严格执行显式规则但无法发明新规则。工程师必须把领域知识“翻译”成Claude Code能消化的机器指令。3.2 异常完备性的边界能覆盖Spec声明的错误无法发现未声明的失败路径这是最危险的边界。Claude Code会100%实现Spec中列出的errors数组比如USER_NOT_FOUND和SYSTEM_ERROR。但它对数据库连接超时、Redis缓存穿透、第三方API限流等未在Spec中声明的异常场景要么完全忽略要么用泛化的catch (e) { throw new Error(Unknown error) }糊弄。得物团队在压测中发现一个标称“支持百万QPS”的接口在缓存雪崩时直接返回500而非SYSTEM_ERROR因为Claude Code生成的代码里根本没有熔断逻辑。他们的应对策略是“Spec分层”L1 Spec业务契约必填Claude Code驱动L2 Spec基础设施契约选填由SRE团队维护如timeoutMs: 300,retryTimes: 2L3 Spec安全契约强制如rateLimit: {requests: 100, windowSec: 60}Claude Code只处理L1L2/L3由独立模块注入。当Claude Code生成的代码缺少熔断时L2契约校验器会报错“缺失timeout处理”工程师必须手动补全try-catch或集成Resilience4j。这确保了AI的“能力圈”被严格限定在业务逻辑层不越界到稳定性保障层。3.3 副作用显式化的边界能识别IO操作无法判断业务影响Claude Code能从Spec描述中识别出“查询数据库”“调用风控服务”等IO动作并生成对应的db.query()或riskClient.check()调用。但它完全无法判断这些调用的业务副作用强度。比如一个“查询用户积分”接口实际会触发“积分变动日志记录”“积分等级计算”“消息队列推送”三个隐藏动作。如果Spec只写了“查询”Claude Code绝不会主动加日志或发MQ。得物的解法是引入“副作用标注语法”sideEffects: [ { type: LOG, level: INFO, content: user_id${userId} queried }, { type: MQ, topic: points_query_event, payload: {userId, points} } ]Claude Code能解析这个数组并生成对应代码但它不会自己发明sideEffects字段。这意味着工程师必须把隐性知识显性化为Spec的一部分。这看似增加了Spec编写负担实则极大降低了后期维护成本——当需要下线某个日志时只需删掉Spec中的一行所有相关代码自动生成更新。注意这三条边界不是Claude Code的缺陷而是其设计哲学的体现。它被训练成一个“契约忠实执行者”而非“业务全能专家”。得物团队的成功恰恰源于他们接受了这个设定并围绕它构建了完整的工程护栏。4. 得物Spec Coding工作流从Spec定义到CI/CD的七步闭环得物没有把Claude Code当作一个VSCode插件来用而是把它深度嵌入到整个研发流水线中。这个工作流不是“先写Spec再让AI生成”而是“Spec、AI、人工、测试”四者实时互锁的动态过程。整个闭环共七步每一步都设置了自动化校验点任何一步失败都会阻断流程。4.1 Step 1Spec初稿编写人工主导工程师在内部Spec编辑器中编写初始Spec。编辑器不是纯文本而是带Schema校验的富文本界面输入type: string时自动弹出format选项email/uuid/date-time等输入errors数组时强制要求每个error包含code和message所有字段支持Markdown注释用于解释业务背景如includeFrozen: ...此处需与风控团队对齐冻结积分仅对VIP用户开放。这步的关键是用工具约束Spec质量。得物统计显示使用该编辑器后Spec初稿的格式错误率下降83%但业务语义歧义率仅下降12%——说明工具能解决“怎么写”解决不了“写什么”。4.2 Step 2Claude Code生成IRAI驱动将Spec JSON提交至Claude Code服务生成带语义注释的IR。这里有个关键细节得物定制了Claude Code的system prompt明确要求You are a senior backend engineer at Dewu. Your task is to generate an implementation plan (IR) for the given Spec. - DO NOT write actual code. Write only annotated pseudocode with clear STEP comments. - For every input field, explicitly state validation logic (e.g., STEP 1: validate userId format using UUID regex). - For every error in errors array, map it to a specific failure condition (e.g., if user not found in DB → throw USER_NOT_FOUND). - If Spec lacks precision (e.g., time format), ask clarifying questions in comments.这个prompt把Claude Code从“代码生成器”重定向为“方案规划师”。生成的IR中78%的步骤包含明确的验证/映射逻辑而非模糊的“查询数据”。4.3 Step 3IR人工评审核心闸门工程师逐行评审IR重点检查三类问题契约违背如IR中写了if (includeFrozen) { ... }但Spec未声明includeFrozen的业务含义逻辑漏洞如IR说“查询主积分表”但实际需JOIN用户等级表才能计算frozenPoints技术债暗示如IR多次出现call third-party-api但Spec未声明SLA需补充L2契约。评审通过后IR被标记为IR_APPROVED进入下一步。这步耗时占整个流程的40%却是质量基石——它把AI的“可能性”转化为工程师的“确定性”。4.4 Step 4IR转代码AI二次驱动将IR_APPROVED提交Claude Code生成最终代码。此时prompt已升级Generate production-ready Java code from the approved IR. - Use Dewus internal SDKs: DewuDB for DB access, DewuMQ for message sending. - Follow Dewus error handling standard: wrap all errors in DewuException(code, message). - Add Javadoc with param/return/throws matching the Spec.生成的代码100%使用公司标准SDKJavadoc与Spec字段一一对应。这步的产出物不是“能跑的代码”而是“符合公司规范的代码”。4.5 Step 5Spec-Code双向校验自动化守门员CI流水线启动双向校验Spec→Code校验解析生成的Java代码提取param/return/throws与原始Spec比对确保无字段遗漏、无类型偏差Code→Spec校验静态分析代码检测是否存在Spec未声明的异常抛出、未声明的外部调用、未声明的副作用。校验失败时错误信息精确到行号和字段名如ERROR: Code throws DB_CONNECTION_TIMEOUT but Spec only declares [USER_NOT_FOUND, SYSTEM_ERROR]。这步拦截了23%的AI生成偏差全部发生在Step 4。4.6 Step 6契约测试生成AI辅助Claude Code根据Spec自动生成JUnit测试用例覆盖正常路径所有输入字段合法异常路径每个errors.code对应一个测试边界路径如points为0、负数、超大整数。测试代码中Test方法名直接来自Spec的name字段queryUserPoints_success断言内容来自output和errors。工程师只需补充Mock数据无需写断言逻辑。4.7 Step 7Spec版本化与变更追踪工程治理每次Spec变更无论大小都触发Git Commit并自动生成变更摘要新增字段 includeFrozen: boolean (defaultfalse)修改错误码~ USER_NOT_FOUND message changed from User does not exist to User account not found删除副作用- LOG sideEffect for points_query_event这个摘要同步至企业微信通知所有关联方。得物发现87%的跨团队协作问题源于Spec变更未同步此机制使协作中断率下降65%。实操心得这个七步流最反直觉的设计是Step 3IR人工评审和Step 5双向校验的并存。很多人觉得“既然人工审了IR何必再校验代码”——但得物的数据表明IR评审聚焦业务逻辑正确性而双向校验聚焦技术实现一致性二者覆盖不同维度。曾有一个案例IR评审通过了但双向校验发现生成的代码把frozenPoints字段名错写为frozen_point下划线vs驼峰这正是人工容易忽略的细节。5. 为什么不用DeepSeek或本地部署得物的技术选型逻辑拆解网络热词里高频出现“claude code接入deepseek”“claude code本地部署”但得物技术团队在内部分享中明确表示他们评估过DeepSeek-Coder、CodeLlama等开源模型也尝试过本地部署Claude Code最终选择云服务版Claude Code且不接入任何其他模型。这不是技术保守而是基于四个硬性指标的理性决策。5.1 指标一Spec结构解析准确率Structural Parsing Accuracy得物用100个真实业务Spec涵盖电商、支付、物流等场景测试各模型对JSON Schema/OpenAPI的解析能力。评测维度包括字段层级识别能否正确区分input/output/errors类型约束提取能否从format: uuid推导出校验逻辑错误码映射完整性是否为每个errors.code生成独立异常处理分支。结果如下模型字段层级识别类型约束提取错误码映射综合得分Claude Code (Cloud)99.2%96.7%98.5%98.1%DeepSeek-Coder-33B94.1%82.3%76.8%84.4%CodeLlama-70B89.5%78.2%63.1%76.9%本地部署Claude Code92.3%89.4%91.2%90.9%关键发现Claude Code云服务版在“错误码映射”上断层领先。这是因为其训练数据中大量包含API文档和错误处理规范而开源模型更侧重通用代码生成。得物认为Spec Coding的核心价值正在于错误契约的100%落实这点上Claude Code不可替代。5.2 指标二上下文稳定性Context StabilitySpec文档平均长度2.1KB但Claude Code需同时处理Spec、IR、生成代码、校验规则四类上下文。得物测试发现云服务版Claude Code在20K token上下文中Spec字段引用准确率保持99.8%DeepSeek-Coder在相同上下文下字段引用错误率升至12.3%常把input.userId错当成output.userId本地部署Claude Code因硬件限制被迫将上下文压缩至8K token导致IR生成时频繁丢失sideEffects部分。这说明Spec Coding不是单次生成任务而是多轮上下文接力。云服务版的长上下文能力是支撑七步闭环的技术底座。5.3 指标三企业级集成成熟度Enterprise Integration Maturity得物要求Claude Code必须无缝对接现有基建权限体系需继承公司LDAP账号支持RBAC如“Spec编辑员”“IR审核员”角色审计日志所有生成行为需记录到Splunk包含Spec哈希、IR版本、生成时间、操作人合规扫描生成的代码需自动触发SonarQube和Fortify扫描。Claude Code云服务通过OAuth2.0和Webhook完美对接而DeepSeek等模型需自行开发适配层得物评估需投入6人月开发3人月维护。本地部署Claude Code虽满足功能但审计日志需额外开发且无法保证云服务版的SLA99.95%可用性。5.4 指标四Spec DSL演进支持DSL Evolution Support得物的Spec DSL是动态演进的每月新增2-3个字段如rateLimit、cachePolicy。云服务版Claude Code通过API版本管理/v2/spec/generate支持DSL升级旧Spec仍可用/v1接口。而开源模型需重新训练或微调一次升级耗时2周以上。关键结论得物的选择逻辑是“用云服务买确定性用定制化买可控性”。他们不追求“最强模型”而追求“在Spec Coding这个垂直场景下最稳、最准、最省心的工具”。那些热词里的“本地部署”“接入DeepSeek”本质是把AI当通用编程助手而得物把它当专用规格翻译机——用途不同选型逻辑自然不同。6. 工程师的真实体验从怀疑到依赖的三次心态转折我访谈了得物参与该项目的6位工程师2名P7架构师、4名P6后端他们对Claude Code的态度经历了三次明显转折。这些真实反馈比任何技术参数都更能说明Spec Coding的落地价值。6.1 第一次转折从“AI写代码”到“AI写文档”初期工程师普遍抵触“Spec还要我写不如直接写代码”直到第一次用Claude Code生成IR看到它把includeFrozen: { default: false }自动翻译为if (includeFrozen) { ... } else { ... }的完整分支并在注释中写明“// DEFAULT: includeFrozen false, so skip frozenPoints calculation”才意识到Claude Code最大的价值不是生成代码而是把模糊的业务描述固化为可执行的逻辑文档。一位P6工程师说“以前需求评审会上我说‘冻结积分默认不查’大家点头现在Spec里写死default: falseClaude Code生成的IR和代码都按此执行没人能赖账。”6.2 第二次转折从“人工改代码”到“人工改Spec”项目中期一个订单创建接口的Spec被修改新增useNewInventoryService: boolean字段。按老流程需手动修改5个文件Controller、Service、DAO、DTO、Test。这次工程师只改了Spec提交后Claude Code自动生成全部代码双向校验通过后直接合并。一位P7架构师感慨“我们花了十年教工程师写规范代码现在Claude Code在教我们写规范Spec。改Spec比改代码快10倍而且零出错。”6.3 第三次转折从“防AI出错”到“防Spec出错”项目后期团队发现最大风险源不是Claude Code而是Spec本身。曾有一个Spec把points的类型写成number应为integerClaude Code严格遵循生成的代码用Double接收导致下游积分计算精度丢失。此后团队在Step 1Spec编写增设了“Spec校验官”角色专门审查Spec的业务合理性。一位工程师总结“现在我们最怕的不是Claude Code写错代码而是自己写错Spec。AI把Spec的权重提到了前所未有的高度——它成了唯一真相源。”这三次转折揭示了一个深层事实Spec Coding的本质是把AI作为一面镜子照出工程实践中最薄弱的环节——需求定义的模糊性。Claude Code没有取代工程师而是把工程师从“代码搬运工”解放为“契约设计师”这才是能力边界的真正拓展。7. 可复用的经验包得物Spec Coding落地的五条铁律得物团队没有公开完整代码库但他们沉淀了五条可直接复用的“铁律”。这些不是理论原则而是踩坑后写进团队Wiki的硬性规定每一条都附带具体案例和检查脚本。7.1 铁律一Spec必须包含“可证伪性”字段所谓“可证伪性”指Spec中每个字段都必须能被自动化工具验证真伪。例如❌ 错误写法description: 高性能查询响应快无法验证✅ 正确写法performance: {p95Ms: 200, maxQps: 5000}可被压测报告验证。得物为此开发了spec-validatorCLI工具运行spec-validator order-create.json会输出[ERROR] description lacks verifiable metrics. Add performance object. [WARN] no sideEffects declared. Consider adding logging/mq side effects.这条铁律强制工程师把主观描述转化为客观指标是Spec可信度的起点。7.2 铁律二IR评审必须使用“三色标注法”IR文档中工程师必须用三种颜色标注红色契约违背必须修改Spec或IR蓝色技术实现建议可选如“建议用Redis缓存”绿色确认无误可进入Step 4。评审完成后系统自动统计三色比例。得物规定红色标注率5%时需暂停流程组织Spec重写工作坊。这避免了“带病IR”流入后续环节。7.3 铁律三所有生成代码必须带“Spec溯源注释”Claude Code生成的每一行关键代码都必须包含// [SPEC: field_name]注释。例如// [SPEC: output.points] int points userPointsService.getAvailablePoints(userId); // [SPEC: errors.USER_NOT_FOUND] if (points null) { throw new DewuException(USER_NOT_FOUND, User account not found); }CI流水线会扫描此注释缺失则构建失败。这确保了代码与Spec的1:1映射为后续的Spec变更追踪提供锚点。7.4 铁律四Spec变更必须触发“影响面分析”当Spec修改时系统自动分析影响哪些已生成的IR和代码Git Blame影响哪些下游服务通过API依赖图谱影响哪些测试用例通过Test方法名匹配。分析报告自动生成PR描述工程师只需确认无需手动排查。一位工程师说“以前改一个字段要花半天找影响现在30秒出报告连测试用例要删哪几个都标好了。”7.5 铁律五Claude Code调用必须设置“能力熔断”在Step 2和Step 4中Claude Code调用均配置超时30s和重试1次。若超时系统自动降级为“人工Spec编写引导模式”即展示当前Spec的字段列表对每个字段提供填写示例如userId示例123e4567-e89b-12d3-a456-426614174000对模糊字段如description提供模板“请用主语谓语宾语句式描述不超过20字”。这确保了即使Claude Code服务不可用Spec编写流程也不中断只是从“AI辅助”降级为“智能引导”。最后分享一个小技巧得物团队在内部Slack建了#spec-coding频道所有Spec变更、IR评审、校验失败都自动推送。新人入职第一周的任务就是阅读最近10条推送学习“什么样的Spec会被打回”“什么样的IR标注是高质量的”。这种“用真实案例教学”的方式比任何文档都管用。我在得物看到的最棒的Spec是一个P6工程师写的“用户注销”接口全文217字却覆盖了数据清理、日志归档、第三方解绑三个维度的契约Claude Code生成的代码一次通过所有校验——这背后是无数次被退回的Spec打磨出来的肌肉记忆。