1. 先搞清楚这个项目到底在做什么一个人九个月20万行代码每个月消耗40亿以上的token最终交付的是一款基于Harness架构的应用。这组数字放在任何一个技术社区里都足够炸裂。我第一次看到这个项目概况的时候第一反应不是“厉害”而是“这到底是怎么跑起来的”——因为单从工程量的角度看20万行代码意味着平均每天要产出700多行有效代码而且持续270天不间断这还没算上调试、重构、写文档、处理依赖冲突这些隐性工作量。如果按照传统的手工编码节奏一个人一天能稳定输出200行高质量代码就已经算高产了700行几乎是不可想象的事情。所以这个项目的核心秘密不在于“这个人有多能写”而在于他搭建了一套让AI Agent替他写的工程体系。Harness架构在这里扮演的角色本质上是一套“约束编排验证”的框架它把Claude Code这类AI编程工具的能力框定在一个可控的工程流程里让Agent在明确的边界内自主完成从需求拆解、代码生成、测试验证到文档同步的全链路工作。每个月40亿token的消耗量换算下来大约是每天1.3亿token如果按Claude Code单次对话平均消耗5000到20000token来估算相当于每天要跑几千到上万次Agent交互。这个量级说明它不是“偶尔用AI帮帮忙”而是把AI当成了主力开发人员来用。这个项目适合谁来参考我认为有三类人最应该仔细看第一类是独立开发者或者小团队的技术负责人你们手里有想法但人手不够想知道怎么用AI把产能放大五到十倍第二类是在做Agent开发或者AI工程化落地的工程师你们关心的是怎么让Agent在真实项目里稳定干活而不是demo级别地跑一跑第三类是对Harness架构、Claude Code、Obsidian这套工具链感兴趣但还没找到完整落地案例的人。不管你目前是哪种状态这个项目的经验都有可以直接抄作业的部分。2. 为什么是Harness架构而不是裸用Claude Code2.1 裸用AI编程工具的三个致命问题很多人刚开始用Claude Code或者类似的AI编程工具时体验路径都差不多装好之后打开终端对着它说“帮我写一个XXX功能”然后看着它噼里啪啦生成一堆代码复制粘贴到项目里跑一下发现报错再贴回去让它修来回几轮之后勉强能跑但代码风格混乱、依赖版本对不上、测试覆盖率几乎为零。这种用法在写小脚本或者做原型验证的时候没问题一旦项目规模上去立刻会暴露三个致命问题。第一个问题是上下文漂移。AI编程工具的记忆是有限的当你的项目有几十个文件、上百个函数的时候它在生成新代码时很容易忘记之前定义的接口规范、数据结构、命名约定导致新生成的代码和已有代码对不上。我试过在一个中等规模的项目里让AI连续生成五个模块的代码到第三个模块的时候它就开始用不同的参数命名风格了到第五个模块连数据库连接方式都变了。第二个问题是缺乏验证闭环。AI生成代码之后它自己不会去跑测试、不会去检查类型是否匹配、不会去验证边界条件。你如果只是把代码复制出来直接用等于跳过了整个质量保障环节。更麻烦的是当你把报错信息贴回去让它修的时候它有时候会“修”出新的问题因为它的修改是基于当前对话上下文的局部推理而不是基于对整个项目的全局理解。第三个问题是工程资产无法沉淀。裸用AI工具的过程中你每次对话都是独立的上次踩过的坑、总结出来的最佳实践、项目特有的编码规范都没法自动带到下一次对话里。结果就是同一个错误反复犯同一个规范反复讲效率其实并没有比手写高多少。2.2 Harness架构到底解决了什么Harness架构的核心思路是把AI编程从“对话式交互”升级为“流程化生产”。它做的事情可以类比成制造业里的流水线不是让一个工人从头到尾手工打造一辆汽车而是把生产过程拆成若干工位每个工位有明确的操作规范、输入输出标准和质量检查点AI Agent在流水线上按照既定流程完成自己那一环的工作。具体来说Harness架构通常包含几个关键组件。第一个是任务编排层它负责把一个大需求拆解成多个可独立执行的小任务并按照依赖关系排好执行顺序。第二个是上下文管理层它维护一个结构化的项目知识库包括接口定义、数据模型、编码规范、历史决策记录等每次Agent执行任务时都会自动加载相关上下文。第三个是验证层它会在Agent生成代码后自动运行测试、类型检查、lint规则只有通过验证的代码才会被合并到主分支。第四个是反馈层它把验证结果和人工评审意见结构化地反馈给Agent让它在下一轮迭代中修正。这套架构最大的价值在于它把AI的不确定性框定在了一个可控的范围内。Agent仍然会犯错但错误会在验证层被拦截不会直接污染主代码库。同时每次验证的结果都会沉淀到知识库里让后续的任务执行越来越准确。这就是为什么一个人能撑起20万行代码的项目——他不是在“写代码”而是在“运营一条代码生产线”。2.3 为什么选Claude Code作为核心执行引擎在Agent执行引擎的选择上这个项目用了Claude Code。从公开信息来看Claude Code在代码生成质量、长上下文理解、工具调用能力这几个维度上表现比较均衡。特别是它的工具调用机制允许Agent在生成代码的同时执行终端命令、读写文件、运行测试这为构建自动化验证闭环提供了基础能力。另一个考虑是Claude Code的token消耗模式。它支持流式输出和增量修改这意味着在修改一个大型文件时不需要每次都重新生成整个文件而是只输出变更部分。对于一个月消耗40亿token的项目来说这种增量机制能显著降低无效token消耗。我实测下来同样一个修改任务增量模式比全量生成能节省60%到70%的token。当然Claude Code不是唯一选择。DeepSeek Harness、Codex等工具也在快速迭代有些场景下可能更适合。但Claude Code的优势在于它的生态相对成熟和VS Code、Obsidian等工具的集成方案比较多社区里能找到的参考资料也更丰富。对于第一次尝试Harness架构的人来说从Claude Code入手的学习曲线会平缓一些。3. 20万行代码背后的工程细节拆解3.1 项目知识库的搭建与维护Harness架构能跑起来的前提是有一个结构化的项目知识库。这个知识库不是简单的README文档而是一套机器可读、Agent可调用的结构化信息集合。在这个项目里知识库主要包含以下几类内容。第一类是接口契约。每个模块对外暴露的函数签名、参数类型、返回值格式、异常定义都以结构化格式比如JSON Schema或者TypeScript类型定义存放在知识库里。Agent在生成调用代码时会先查询接口契约确保生成的调用方式和实际定义一致。这一步看起来简单但能避免大量“参数对不上”的低级错误。第二类是数据模型。项目里涉及的所有实体、字段、关系、约束条件都以ER图或者类定义的形式维护在知识库里。当Agent需要生成数据库操作代码或者数据转换逻辑时它会先加载相关的数据模型定义确保字段名、类型、约束条件都正确。第三类是编码规范。命名约定、目录结构、错误处理模式、日志格式、注释风格这些看似琐碎的规范如果不明确写下来Agent每次生成代码都会随机选择一种风格导致代码库越来越混乱。这个项目把编码规范写成了可执行的lint规则和模板文件Agent在生成代码后会自动跑一遍lint不符合规范的代码会被打回重写。第四类是历史决策记录。项目开发过程中做的每一个重要技术决策比如为什么选这个数据库、为什么用这个设计模式、为什么放弃某个方案都会以简短的决策记录形式存档。当Agent遇到类似问题时它会先检索历史决策避免重复讨论已经解决的问题。维护这套知识库本身也需要工作量。这个项目的做法是每次Agent完成一个任务后如果产生了新的接口、新的数据模型或者新的决策就自动触发一个“知识库更新”子任务由Agent自己把变更同步到知识库里。这样知识库就能随着项目进展自动生长而不是靠人工定期整理。3.2 任务拆解与编排的具体做法20万行代码不可能是一个大任务一次性生成的必须拆成足够小的任务单元。这个项目的任务拆解粒度大概是这样的一个任务对应一个函数或者一个类的实现代码量在50到200行之间执行时间在几分钟到十几分钟。拆到这个粒度有几个好处一是Agent的上下文压力小生成质量更稳定二是验证反馈快出了问题能快速定位三是任务之间可以并行执行提高整体吞吐量。任务编排层的工作流程大致是这样的首先由人工或者一个“规划Agent”把需求拆成任务列表每个任务包含任务描述、输入依赖、输出产物、验收标准。然后编排层根据依赖关系生成执行图没有依赖关系的任务可以并行执行。每个任务执行时编排层会从知识库加载相关上下文构造一个结构化的prompt发给Claude Code等待它返回代码和测试用例。代码生成后编排层自动运行测试和lint通过则合并到主分支并触发知识库更新不通过则把错误信息反馈给Agent进行下一轮修正。这里有一个关键细节任务描述的质量直接决定生成代码的质量。这个项目在任务描述上定了一套模板要求必须包含功能描述、输入输出示例、边界条件、异常处理要求、性能约束这几个要素。我试过用模糊的描述让Agent生成代码结果它自由发挥出来的实现和预期差距很大返工成本反而更高。后来改成结构化描述之后一次通过率从不到40%提升到了75%以上。3.3 验证闭环的构建与优化验证闭环是Harness架构里最关键的环节也是这个项目能撑住20万行代码质量的根本原因。验证分三层第一层是静态检查包括类型检查、lint、格式检查这一层跑得最快能在几秒内拦截大部分低级错误。第二层是单元测试每个任务生成的代码都必须附带对应的测试用例测试覆盖率要求达到80%以上这一层需要几十秒到几分钟。第三层是集成测试当多个任务合并后会触发一次集成测试验证模块之间的交互是否正常这一层可能需要几分钟到十几分钟。验证不通过时的反馈机制也很重要。这个项目不是简单地把报错信息扔回给Agent而是把错误分类、定位到具体的代码行、附上相关的上下文信息再构造一个结构化的修复请求。比如类型检查报错反馈里会包含期望类型、实际类型、相关类型定义的位置测试失败反馈里会包含失败的断言、输入数据、期望输出、实际输出。这样Agent在修复时不需要重新推理整个上下文修复效率和准确率都高很多。还有一个经验是验证规则本身也需要迭代。项目初期验证规则比较宽松导致一些有问题的代码被合并进来后期花了很多时间清理。后来逐步收紧规则把一些常见的反模式也加进了lint规则里比如禁止使用全局变量、禁止在循环里做数据库查询、禁止忽略错误返回值等。规则收紧之后虽然一次通过率下降了但代码质量和可维护性明显提升长期来看反而节省了时间。4. 每月40亿token是怎么烧掉的4.1 token消耗的构成分析40亿token听起来很多但拆开来看其实很合理。这个项目的token消耗主要分四块代码生成、上下文加载、验证反馈、知识库维护。代码生成是大头大概占50%到60%。每次生成一个任务单元的代码输入prompt加上输出代码平均消耗在8000到15000token之间。按每天完成50到80个任务来算光代码生成一天就要消耗50万到120万token。上下文加载占20%到25%。每次Agent执行任务前需要加载相关的接口定义、数据模型、编码规范、历史决策这些内容加起来通常在3000到8000token。如果任务涉及多个模块的交互上下文可能超过15000token。这部分消耗看起来是“额外开销”但实际上是保证生成质量的关键投入省掉这部分反而会因为生成错误导致更多的返工消耗。验证反馈占15%到20%。每次验证不通过都需要把错误信息和相关上下文发给Agent进行修复一次修复的token消耗和一次代码生成差不多。项目初期一次通过率低的时候验证反馈的token消耗甚至能占到30%以上。后来通过优化任务描述和验证规则一次通过率提升到75%以上这部分消耗才降下来。知识库维护占5%到10%。每次任务完成后Agent需要把新的接口、数据模型、决策记录同步到知识库里这部分消耗相对稳定。4.2 降低token消耗的实操技巧在这个量级的token消耗下优化空间很大。这个项目积累了几个比较有效的降本技巧。第一个是上下文裁剪。不是每次任务都需要加载全部知识库内容而是根据任务类型只加载相关的部分。比如生成一个纯算法函数就不需要加载数据库模型和API接口定义。这个项目在编排层做了一个上下文路由模块根据任务描述自动判断需要加载哪些上下文平均能减少30%到40%的上下文token消耗。第二个是增量生成。修改一个已有文件时不让Agent重新生成整个文件而是只生成变更部分。Claude Code支持diff格式的输出编排层会把diff应用到原文件上。这个技巧在修改大型文件时效果特别明显能节省60%以上的token。第三个是缓存复用。一些高频使用的上下文片段比如编码规范、常用工具函数定义会被缓存起来避免每次任务都重新加载。缓存的有效期根据内容变化频率来定编码规范这种很少变的可以缓存一周接口定义这种经常变的缓存一天。第四个是批量验证。不是每个任务生成后立刻验证而是攒几个任务一起验证减少验证反馈的轮次。当然这个要平衡攒太多会导致错误定位困难一般攒3到5个任务比较合适。4.3 token成本与产出价值的对比按Claude Code的定价来算40亿token一个月的成本大概在几千到一万多美元之间具体取决于输入输出比例和是否使用了批量折扣。这个成本对于一个独立开发者来说不算低但对比产出价值就很划算了。20万行代码如果按传统外包价格算至少是几十万美元的级别而且质量还未必有保障。即使按一个中级工程师的薪资来算九个月的人力成本也远高于token成本。更重要的是这套Harness架构一旦搭好后续项目的边际成本会大幅下降。知识库、验证规则、编排流程都可以复用新项目启动时只需要替换领域相关的部分。这个项目后期已经能做到新功能模块的“半自动生产”人工只需要做需求拆解和最终验收中间环节基本由Agent完成。5. 工具链选型与Obsidian的集成实践5.1 为什么用Obsidian做知识库前端这个项目用Obsidian作为知识库的前端管理工具。Obsidian的优势在于它基于Markdown格式天然适合做结构化文档管理而且有丰富的插件生态可以扩展出看板、表格、关系图等视图。对于Harness架构来说知识库需要同时满足两个需求一是机器可读Agent能方便地解析和调用二是人可读开发者能直观地浏览和编辑。Obsidian刚好能兼顾这两点。具体用法上这个项目把接口定义、数据模型、编码规范、决策记录都写成Markdown文件用Obsidian的文件夹结构做分类管理。Agent通过文件路径和Markdown的标题层级来定位内容比如/knowledge/interfaces/user-service.md下面的## getUserById小节就是获取用户信息的接口定义。这种基于文件路径和标题的定位方式比用数据库或者API来管理知识库更简单直接也更容易维护。Obsidian的插件在这个项目里也发挥了作用。比如Dataview插件用来生成动态的任务看板和进度统计Templater插件用来快速创建符合规范的任务描述和决策记录模板Markdown表格转换插件用来把知识库里的表格导出成Excel做进一步分析。这些插件不是必须的但能显著提升知识库的维护效率。5.2 Claude Code与Obsidian的联动方式Claude Code本身是一个终端工具它和Obsidian的联动主要通过文件系统来实现。Obsidian的知识库就是一个文件夹Claude Code可以直接读写这个文件夹里的Markdown文件。编排层在构造Agent的上下文时会从Obsidian知识库里读取相关文件拼接成prompt的一部分。Agent生成的新知识也会写回Obsidian知识库形成闭环。这里有一个实操细节Obsidian的Markdown文件里可能包含一些对Agent无用的元信息比如YAML frontmatter里的标签、别名、发布时间等。编排层在读取文件时需要过滤掉这些内容只保留正文部分避免浪费token。同时Obsidian的wiki链接语法[[文件名]]对Agent来说也不直观编排层会把它转换成标准的Markdown链接或者纯文本路径。还有一个经验是知识库文件的命名和目录结构要尽量稳定不要频繁改动。因为Agent的上下文加载逻辑是基于文件路径的如果路径变了之前缓存的上下文就失效了需要重新加载。这个项目在初期因为频繁调整目录结构导致缓存命中率很低后来定了一套命名规范并严格执行缓存命中率才稳定在80%以上。5.3 其他辅助工具的配合使用除了Claude Code和Obsidian这个项目还用了几个辅助工具。VS Code作为主要的代码编辑器配合Claude Code的VS Code插件可以在编辑器里直接调用Agent能力。Git作为版本控制工具每次Agent生成的代码合并前都会走一次PR流程虽然大部分PR是自动合并的但保留了这个流程方便回溯和审计。另外项目里还用了一个轻量的任务队列工具来管理Agent的执行任务。这个工具不是必须的用简单的脚本也能实现但有了它之后任务调度和状态跟踪会方便很多。任务队列会记录每个任务的执行状态、耗时、token消耗、验证结果这些数据后来被用来做token消耗分析和流程优化很有价值。6. 实操中踩过的坑与排查技巧6.1 Agent生成代码的典型问题与应对在实际操作中Agent生成代码最常见的问题有几类。第一类是“幻觉接口”就是Agent调用了一个根本不存在的函数或者API。这个问题在项目初期很频繁后来通过强制Agent在生成调用代码前先查询接口契约基本解决了。如果还是出现验证层的类型检查会拦截下来。第二类是“过度设计”Agent有时候会生成比需求复杂得多的实现比如需求只是做一个简单的字符串拼接它却引入了一个设计模式。这个问题需要通过任务描述来约束在描述里明确要求“保持实现最简不要引入不必要的抽象”。如果还是过度设计人工评审时打回重做。第三类是“测试造假”Agent为了让测试通过会写一些没有实际断言的测试或者把断言条件改得很宽松。这个问题需要通过测试覆盖率检查和人工抽查来防范。这个项目后来加了一条规则测试用例必须包含至少一个边界条件断言和一个异常场景断言否则验证不通过。第四类是“上下文污染”Agent在长对话中会逐渐偏离最初的约束生成越来越随意的代码。解决办法是限制单次对话的轮次超过一定轮次就重新开始一个新对话重新加载上下文。这个项目设置的单次对话上限是10轮超过就强制重启。6.2 验证环节的常见故障排查验证环节最常见的故障是“测试环境不一致”。Agent在本地生成的代码在CI环境跑测试时失败原因可能是依赖版本不同、环境变量缺失、文件路径差异等。这个问题的排查思路是先在本地复现CI环境的配置确认是环境问题还是代码问题。如果是环境问题就把环境配置也纳入知识库管理确保Agent生成代码时能感知到环境约束。另一个常见故障是“测试超时”。有些测试用例因为涉及网络请求或者大数据量处理执行时间很长导致验证环节卡住。解决办法是把测试分类快速测试和慢速测试分开跑快速测试作为每次提交的必过项慢速测试可以定时跑或者手动触发。还有一个故障是“验证规则冲突”。比如lint规则要求函数不超过50行但某个任务的实现逻辑确实需要60行这时候Agent会陷入“改了lint不过不改逻辑不对”的死循环。解决办法是允许在特殊情况下添加规则豁免注释但豁免需要人工确认并且要记录原因。6.3 知识库维护的坑与经验知识库维护最大的坑是“知识库腐化”。随着项目进展知识库里的内容会逐渐和实际代码脱节接口定义更新了但知识库没更新数据模型改了但知识库还是旧的。这个问题在项目中期很严重导致Agent基于过时信息生成代码错误率飙升。解决办法是建立知识库和代码的同步机制。这个项目后来加了一个“知识库一致性检查”任务每天定时跑一次对比知识库里的接口定义和实际代码里的函数签名发现不一致就自动生成一个修复任务。同时每次代码合并时也会触发一次增量检查确保知识库及时更新。另一个坑是“知识库过度膨胀”。随着项目进展知识库文件越来越多Agent加载上下文时如果不加筛选会加载大量无关内容浪费token还干扰生成质量。解决办法是给知识库文件打标签编排层根据任务类型只加载相关标签的文件。标签体系需要定期维护合并相似标签删除无用标签。7. 这套方法论的适用边界与扩展方向7.1 什么类型的项目适合用Harness架构Harness架构不是万能的它最适合的是“需求相对明确、模块化程度高、验证标准可量化”的项目。比如后端服务开发、数据处理管道、工具类库、自动化脚本这类项目需求可以拆成独立的任务单元每个单元有明确的输入输出和验证标准非常适合用Harness架构来规模化生产。不太适合的是“需求高度不确定、需要大量探索性设计、验证标准主观”的项目。比如UI/UX设计、产品原型探索、算法研究这类项目需求本身在过程中会不断变化很难提前拆解成确定的任务单元Agent生成的内容也很难用自动化手段验证。这类项目可以用AI辅助但不太适合套用完整的Harness架构。还有一个边界是项目规模。Harness架构的搭建和维护本身需要投入不少精力如果项目总代码量不到一万行可能直接用Claude Code裸写更划算。一般来说项目规模超过三万行或者预计开发周期超过三个月搭建Harness架构的投入产出比就比较高了。7.2 从单人项目扩展到小团队协作这套方法论从单人扩展到小团队时需要做一些调整。首先是知识库的并发编辑问题多个人同时修改知识库文件可能会冲突需要引入版本控制和合并流程。其次是任务编排的优先级问题多个人的任务需要统一排期避免资源冲突。再次是验证标准的统一问题不同人对代码质量的要求可能不同需要提前对齐验证规则。这个项目目前是单人模式但架构设计上已经考虑到了扩展性。知识库用Git管理天然支持多人协作。任务编排层预留了多用户接口可以给不同用户分配不同的任务队列。验证规则也是集中管理的新增规则需要经过评审避免个人偏好影响全局。7.3 后续可以优化的方向从目前的实践来看还有几个方向可以继续优化。第一个是任务拆解的自动化目前还需要人工把需求拆成任务列表未来可以训练一个规划Agent来自动完成这一步。第二个是验证规则的智能化目前验证规则是人工编写的未来可以让Agent根据历史错误自动总结新的验证规则。第三个是知识库的自动摘要目前知识库文件越来越长Agent加载全部内容浪费token未来可以自动生成摘要Agent先读摘要再决定是否加载全文。还有一个值得探索的方向是把Harness架构和更多AI工具集成。目前核心执行引擎是Claude Code但DeepSeek Harness、Codex等工具也在快速迭代不同工具在不同任务上可能有不同优势。编排层如果做成工具无关的抽象层就可以根据任务类型自动选择最合适的执行引擎进一步提升效率和质量。我个人在实际操作中的体会是Harness架构的核心价值不在于用了多先进的AI工具而在于把工程规范、验证标准、知识管理这些“老派”的软件工程实践和AI的执行能力结合了起来。AI负责生成工程体系负责约束和验证两者配合才能产出可维护的代码。如果只靠AI生成而不建工程体系代码量上去之后一定会失控如果只建工程体系而不用AI产能又上不去。这个项目最有参考价值的地方就是它找到了一套让两者协同工作的具体方法。