这也许就是Harness诞生的过程：从文档协作到 SDD（Spec-Kit），我们如何摸索出一套 AI 协作研发范式

2026 那年关于 AI Coding 的神奇案例已经很多了。也有很多小伙伴在分享自己在 AI Coding 一块的经验但这里有个问题作为一个技术负责人站在团队角度应该如何弄清楚到底应该如何与 AI 合作因为当前问题就已经挺多了昨天同学团队里发生了激烈争执。产品用AI出原型图前端开发拒绝接收。吵架到最后前端哭了为了弄清楚到底该如何与AI协作这件事我们做了一次基于 Spec-Kit 的一次生产团队落地探索实践的结果也很符合预期AI 真正进入研发流程不是先选模型/工具而是先立规范在实践开始前我们原本想解决的是如何让 AI 在人的监管下尽可能完整地承担代码实现但真正做进去后发现最大的瓶颈根本不在代码生成而在需求边界、规则口径、接口约束、验收标准这些前置上下文是否稳定。也正因为如此我们最开始补的不是编码工具链而是需求对齐本身。在具体实践上我们从飞书文档承接需求和规则到开发同步工具连接文档和代码仓再到最终转向基于 Spec-Kit 的 SDD我们最后真正得到的不是一套单独的工具用法而是一套与 AI 协作的研发范式让规范、实现、验证、修复和反馈回写逐步形成闭环让 AI 不再只是辅助写代码而开始在约束下参与真实研发。Spec-Kit开始讨论之前我们先简单说一下 Spec-Kit。它是 GitHub 在 2025 年开源的一个工具集核心理念是规范驱动开发Specification-Driven Development简称 SDD。这套工具提供了一套很轻的流程骨架用 /specify 把需求和约束讲清楚用 /plan 把方案拆明白用 /tasks 列成可执行的小任务最后让 AI 按 /implement 一步步把代码写出来。我们之所以选择基于它来做验证原因也很直接不是因为它社区热度高而是因为我们在实践中摸索出来的那套规范雏形全局规范、feature 分层、需求/设计/验收拆开这里后面会介绍和 Spec-Kit 的理念高度一致。因为 Spec-Kit 很好的满足了我们的想法又很轻量级所以我们就直接用了但要注意Spec-Kit从来不是今天的重点我们今天不是来介绍工具的而是我们是如何摸索出一套与 AI 协作的研发范式。好现在正文开始…我们想解决什么一开始我们想做的事情很明确不是让 AI 来帮人补几段代码、写一两个页面而是希望在人的监管下让 AI 尽可能完整地承担代码实现。能不能 100%替代人能替代人的 百分之多少这重来都是一件重要的事情辅助写代码更像给现有研发流程打强力补丁哪里缺就补一下。它当然有价值但整体上并不会真正改变研发链路本身。人依然是主执行者AI 只是一个更聪明一点的加速器。而让 AI 尽可能完整实现代码就不一样了。这意味着 AI 不再只是边角料的补充角色而要开始进入主流程要真正承接需求、完成实现并在反馈中继续收敛。这个时候问题就不再只是模型够不够强而是团队有没有把输入整理到足够可执行。换句话说这里第一个本质问题就产生了AI 的问题很多时候并不是模型强弱的问题而是前置上下文的问题。如果需求边界没有讲清楚验收标准写了等于没写那么人来实现会返工AI 来实现同样会返工。区别无非是人可能慢一点地出错AI 往往能更快地把问题做大。AI像一个效率放大器好的输入会被放大坏的输入也一样会被放大。因为其效率极高如果前面的边界一旦没立住它会以一种相当敬业的方式把问题又快又整齐地做出来。所以需要优先补的不是编码工具与模型而是需求、规则、接口、验收这些前置上下文的稳定表达出发点是什么很重要因为它意味着我们要解决的首先不是怎么让 AI 写得更快而是怎么先把该说清楚的东西说清楚然后基于此再谈 AI 协作。作为个人可以盯着模型、盯着生成但如果着眼于团队先顶着的就一定是约束这也在我们团队产生了一个情况AI 对个人可能是 200%、500% 的提效但一进入团队数字键就要低很多这涉及到了团队更底层的协作问题了如果想让 AI 真正承担实现那么团队必须先把怎么把事情讲清楚这件事做得比以前更认真。这也是为什么后来的整条路径没有先从代码开始而是先从需求对齐开始。文档对齐既然问题的关键不在写代码而在先把事情讲清楚那么接下来的问题就变得很现实了这些需求、规则、接口、任务、验收到底应该靠什么来承接。那时候我们其实调研过几种不同方式包括更偏工程化的 Markdown也包括团队内部已经广泛在用的飞书文档这一步看起来像是在选工具实际上是在设计协作流程我们需要的不只是一个能写字的地方而是一个能让产品、前后端、测试、AI 共同围绕它工作的载体。首先是 Markdown他的优势很明显结构清晰、天然贴近代码仓、版本化也更顺手。但问题在于我们是要设计整个团队的协作流程真实团队不是只由工程师组成。只要产品、测试、业务方还需要高频参与你就很难只站在技术上所谓“更优雅”的角度做决定。所以飞书/钉钉文档就出现了。他的优势恰恰在另一边大家的接受度高协作门槛低评论、讨论、共享、修改都比较顺。很多时候一套方法能不能落地决定因素未必是谁更先进而是谁更容易先跑起来。最终当然是选择钉钉/飞书文档咯这里有一个点特别想强调我们当时并不是想多写文档。相反我们真正想做的是用文档把那些原本散在会议、聊天、口头约定和个人记忆里的东西尽量往一个更稳定的结构里收。而这一步本来就很难多数时候我们的规则只能控制自己不能约束太多部门毕竟**“写代码”是我们本质工作而其他部门没有义务配合我们除非有公司降本增效的大棒**。规范雏形所以飞书阶段做的事情从最开始就已经远远不只是把文档写清楚了。管理推动阶段的故事暂时不表我们先回归文档约束本身我们逐渐摸索出了一套很朴素、但已经带有明显规范意识的组织方式。最开始文档当然也带有记录属性毕竟需求讨论、方案梳理、接口约定这些东西总要先有地方落下来。但随着使用深入我们明显地感受到**文档如果只承担记一记的作用它的价值其实很有限。**因为记录并不会天然变成约束。所以飞书阶段很快就出现了一个变化文档开始不再只是为了留痕而是开始承担交付过程里的实际作用。它不只是记录大家说过什么而是开始承接需求对齐、实现约束、联调依据和验收口径。再往前走一点我们很快发现并不是所有内容都适合混在一起写。有些东西明显不是某一个 feature 独有的而是很多功能都会反复引用的通用规则。比如一些统一口径、共享定义、公共约束、跨功能都适用的边界判断这类内容如果每个 feature 都各写一份看起来像是自给自足实际上很快就会变成各写各的版本。于是当时我们就开始有意识地区分两类内容一类是全局规范更适合沉淀那些跨 feature 复用的稳定规则另一类是 feature 交付内容更适合围绕某个具体功能展开需求、设计、实现和验收。除了全局和局部的区分feature 内部也开始逐渐形成层次。那时候我们已经不满足于用一篇文档把所有内容糊在一起而是开始有意识地拆分不同角色关心的内容。最典型的就是围绕 feature 逐步形成了 PRD、BED、FED 等分层PRD 主要承接业务目标、场景、范围、规则和需求边界BED 主要承接后端实现设计、接口、数据结构、约束和服务逻辑FED 主要承接前端页面、交互、状态流转、联动逻辑和实现关注点再往下还会根据需要补充任务拆解、测试口径、验收内容等配套信息。如果用现在的视角回头看飞书阶段其实已经有很明显的 Spec 驱动特征了只是那时候我们还没有把这件事明确叫成 SDD也还没有迁移到更适合工程化承接的结构里。文档代码两层皮飞书阶段走到后面一个很现实的问题很快摆到了桌面上文档虽然开始承接交付了但它和代码仓之间还是两张皮。在线协作当然方便大家都能看、都能改、都能评论。只不过一旦文档开始承担规范和约束的作用问题就变了**它不再只是放在那儿供人参考的材料而是需要和代码实现建立更稳定的关系。**否则文档写得越认真后面维护起来反而越容易累。最典型的问题就是同步。飞书里有一版仓库内部也有一版今天在线上改了一点明天本地可能还是旧的讨论时以最新版本为准开发时看到的却不一定是同一份内容。这些问题在文档只是补充说明的阶段还能靠人盯住一旦文档开始承担交付约束它们就会迅速变成真正的协作摩擦。也正因为如此我们后来专门开发了一个飞书文档上传、下载、同步的工具。说白了这个工具想解决的事并不复杂尽量把飞书里的内容和代码仓协同起来让文档不要永远悬在仓库外面当一个大家都说重要但谁也不敢完全依赖的平行系统。这个动作本身其实已经说明了一件事我们当时已经不满足于在线文档协作了而是在尝试把文档真正纳入研发链路。换句话说飞书阶段走到这里问题已经不再是文档写没写而是文档能不能跟实现一起跑。这是一个很重要的变化。因为它意味着我们对文档的期待已经从承接信息进一步升级成了承接协作。但也正是在这个过程中问题逐渐暴露出来同步只是表层真正困难的是文档管理、版本约束、发布消费以及整套机制的持续维护。而这挺难的越后面越难说得直白一点文档越来越像代码了需要版本需要依赖关系…这个时候飞书就不够用了其实大家都看得出来这里出了一个问题文档同步开始成了一个负担。这个时候Spec-Kit 的价值就出现了Spec-Kit 的意义其实从这里大家就会更清晰 Spec-Kit 出现的原因了。前面提到为了解决飞书文档上传、下载、同步的问题我们专门开发了一个工具。这个工具原本只是想补齐文档体系和代码仓之间的协同缺口目标很务实真的让我们那套流程走起来。但巧的是这个工具本身似乎正是基于 Spec-Kit 理念开发的。这件事在当时带来的冲击并不是我们发现了一个新工具而是我们第一次在实际使用里直接感受到了另一套组织方式的手感。Spec-Kit 最初进入我们视野时也并不是一开始就以主角身份登场的。它不是作为一个需要全团队立刻切换过去的新范式出现的而是先出现在一个更具体的场景里我们在开发飞书同步工具时拿它作为底层组织方式来用。这个顺序很重要。因为一旦从看别人怎么介绍变成自己拿来做一个东西很多原本停留在概念层的内容马上就会落到手感层。结构是不是清楚边界是不是自然需求、计划、任务、验收之间是不是顺得起来这些事不用再靠想象判断了做一轮就知道。也正是在这个过程中我们第一次不是听说 Spec-Kit 不错而是直接上手感受到这套东西的骨架确实是顺的。更有意思的是随着工具开发推进我们并没有觉得自己在学一套完全陌生的新东西反而越来越强烈地感受到一种熟悉感…因为此前飞书阶段已经摸索出来的很多做法比如区分全局规范和 feature 内容区分需求、设计、实现、验收的职责让文档从记录走向承接交付而在 Spec-Kit 这里被放进了一套更完整、更清晰的骨架里。他尤其需要大家关注的是背后的组织方式它让需求、计划、任务、实现、验收这些原本很容易散开的东西第一次有机会沿着一条更自然的路径串起来。不是今天需求单独写一份明天任务再补一份后天测试口径另开一份大家最后靠脑补去拼接而是从一开始就承认这些东西本来就应该是同一条链路上的不同节点。也正是在这里选择就很清晰了直接上 Spec-Kit 就好。从 Spec-Kit 到 SDD接下来的发展很清晰我们开始进一步调研 SDD。接触 Spec-Kit更多是让我们看到了一个更合适的骨架那么调研 SDD则是让我们第一次把整件事从文档协作问题提升到研发方法问题来理解。前面那条路走下来团队其实已经积累了不少直觉只靠文档记录不够只靠在线协作不够只靠同步工具也不够规范如果不能进入运行链路最后还是会停在看起来很重要的层面。直到接触 SDD这些直觉才第一次被系统地串成一句完整的话我们真正需要的不是一套更会同步文档的方案而是一套更完整的规范驱动交付模式。一旦这么理解团队关心的就不再只是文档放哪儿、怎么同步、谁来改而会变成更底层的一组问题规范如何组织规范如何承接共享事实规范如何和 feature 交付衔接规范如何进入实现仓规范如何支持验证、修复与持续演进。当问题被提到这个层面时飞书体系的问题也就更清楚了。它不是不能做而是天然更适合协作与讨论不太适合承接一套持续运行的规范系统。所以后来转向基于 Spec-Kit 的 SDD并不是因为前面的飞书阶段做错了更不是因为那套探索没有价值。恰恰相反如果没有那一段我们后面大概率也很难这么快走到这一步。真实团队协作紧接着我们又碰到了另一个现实问题Spec-Kit 很适合把单个 feature 的起手式做完整但真实团队协作并不会停在起手式。在单个 feature 里Spec-Kit 对我们的帮助非常直接需求编写、问题分析、方案对齐、计划拆分、验收标准这些事情都能被组织得更清楚。过去那些容易散、容易混、容易反复口头补充的内容第一次真正被拉进同一条链路里。但真正进入实现阶段后团队协作会自然冒出两个新的问题第一代码实现过程中常常会反推 spec 做调整第二代码实现完成之后还需要系统地检查代码和 spec 是否真的对齐现实里很少有哪份 spec 一开始就完全正确。需求讨论阶段看着没问题真正一落到实现里旧代码、已有模型、接口约束、命名习惯、边界场景、历史兼容性这些东西就会一个接一个冒出来。这时候你会发现问题并不总是代码没按 spec 写。有些时候是实现偏离了规范有些时候反而是规范本身还不够完整甚至在个别场景下现有代码里的某些处理方式比 spec 写得更合理。所以真实团队里spec 不可能是一次写完就封版的静态产物。它必须允许被实现过程持续反向校正。否则规范和实现之间的关系就会很快从约束变成脱节。而在另一端实现写完之后到底有没有真的对上规范也不能靠口头确认。按 spec 开发这句话在很多团队里都很常见。但如果没有一轮系统化检查它很容易停留在口头层面。大家都觉得自己是按规范做的真到接口一对、字段一拉、权限一验、页面一看才发现所谓差不多和真的对得上中间通常还隔着一条不算短的路。所以后来我们又补了一组面向实现阶段的能力。一边约束 AI 在子仓里按规范写代码不只是看当前 feature还会自动加载依赖 feature 的上下文同时读取主仓规范和子仓约定写代码前先做既有代码侦察另一边在代码写完后再把实现重新拉回规范里逐项核对检查接口、字段、权限、枚举、页面结构这些关键点到底有没有真的一致。这些扩展的核心目的不是把按规范开发说得更漂亮而是尽量把这件事变成一件可检查、可验证、可收口的事情。真正跑进生产团队后我们也越来越清楚验证这件事不能只靠最后一脚。这次探索带来的变化如果只看表面这次探索像是在换文档结构、换协作方式、换仓库组织甚至顺手换了一批工具。但真正发生变化的并不是工具箱更丰富了而是大家开始习惯并遵守这套流程了。首先需求对齐的载体变了。研发流程开始有意识的被前置了这套方式跑起来之后需求对齐第一次开始有了更稳定的承载结构。甚至老板之前做战略需求讨论时候习惯性的忽略技术人员现在都有所改变。其次**规范和实现的关系变了**文档和代码之间常常是两层皮。过去文档负责说明代码负责落地中间那段最关键的翻译过程往往还是靠人脑兜底。而现在规范不再只是写给人看的说明材料而开始真正进入实现链路。它既是人理解需求和边界的依据也是 AI 消费上下文、展开实现的依据。更重要的是它不再只是前置输入而开始在实现过程中被持续校正、在实现完成后被重新验证。总而言之当 AI 开始读文档当 AI 开始负责交付代码的时候整个工作流程、工作内容全部会变化第三AI 在研发中的角色变了。过去 AI 更像一个随叫随到的副驾驶。但随着规范、实现、验证和反馈回写逐渐串起来AI 在研发里的位置开始变化了。它不再只是接一个局部任务然后吐出一段代码而是开始沿着更完整的链路往前走先理解规范再完成实现然后接受测试和校验反馈接着继续修复问题必要时还会把发现的问题再反推回主仓。这个变化逐渐有些*反客为主了第四团队协作从靠人盯变成靠机制托底。当前这套方式还有很多地方在演化但一个很直观的变化就是越来越多原本靠经验丰富的人盯着的事情开始有机制先兜一层了主仓内部有没有自己打架不再完全靠人翻文档实现时发现 spec 和代码对不上不再只能靠口头沟通代码写完之后有没有真的按规范对齐也不再只是拍脑袋说应该差不多。最后研发链路的顺滑程度变了。过去最常见的状态是每个环节都不算缺。需求有人讲实现有人做测试有人验问题也总有人修单看每个点好像都在但一旦连起来就总觉得哪里不顺。现在这套方式的价值让这些齿轮开始更像一套传动系统。需求进入规范规范进入实现实现进入验证验证再回到修复实现过程中发现规范有问题还能继续回写主仓重新收敛正式口径。从体感上说研发过程确实变顺了。但更准确地说它不是更快了而是更连贯了。但为什么老板也愿意由着我们瞎折腾原因很简单有些岗位确实会消失…结语写到这里如果要问这次探索到底让我们想明白了什么我觉得未必是找到了一套标准答案。更准确地说是我们终于把一些原本模糊的问题看清楚了。首先真正的难点不在 AI 会不会写代码而在前置上下文是否稳定。AI 不会自动修复需求边界、规则口径、接口约束、验收标准里的问题它只会把这些问题更早、更快地暴露出来。所以这次实践给我们最直接的提醒就是AI 的引入不会自动修复协作问题它只会把协作问题暴露得更彻底。其次Spec-Kit 的价值在于把 feature 的起手式做完整而真实团队落地还要继续补上实现阶段的反馈与验证链路。它的意义不只是提供几份模板而是给了团队一个可以继续扩展的骨架。骨架一旦有了后面的反馈、验证、修复和回写才有地方可挂。再往下我们也越来越确认社区方案进入生产团队关键不是照搬而是持续演化。我们不是直接把 Spec-Kit 拿来照着用而是从业务目标出发先经历飞书文档、同步工具再到方法切换。真正有效的不是采用了什么而是怎么把它改到自己能用。而这次探索最重要的结果是我们最终越来越相信当规范、实现、验证、修复和反馈回写形成闭环时AI 才真正开始进入生产研发过程。它不再只是一个会补几段代码的局部工具而开始在规范约束下沿着一条完整链路稳定工作。所以如果一定要把这次探索压成一句话我更愿意这样说AI 真正进入生产研发过程不是从会写代码开始的而是从能在规范约束下跑完一条闭环链路开始的学AI大模型的正确顺序千万不要搞错了2026年AI风口已来各行各业的AI渗透肉眼可见超多公司要么转型做AI相关产品要么高薪挖AI技术人才机遇直接摆在眼前有往AI方向发展或者本身有后端编程基础的朋友直接冲AI大模型应用开发转岗超合适就算暂时不打算转岗了解大模型、RAG、Prompt、Agent这些热门概念能上手做简单项目也绝对是求职加分王给大家整理了超全最新的AI大模型应用开发学习清单和资料手把手帮你快速入门学习路线:✅大模型基础认知—大模型核心原理、发展历程、主流模型GPT、文心一言等特点解析✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑✅开发基础能力—Python进阶、API接口调用、大模型开发框架LangChain等实操✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经以上6大模块看似清晰好上手实则每个部分都有扎实的核心内容需要吃透我把大模型的学习全流程已经整理好了抓住AI时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】