1. 先搞清楚这个标题到底在说什么第一次看到一个人、九个月、20 万行代码、每个月烧掉 40 亿 token这组数字我的第一反应不是惊叹而是怀疑——这到底是在讲一个真实工程还是在讲一个被包装过的营销故事但把关键词摊开来看Harness、Agent、Claude Code、Obsidian、Markdown这几个词凑在一起指向的其实是一个非常具体的工程场景用 Agent 架构去驱动一个以 Markdown 为知识载体的应用并且把整个开发流程本身也交给 Agent 来加速。这里说的 Harness不是某个单一工具的名字而是一种架构思路——你可以把它理解成给 AI 套上一副缰绳和马具。模型本身是野马能力很强但方向不定Harness 就是那套约束系统负责把模型的输出接进真实的执行环境里让它能读文件、写文件、跑命令、调工具、拿反馈、再修正。Claude Code 就是这类 Harness 的一个典型代表它把模型能力封装成一个能在本地项目里干活的执行体。而 Obsidian 在这里扮演的是知识底座的角色Markdown 是它的数据格式整个应用的知识组织、文档流转、内容沉淀都建立在 Markdown 之上。所以这个标题真正在讲的事情是一个人用 Agent 驱动的开发方式在九个月里堆出了一个 20 万行代码量级的 Harness 架构应用而支撑这个开发强度的是每月 40 亿 token 的模型调用量。这个量级意味着什么意味着开发者的角色已经从写代码的人变成了设计约束、审阅产出、修正方向的人。代码的绝大部分不是手敲的而是在 Harness 的框架下由 Agent 生成、由人把关的。这篇文章我想拆的就是这件事背后的工程逻辑Harness 架构到底解决了什么问题为什么 Markdown 和 Obsidian 会成为这类应用的天然搭档40 亿 token 这个数字背后是怎样的调用结构以及一个独立开发者要复现类似路径需要迈过哪些具体的坎。不管你是刚接触 Agent 开发的新手还是已经在用 Claude Code 这类工具的老手我都会尽量把每一步的为什么讲清楚而不是只丢一堆结论。2. Harness 架构到底在解决什么问题2.1 裸模型和真实工程之间的那道鸿沟很多人对 Agent 的理解停留在给模型一个任务它就能自己完成。实际跑过就知道裸模型直接面对真实工程时问题一大堆。模型不知道你的项目结构不知道文件在哪不知道上一个命令的输出是什么更不知道它刚才的修改有没有把别的地方搞坏。它只能基于你给的那点上下文做一次性推理推理完就断了。Harness 要补的就是这条链路。它给模型提供了一套可执行的环境接口读文件、写文件、执行命令、搜索代码、查看报错、再基于结果继续推理。模型不再是一次性回答问题的嘴而是能动手、能看反馈、能迭代的手。这个转变是质变因为真实工程里的绝大多数任务都不是一次推理能搞定的而是做一步、看结果、再调整的循环。我自己的体会是判断一个 Agent 工具好不好用核心就看它的 Harness 做得扎不扎实。模型能力再强如果 Harness 只能让它读不能让它写或者写完不给它看执行结果那它就是个高级聊天框。反过来Harness 做得好哪怕模型能力中等也能在真实项目里干出像样的活。2.2 Harness 的三个核心能力层把 Harness 拆开看它至少包含三层能力缺一层都会让整个系统瘸腿。第一层是上下文管理。模型一次能看的 token 是有限的但一个 20 万行的项目根本塞不进去。Harness 必须能根据当前任务动态地把相关文件、相关历史、相关约束挑出来喂给模型。这一层做得好不好直接决定了模型是在盲人摸象还是有的放矢。常见的做法包括按文件路径检索、按符号引用追踪、按最近修改时间排序以及把项目级的约定比如代码风格、目录规范固化成一份始终注入的说明文件。第二层是工具执行与反馈闭环。模型决定要做什么之后Harness 负责真正去执行——跑测试、跑构建、调脚本、改文件——然后把执行结果成功、失败、报错信息、输出内容回传给模型。这个闭环的速度和准确性决定了 Agent 的迭代效率。如果每次执行都要等很久或者反馈信息残缺模型就会在错误的路上越走越远。第三层是约束与安全边界。Agent 能写文件、能跑命令就意味着它也能删文件、能跑危险命令。Harness 必须有一套边界机制哪些目录可写、哪些命令要二次确认、哪些操作要留痕。这一层在个人项目里容易被忽略但一旦项目规模上来没有边界就是灾难。2.3 为什么是 Harness 而不是别的架构市面上 Agent 架构的思路不止一种。有走多智能体协作路线的让一堆小 Agent 互相分工有走工作流编排路线的把任务拆成固定步骤串起来。Harness 架构的特别之处在于它把复杂度压在执行环境这一侧而不是压在任务编排那一侧。这个选择背后的逻辑很实在真实工程里的任务太发散了你很难提前把所有步骤编排好。与其花大力气设计一套万能的工作流不如把环境做得足够强让模型自己在环境里探索。模型负责想做什么Harness 负责让它能做、做完能看、看了能改。这种分工让系统对任务的适应性更强代价是对 Harness 本身的工程质量要求更高。从 20 万行代码这个量级反推如果走的是固定工作流路线光是维护那套编排逻辑就够呛更别说应对开发过程中不断变化的需求。Harness 路线把变化交给模型去消化人只需要维护好环境接口和约束规则这在单人开发场景下是更划算的。3. Markdown 和 Obsidian 为什么成了这套架构的底座3.1 Markdown 作为 Agent 的母语关键词里 Markdown 出现了一大串markdown 换行、markdown 语法、markdown 表格转换 excel、markdown 转 word 工作流、markdown 阅读器、markdown preview enhanced。这些词密集出现不是偶然它说明在这类应用里Markdown 不只是一种文档格式而是整个系统的数据交换层。原因很直接模型对 Markdown 的亲和度极高。你让模型输出结构化内容它天然就会用标题、列表、表格、代码块来组织。这些结构既是给人看的也是给程序解析的。一份 Markdown 文档人读起来清爽程序用正则或解析器拆起来也方便。相比之下JSON 对人不够友好纯文本又缺乏结构Markdown 刚好卡在中间那个甜点位上。在 Harness 架构里Markdown 还承担了一个额外角色Agent 的工作记录和指令载体。你可以把任务描述写成 Markdown把执行结果写成 Markdown把项目约定写成 Markdown模型读这些文件就像读自然语言一样顺畅不需要额外的格式转换。这种人机通用的特性是 Markdown 在这类系统里不可替代的根本原因。3.2 Obsidian 提供的知识组织能力单有 Markdown 文件还不够文件一多就会乱。Obsidian 的价值在于它给 Markdown 加了一层双向链接和知识图谱。每个笔记可以引用其他笔记引用关系可以被反向追踪整个知识库形成一个网状结构而不是树状结构。这对 Agent 应用来说意义重大。当模型需要理解一个概念时它不只看这一个文件还能顺着链接看到相关的上下文。这种顺着关系找信息的能力恰好补上了 Harness 上下文管理那一层的短板。你不需要手动告诉模型这个任务和哪些文件相关链接关系本身就提供了线索。Obsidian 的插件生态也是加分项。obsidian git 让知识库能版本化obsidian 插件推荐里那些增强编辑和预览的工具让 Markdown 的编写体验接近专业编辑器。对于要长期维护的知识库来说这些工程化的细节决定了它能不能撑住九个月甚至更久的高强度使用。3.3 从记笔记到喂 Agent的转变传统上 Obsidian 是给人做笔记用的但在这套架构里它的定位变了——它同时是人的知识库和 Agent 的上下文源。这个双重身份带来一个很实际的好处你为 Agent 整理的知识人自己也能用人自己积累的笔记Agent 也能直接读。不需要维护两套数据。我踩过的一个坑是早期我试图给 Agent 单独维护一套精简版上下文结果发现维护成本极高而且经常和真实文档不同步。后来改成直接用 Obsidian 库作为唯一数据源Agent 读的就是人读的虽然单次注入的 token 多了些但一致性带来的收益远大于那点成本。这个取舍在 40 亿 token 的月消耗量级下其实是划算的——多花的 token 换来了不用维护两套文档。4. 40 亿 token 一个月这个数字是怎么烧出来的4.1 拆解 token 消耗的四个来源40 亿 token 一个月平均下来每天一亿多。这个数字乍看吓人但拆开看就合理了。消耗主要来自四块消耗来源占比估算说明上下文注入约 40%每次调用都要把相关文件、约定、历史塞进去代码生成约 30%模型输出的代码、文档、配置迭代重试约 20%第一次没做对看反馈后重来探索性调用约 10%模型自己搜索、查看、确认信息上下文注入占大头这符合 Harness 架构的特点——为了让模型看得全每次调用都得喂大量背景。这也是为什么上下文管理做得好不好直接决定成本。如果检索不精准注入一堆无关内容token 就白烧了。4.2 为什么这个量级在单人开发里是合理的有人会问一个人一个月烧 40 亿 token是不是太夸张了换个角度算20 万行代码九个月平均每月两万多行。如果这些代码大部分由 Agent 生成每行代码平均消耗几千 token含上下文和迭代那一个月一亿多 token 是打底的。再加上文档、配置、测试、调试翻几倍很正常。关键在于这些 token 换回来的是什么。如果一个人手写 20 万行代码九个月根本不可能光是打字和调试的时间就不够。Agent 把写这个动作的成本压到了极低人只需要负责判断写得对不对。40 亿 token 买的不是代码本身而是把人的时间从重复劳动里解放出来。这个账在单人项目里算得过来因为人的时间才是最贵的。4.3 控制 token 成本的几个实操手段烧得多不代表可以乱烧。我在实际项目里总结了几个压成本的手段效果都挺明显。第一个是分层注入。不是每次调用都把整个项目塞进去而是按任务类型决定注入范围。改一个函数就只注入这个函数所在文件加它的直接依赖做架构调整才注入更大范围。这个分层规则要写进 Harness 的上下文管理逻辑里让它自动判断。第二个是缓存高频上下文。项目级的约定、目录结构、常用工具说明这些内容每次都要用但内容不变。把它们做成一份固定的系统提示缓存起来比每次重新拼装要省。有些模型接口支持上下文缓存用好了能省下可观的重复计算。第三个是限制迭代轮数。Agent 容易陷入改一点、看一点、再改一点的循环轮数一多 token 就爆。给每个任务设一个迭代上限超过就停下来让人介入比让它无限试错要省得多。我一般设 5 到 8 轮超过就说明任务描述有问题该人来重新拆解了。5. 一个人怎么撑起 20 万行代码的工程5.1 角色转变从写代码到设计约束单人做出 20 万行代码量级的项目前提是接受一个事实你不再是主要的生产者而是约束的设计者和产出的审阅者。这个转变说起来轻松做起来反直觉。手会痒看到 Agent 写得不对就想自己上手改一改就回到老路上了。正确的做法是把精力花在三件事上定义清楚任务边界这个模块要做什么、不做什么、设计好验收标准怎么判断做完了、做对了、维护好项目约定代码风格、目录规范、命名规则。这三件事做好了Agent 的产出质量会稳定在一个可接受的水平做不好就得不停地返工。我自己的经验是任务描述写得越具体Agent 一次做对的概率越高。与其写实现一个用户管理模块不如写实现一个用户管理模块包含增删改查四个接口数据存本地 JSON 文件接口命名遵循现有 user 模块的风格错误处理用项目统一的 Result 类型。后者多花五分钟写能省下半小时的返工。5.2 用 Markdown 管理任务和知识在 Obsidian 里我把项目拆成几类笔记需求笔记记录要做什么设计笔记记录怎么做任务笔记记录当前在做的具体事项复盘笔记记录踩过的坑和结论。这几类笔记之间用双向链接串起来形成一个可追溯的网络。Agent 干活时读的就是这些笔记。它读需求笔记知道目标读设计笔记知道约束读复盘笔记知道哪些坑不能再踩。这种知识前置的做法让 Agent 不需要每次从零理解项目大大降低了沟通成本。而且这些笔记是人写的质量比模型自己生成的上下文要高注入进去的每一 token 都更有价值。一个具体的技巧是给每类笔记定一个模板。需求笔记固定包含背景、目标、验收标准三段设计笔记固定包含方案、取舍理由、影响范围三段。模板化之后Agent 解析起来更稳定人写起来也更快不会漏掉关键信息。5.3 版本控制与回滚策略Agent 大量生成代码最大的风险是改坏了不知道。版本控制在这里不是可选项是必需品。obsidian git 管知识库的版本代码库用常规的 git 管两边都要有清晰的提交粒度。我的做法是每个 Agent 任务完成后强制提交一次提交信息里写清楚这个任务做了什么。这样一旦发现某次改动引入了问题可以精确定位到是哪次任务导致的回滚范围也小。如果攒着一起提交出了问题就得大海捞针。回滚策略上我倾向于小步快跑而不是大版本回退。发现某个改动有问题先看能不能局部修修不了再回退那一次提交。因为 Agent 的产出往往是相互依赖的大范围回退可能把好的改动也一起退掉了。保持提交粒度小回退的代价就低。6. 复现这条路径要迈过的几个坎6.1 环境搭建Claude Code 这类工具的落地细节关键词里 claude code 安装、claude code 下载、vscode 配置 claude code、vscode 安装 claude code 出现频率很高说明环境搭建是很多人的第一道坎。这类工具通常以命令行或编辑器插件的形式提供安装本身不复杂麻烦的是配置。配置的核心是把工具接进你的项目环境。要让它知道项目根目录在哪、用的是什么语言和框架、有哪些可用的命令。这些信息一般通过项目根目录下的配置文件来声明。配置文件写得好工具一进来就能干活写得含糊它就得反复问你效率大打折扣。还有一个容易忽略的点是权限边界。这类工具默认可能允许读写项目内文件、执行命令。在个人项目里问题不大但如果项目里有敏感配置或重要数据最好在配置里明确哪些目录可写、哪些命令需要确认。这个设置花不了几分钟但能避免很多意外。6.2 从零到第一个能跑的任务新手最容易犯的错是一上来就让 Agent 做大事。正确的路径是从最小的可验证任务开始。比如让它读一个文件、改一行内容、跑一次测试。这些任务能帮你确认工具装对了没、上下文注入对不对、执行反馈通不通。跑通最小任务之后再逐步加复杂度。先做单文件内的修改再做跨文件的修改最后做涉及多个模块的重构。每一步都确认上一歩稳定了再往下走。这个过程看起来慢但比一上来就搞大任务然后卡住要快得多。我自己的第一个任务是让 Agent 给一个已有函数加注释。它做对了我就知道基本链路是通的它做错了我能从错误里看出是上下文没给对还是执行没反馈。这种小任务是最好的调试手段。6.3 任务拆解的粒度控制Agent 能处理的任务粒度是有限的。太粗它抓不住重点太细你拆解的时间比它干活的时间还长。找到那个合适的粒度是单人用 Agent 开发的核心技能。我的经验法则是一个任务对应一次可独立验证的产出。比如实现登录接口是一个任务实现登录接口的参数校验是另一个任务。每个任务做完都能跑一次测试确认对错。这样任务之间边界清晰Agent 不容易跑偏出问题也好定位。粒度控制还和 token 成本挂钩。任务太粗Agent 需要注入大量上下文还容易在中间步骤迷失任务太细每次调用的固定开销系统提示、环境说明占比就高。在 40 亿 token 的量级下这个平衡点值得花时间找。6.4 常见报错与排查思路关键词里出现了 agent execution terminated due to error 这类报错词说明执行中断是常见问题。这类报错通常有几个来源上下文超限、工具调用失败、模型输出格式不符合预期、执行环境权限不足。排查的顺序建议是先看是不是上下文超了这是最常见的再看工具调用有没有报错然后看模型输出是不是被截断了最后查环境权限。这个顺序是从高频到低频排的能帮你快速定位。上下文超限的解决办法是精简注入内容或者把大任务拆小。工具调用失败要看具体是哪个工具、报什么错通常是路径不对或命令不存在。输出截断一般是模型输出长度限制需要把任务拆细或者调整输出配置。权限问题最直接看报错信息里提到哪个路径或命令去配置里放开就行。7. 这套打法适合谁不适合谁7.1 适合的场景特征这套 Harness 加 Agent 加 Markdown 知识库的打法最适合需求相对明确、但实现工作量巨大的项目。比如工具类应用、内容管理系统、数据处理管道这类逻辑清晰但代码量大Agent 能承担大部分实现工作。另一个适合的特征是知识密集但结构松散。如果项目涉及大量文档、规则、配置用 Obsidian 组织起来再让 Agent 读取能发挥出很大价值。Markdown 的通用性让知识既能被人消费也能被 Agent 消费一份投入两份收益。还有一点是开发者愿意接受角色转变。如果你享受手写代码的过程这套打法会让你难受如果你更关心项目能不能快速成型愿意把写代码的活交出去那这套打法会很顺手。这是个心态问题不是技术问题。7.2 不适合的场景与替代思路反过来需求高度不确定、需要频繁试错的项目不太适合这套打法。Agent 擅长执行明确的任务不擅长在模糊需求里探索方向。这种项目更适合人先想清楚再交给 Agent 实现。对性能极度敏感、需要精细调优的项目也要谨慎。Agent 生成的代码通常能跑但不一定跑得快。性能优化这种需要反复测量和微调的工作人来做效率更高。可以让 Agent 写初版人来优化关键路径。安全要求极高的项目同样要小心。Agent 生成的代码可能引入安全漏洞需要额外的审查环节。如果项目对安全有硬性要求要么加强审查要么把敏感部分留给人写。7.3 成本与收益的现实权衡最后说钱的事。40 亿 token 一个月按主流模型的定价成本不是小数目。这个投入值不值取决于项目本身的价值。如果项目能带来收入或者能省下雇人的成本那这笔投入是划算的。如果只是练手项目那就要控制规模别一上来就追求 20 万行。我的建议是从小规模验证开始。先用这套方法做一个小项目跑通全流程算清楚实际成本再决定要不要放大。很多人在没验证的情况下就投入大量资源结果发现方法不适合自己钱和时间都打了水漂。先小后大是控制风险最朴素也最有效的办法。这套打法的本质是把人的判断力和 Agent 的执行力结合起来。人负责想清楚要什么、判断做得对不对Agent 负责把想法变成代码。九个月 20 万行不是靠蛮力堆出来的是靠这套分工跑出来的。想清楚这个分工比纠结用哪个具体工具重要得多。
