Harness架构实战：一人九个月二十万行代码的AI编程工程心得-北京尧图网络

1. 先搞清楚这个项目到底在做什么一个人九个月二十万行代码每个月消耗四十亿以上的 token最终交付的是一款基于 Harness 架构的应用。这几个数字摆在一起任何一个写过代码的人都会先愣一下。二十万行代码是什么概念一个中等规模的商业项目五到八人的团队做一年大概也就是这个量级。而这里是一个人九个月还要同时承担架构设计、编码实现、调试排错、文档撰写所有环节。更关键的是每个月四十亿 token 的消耗量意味着整个开发过程高度依赖 AI 辅助编程不是偶尔问几句而是把 AI 当成了日常开发的基础设施。这个项目最值得拆解的地方不在于“一个人写了多少代码”这种数字层面的震撼而在于它验证了一条路径在 Harness 架构的约束下借助 Claude Code 这类 AI 编程工具个人开发者可以完成过去需要小团队才能推进的复杂应用。Harness 在这里不是某个具体产品名而是一种架构思路——把 AI 能力作为可编排、可调度、可观测的执行单元嵌入到应用主流程中让模型调用、工具调用、状态管理、错误恢复形成一套完整的工程体系。适合读这篇内容的人有三类。第一类是想了解 AI Agent 应用到底怎么落地的人你可能用过 Claude Code、写过一些 prompt但还没想清楚怎么把它变成一个真正的产品。第二类是独立开发者或者小团队的技术负责人你在评估“一个人加 AI 能不能顶一个团队”这件事的可行性。第三类是对 Harness 架构、Agent 框架、Markdown 工作流这些概念有零散认知但缺少一个完整案例把它们串起来的人。我接下来会从架构选型、核心模块实现、实操流程、踩坑记录几个维度把这个项目的关键决策和实现细节拆开讲。不是泛泛而谈“AI 很强”而是具体到每一个技术选择背后的理由、每一个参数的计算依据、每一个坑的排查过程。2. Harness 架构的核心思路与选型逻辑2.1 为什么是 Harness而不是直接调 API很多人做 AI 应用的第一反应是直接调模型 API写一个函数传 prompt拿返回结果完事。这种做法在 demo 阶段没问题但一旦应用复杂度上来问题就会集中爆发。你需要处理多轮对话的状态管理、工具调用的编排、模型输出格式的校验、失败重试的策略、上下文的裁剪、token 消耗的监控这些东西如果全部手写代码量会迅速膨胀而且每一处都是潜在的 bug 来源。Harness 架构的核心价值就在于它把这些通用能力抽象成了一层“执行骨架”。你可以把它理解成一个流水线工厂模型是工人工具是机器Harness 是传送带和调度系统。工人和机器可以换但传送带的逻辑是稳定的。具体来说Harness 层通常包含这几个关键组件执行器Executor负责接收任务、拆解步骤、按顺序或并行调用模型和工具。状态管理器State Manager维护整个会话或任务的上下文决定哪些信息需要保留、哪些可以丢弃。工具注册中心Tool Registry管理所有可被 Agent 调用的工具包括 Markdown 解析、文件读写、搜索、代码执行等。可观测层Observability记录每一步的输入输出、耗时、token 消耗方便调试和优化。错误恢复机制Recovery当某一步失败时决定是重试、跳过还是回滚。我选择 Harness 架构而不是自己从零搭一套理由很直接二十万行代码里如果有三万行是在重复造状态管理和错误处理的轮子那这个项目根本做不完。Harness 把这些脏活累活接过去我只需要关注业务逻辑本身。而且 Harness 的可观测层让我能清楚地看到每个月四十亿 token 到底花在了哪里哪些环节在浪费哪些环节可以优化。2.2 Claude Code 在项目中扮演的角色Claude Code 在这个项目里不是“辅助写代码的工具”而是整个开发流程的核心生产力。我大致统计过二十万行代码里完全手写的部分大概只占百分之十五到二十剩下的部分都是在 Claude Code 的协助下完成的。具体的使用方式分几个层次第一层是代码生成。我给 Claude Code 提供清晰的接口定义和上下文它生成实现代码。这一层最基础也最容易被替代。第二层是架构评审。我会把设计文档丢给它让它指出潜在的问题比如某个模块的耦合度太高、某个数据流存在竞态条件。第三层是调试助手。遇到报错时我把错误日志和相关代码一起给它它给出的排查方向往往比我自己的第一反应更准。第四层是文档生成。项目里的 Markdown 文档、API 说明、配置注释大部分是 Claude Code 根据代码自动生成的。这里有一个关键经验Claude Code 的输出质量高度依赖你给它的上下文质量。你给它一个模糊的需求它给你一个模糊的实现。你给它精确的接口定义、边界条件、错误处理要求它给你的代码基本可以直接用。我在项目初期踩过这个坑后来养成了一个习惯每次让 Claude Code 写代码之前先花十分钟把接口和约束写清楚这十分钟能省掉后面一小时的调试时间。2.3 Markdown 作为核心数据格式的考量这个项目里Markdown 不只是文档格式而是核心的数据交换格式。Agent 的输入输出、配置定义、任务描述、结果记录全部用 Markdown 承载。为什么选 Markdown 而不是 JSON 或 YAML理由有几个Markdown 对人类友好。调试的时候我直接打开文件就能看懂内容不需要额外的解析工具。Markdown 对模型友好。Claude 系列模型对 Markdown 的理解能力极强用 Markdown 描述任务比用 JSON 描述的准确率明显更高。Markdown 的表格语法特别适合表达结构化数据比如参数对照表、状态映射表模型解析起来很稳。但 Markdown 也有坑。最常见的问题是换行处理。不同解析器对换行的处理方式不一样有的把单个换行当空格有的当新段落。我在项目里统一了规范段落内换行用两个空格加换行符段落之间用空行分隔。这个规范写进了项目的贡献指南所有生成的 Markdown 都必须遵守。另一个坑是表格转换。项目里经常需要把 Markdown 表格转成 Excel 或者从 Excel 转回来。我试过几个库最后选了一个基于 AST 的解析方案先解析成抽象语法树再按目标格式重新渲染。这样做的好处是转换过程可控不会出现格式错乱。3. 核心模块的实现细节与参数计算3.1 Agent 执行引擎的设计Agent 执行引擎是整个应用的心脏。它的核心任务是把一个高层任务拆解成可执行的步骤序列然后逐步执行每一步都可能涉及模型调用或工具调用。我采用的是“规划-执行-反思”三段式结构规划阶段模型根据任务描述生成一个步骤列表每个步骤包含目标、输入、预期输出、依赖关系。执行阶段按依赖顺序执行步骤每一步的结果写入状态管理器。反思阶段检查执行结果是否满足预期如果不满足决定是重试、调整步骤还是终止。这里有一个关键参数最大步骤数。我设的是五十步。为什么是五十因为统计下来百分之九十五的任务在三十步以内完成设五十步留出余量同时防止无限循环。超过五十步还没完成的任务大概率是规划阶段出了问题继续执行也是浪费 token。另一个关键参数是单步超时时间。我设的是九十秒。模型调用通常几秒到几十秒工具调用看具体操作。九十秒足够覆盖绝大多数情况超时后触发重试或降级策略。状态管理器的设计也有讲究。我采用的是滑动窗口加摘要的方案。最近十轮对话保留完整内容更早的内容压缩成摘要。这样既保证了上下文的连贯性又控制了 token 消耗。实测下来这个方案比全量保留节省了大约百分之六十的 token而任务完成率只下降了不到百分之三。3.2 工具注册与调用机制工具是 Agent 的手和脚。这个项目里注册了大概三十多个工具涵盖文件操作、Markdown 解析、搜索、代码执行、数据转换等类别。每个工具的定义包含名称、描述、参数 schema、返回值 schema、超时时间、重试策略。工具描述的质量直接影响模型的选择准确率。我踩过的坑是描述写得太简略模型经常选错工具。比如“读取文件”和“解析 Markdown”两个工具如果描述都写得很泛模型就分不清什么时候该用哪个。后来我把描述改得非常具体明确写出“这个工具用于读取原始文件内容不做任何解析”和“这个工具用于解析 Markdown 结构输入必须是 Markdown 格式的字符串”选择准确率从百分之七十多提升到了百分之九十五以上。工具调用的错误处理也值得说。我把错误分成三类可重试错误如网络超时、可降级错误如某个工具不可用但有替代方案、致命错误如参数格式错误。可重试错误自动重试三次间隔指数退避。可降级错误触发备用工具。致命错误直接返回给规划层重新规划。3.3 Token 消耗的监控与优化每个月四十亿 token 的消耗如果不做监控和优化成本会失控。我在 Harness 的可观测层里加了一个 token 统计模块按任务、按工具、按模型分别统计消耗量。数据出来之后发现了几个明显的浪费点第一个浪费点是重复的上下文。同一个任务里多个步骤需要相同的背景信息如果每一步都重新传一遍token 消耗会翻倍。解决方案是把共享上下文放在状态管理器里步骤执行时按需引用而不是全量复制。第二个浪费点是过长的模型输出。有些步骤只需要模型返回一个判断结果但模型倾向于输出一大段解释。解决方案是在 prompt 里明确限制输出格式和长度比如“只返回 JSON不要任何额外文字”。第三个浪费点是无效的重试。有些错误重试多少次都不会成功比如参数格式错误。解决方案是区分错误类型只对可重试错误执行重试。优化之后token 消耗下降了大约百分之三十五而任务完成率基本不变。这个优化过程让我意识到AI 应用的竞争力不只在于模型能力更在于工程层面的精细度。4. 完整实操流程与关键环节实现4.1 环境搭建与依赖安装项目的运行环境基于 Node.js 和 Python 双栈。Node.js 负责 Harness 层的调度和工具注册Python 负责数据处理和模型调用的底层封装。这种双栈设计的原因是Node.js 的异步 IO 适合做调度Python 的生态适合做数据和 AI 相关操作。安装步骤大致如下。首先安装 Node.js 二十版本以上然后安装 Claude Code 的命令行工具。Claude Code 的安装方式根据操作系统不同略有差异核心是确保命令行能正常调用。接着安装 Python 三点十一以上版本创建虚拟环境安装项目依赖。依赖清单里比较关键的几个包包括用于 Markdown 解析的 markdown-it 或 mistune用于状态管理的自定义模块用于 token 统计的 tiktoken 或类似库。配置方面需要设置模型调用的 API 密钥、并发数限制、超时时间、日志级别。我建议把配置分成三层默认配置写在代码里环境配置写在环境变量里运行时配置写在配置文件里。这样不同环境切换时不需要改代码。注意环境搭建阶段最容易出问题的地方是版本兼容性。Node.js 和 Python 的版本不匹配、依赖包之间的版本冲突都会导致后续步骤失败。建议在搭建完成后先跑一遍最小验证用例确认基础链路通畅再继续。4.2 核心配置文件的编写项目的核心配置用一个 Markdown 文件承载我把它叫做任务定义文件。这个文件的结构大致如下顶部是元信息包括任务名称、版本、作者、创建时间。中间是任务描述用自然语言说明这个任务要做什么。下面是步骤定义每个步骤包含步骤编号、目标、输入、输出、依赖、超时、重试策略。最后是工具白名单列出这个任务允许调用的工具。用 Markdown 而不是 JSON 写配置的好处是模型可以直接读懂配置内容不需要额外的解析步骤。而且 Markdown 的层级结构天然适合表达步骤之间的嵌套和依赖关系。配置文件的校验也很重要。我写了一个校验脚本检查步骤编号是否连续、依赖是否成环、工具是否在白名单里、超时和重试参数是否在合理范围内。这个脚本在每次加载配置时自动运行避免因为配置错误导致运行时失败。4.3 执行流程的完整走查一个典型任务的执行流程是这样的。首先加载任务定义文件解析成内部数据结构。然后初始化状态管理器把任务描述和全局上下文写入。接着进入规划阶段模型根据任务描述生成步骤列表。规划结果经过校验后进入执行循环。执行循环里每一步先检查依赖是否满足然后准备输入调用模型或工具获取输出写入状态管理器更新依赖状态。如果某一步失败根据错误类型决定重试、降级还是终止。所有步骤完成后进入反思阶段检查整体结果是否满足任务目标。如果不满足回到规划阶段重新规划最多循环三次。整个流程里最耗时的环节是模型调用最耗 token 的环节也是模型调用。所以优化的重点在于减少不必要的模型调用、缩短每次调用的输入输出长度、提高单次调用的成功率。4.4 结果输出与 Markdown 渲染任务的最终结果以 Markdown 格式输出包含执行摘要、步骤详情、关键数据、错误记录。执行摘要用一段话概括任务完成情况。步骤详情用表格展示每一步的状态、耗时、token 消耗。关键数据用列表或表格呈现。错误记录用引用块标注。Markdown 渲染我选了一个支持表格、代码块、数学符号的渲染器。项目里经常需要展示数学公式所以渲染器必须支持 LaTeX 语法。表格的渲染要注意对齐和换行太宽的表格在窄屏上会溢出我设置了自动换行和横向滚动。提示Markdown 表格转 Excel 是高频需求。我用的方案是先把 Markdown 表格解析成二维数组再用表格处理库写入 Excel 文件。反过来Excel 转 Markdown 表格时要注意处理合并单元格和公式这两个是常见的坑。5. 常见问题与排查技巧实录5.1 Agent 执行中断的排查思路Agent 执行中断是最常见的问题表现是任务跑到一半突然停了日志里只有一行“execution terminated due to error”。排查这类问题我总结了一个三步法第一步看错误发生的步骤编号。如果是第一步就挂了大概率是配置问题或环境问题。如果是中间步骤挂了看这一步的输入输出判断是模型问题还是工具问题。第二步看错误类型。超时、格式错误、权限错误、依赖缺失每种错误的处理方式不同。第三步复现问题。把出错步骤的输入单独拿出来手动执行一遍看是否能复现。我遇到过一个典型问题某个步骤在调用 Markdown 解析工具时反复失败错误信息很模糊。后来发现是输入内容里包含了一个不规范的表格解析器处理不了。解决方案是在解析前加一个预处理步骤规范化表格格式。5.2 Token 消耗异常的定位方法Token 消耗突然飙升通常有几个原因。一是某个步骤陷入了重试循环每次重试都消耗 token。二是上下文没有正确裁剪导致每次调用都携带了大量无关信息。三是模型输出了超长内容比如本该返回一个词却返回了一整段。定位方法是看 token 统计模块的明细。按步骤排序找出消耗最高的几个步骤。按时间排序找出消耗突增的时间点。按模型排序看是不是某个模型的调用量异常。找到异常点之后再去看对应的输入输出基本就能定位问题。5.3 常见问题速查表问题现象可能原因排查方法解决方案执行中断无详细错误配置错误或环境问题检查配置校验日志修正配置重跑校验某步骤反复重试输入格式不符合工具要求手动执行该步骤规范化输入格式Token 消耗突增上下文未裁剪或重试循环查看 token 统计明细优化上下文管理限制重试次数模型选错工具工具描述不够具体检查工具描述细化工具描述明确使用场景Markdown 渲染错乱换行或表格格式不规范检查原始 Markdown统一换行规范规范化表格任务完成率下降上下文裁剪过度对比裁剪前后的完成率调整裁剪策略保留关键信息5.4 独家避坑经验第一个经验不要相信模型的自我评估。模型经常说“我已经完成了任务”但实际上只完成了一半。我的做法是加一个独立的验证步骤用不同的 prompt 让模型检查结果或者用规则引擎做客观校验。第二个经验日志要记全但不要记太多。日志太少排查不了问题日志太多影响性能还占空间。我的做法是分级记录关键步骤记全量普通步骤记摘要调试信息只在开发环境记录。第三个经验版本控制不只是代码配置和 prompt 也要管。prompt 的微小改动可能导致输出质量的巨大变化。我把所有 prompt 都放在版本控制里每次改动都记录原因和效果。第四个经验定期做全链路压测。AI 应用的性能瓶颈往往不在代码本身而在模型调用的延迟和稳定性。定期压测能提前发现这些问题。6. 从二十万行代码里提炼出的工程心得6.1 代码组织与模块划分二十万行代码如果不做好模块划分维护起来会非常痛苦。我的划分原则是按职责分模块按依赖分层级。最底层是基础设施层包括日志、配置、错误处理、工具函数。往上是 Harness 层包括执行器、状态管理器、工具注册中心、可观测层。再往上是业务层包括具体的 Agent 实现、任务定义、结果处理。最上层是接口层包括命令行接口、API 接口、配置文件接口。层与层之间通过明确的接口通信不允许跨层调用。这样做的好处是修改某一层的实现不会影响其他层。比如我后来把状态管理器的实现从内存存储换成了持久化存储业务层完全不需要改动。6.2 测试策略与质量保障AI 应用的测试比传统应用难因为输出不是确定性的。我的测试策略分三层单元测试覆盖工具函数和纯逻辑模块这些是确定性的可以用传统方法测。集成测试覆盖模块之间的交互用 mock 替代模型调用验证流程是否正确。端到端测试用真实模型调用验证任务完成率用统计方法评估比如跑一百个任务看完成率是否达标。端到端测试的成本很高因为每次都要消耗 token。我的做法是只在发版前跑全量端到端测试日常开发用集成测试加少量端到端抽样。6.3 持续迭代与优化方向项目做完之后回头看有几个地方如果重来我会做得不一样。一是状态管理器的设计早期版本过于简单后来重构了一次如果一开始就设计得更通用能省不少时间。二是工具注册中心的接口早期版本没有考虑异步工具的支持后来加的时候改了很多地方。三是 prompt 的管理早期散落在代码各处后来统一到一个目录但迁移成本不低。后续的优化方向主要有三个。一是进一步降低 token 消耗通过更精细的上下文管理和更高效的 prompt 设计。二是提高任务完成率通过更好的规划算法和更完善的错误恢复机制。三是扩展工具生态接入更多类型的工具覆盖更多场景。6.4 个人开发者的效率边界这个项目让我重新思考了个人开发者的效率边界。过去我们认为一个人做不了大项目因为工作量摆在那里。但 AI 辅助编程改变了这个等式。关键不在于 AI 能写多少代码而在于 AI 能帮你跳过多少“不需要创造力的重复劳动”。我的时间分配大致是这样的百分之三十用于架构设计和关键决策百分之四十用于与 AI 协作编码和调试百分之二十用于测试和优化百分之十用于文档和整理。如果没有 AI 辅助编码和调试的时间至少要翻三倍项目周期会从九个月拉长到两年以上。但也要清醒地看到AI 辅助不是万能的。架构设计、关键决策、质量把控这些仍然高度依赖人的判断。AI 可以帮你写代码但不能帮你决定写什么代码。AI 可以帮你排查问题但不能帮你判断这个问题值不值得解决。个人开发者的核心竞争力正在从“写代码的速度”转向“做决策的质量”。我在实际使用中发现最容易高估的是 AI 的规划能力最容易低估的是 AI 的执行能力。让 AI 做一个复杂的架构决策它往往给出似是而非的答案。但让 AI 执行一个定义清晰的任务它的完成质量经常超出预期。所以我的策略是把复杂问题拆解成定义清晰的小任务让 AI 逐个执行我来做拆解和验收。这个策略在这个项目里被验证是有效的也是我愿意继续沿用的工作方式。

Harness架构实战：一人九个月二十万行代码的AI编程工程心得

相关推荐

航拍校园操场人体检测：YOLO数据集构建与密集小目标训练实战

强基计划与竞赛备考：微积分高效学习实战指南

CodeBuddy + WorkBuddy 实战：AI IDE 与 Agent 工作台如何打通开发全链路

更多资讯

Autoware入门实战：Ubuntu 18.04安装、数据回放与相机雷达联合标定全流程解析

FOC电机控制原理与STM32F407实战指南

C语言只有值传递：指针传地址的本质与工程实践

空洞卷积原理与实战：扩大感受野而不增计算量

Jev模型详解：AI的“系统一”决策革命

Linux日志排查实战：从命令组合到线上故障定位

今日更新

MATLAB+Yalmip+CPLEX实战：综合能源系统优化调度全流程解析

I3C比I2C快10倍？RK3576实战：速率、DTS配置与混合总线避坑指南

字符串转对象：JSON.parse、new Function与URLSearchParams

本周精选

如何彻底离线使用 Laya-CoreML：Hugging Face 下载、缓存机制与 local_files_only 详解

基于1Panel 部署MySQL MCP 服务：TaoToken 统一 Key 接入与 config.toml 配置实战

崇州园区营销网站建设避坑指南：5大注意事项保备案安全

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？