1. 一个人九个月二十万行代码这件事到底在说什么先把标题里的数字拆开看。一个人意味着没有团队分工没有前后端联调没有产品经理帮你砍需求所有决策链路都压在一个人的工作记忆里。九个月大约是 270 天扣掉吃饭睡觉和必要的休息真正能高强度输出的时间大概在 1500 到 1800 小时之间。20 万行代码如果按 1800 小时算平均每小时要产出 110 行左右的代码而且这还没算调试、重构、写文档、查资料的时间。每个月烧掉 40 亿以上的 token这个量级说明整个开发过程高度依赖大模型辅助不是偶尔问几句而是把模型当成了日常开发的基础设施。这几个数字放在一起指向的不是“某个人很能写代码”而是一种新的开发范式以 Agent 为核心执行单元、以 Markdown 为知识载体、以 Harness 为调度骨架的应用开发方式。标题里的 Harness 架构应用是整件事的技术核心。Harness 在这里不是某个具体产品的名字而是一类架构思路的代称——它负责把模型能力、工具调用、上下文管理、任务编排这几件事串起来让一个 Agent 或者多个 Agent 能够稳定地完成复杂任务。我接触过不少独立开发者也看过很多“一个人做出某个产品”的案例。大部分案例的真相是作者本身有多年积累代码里有大量复用或者产品本身功能边界很窄。但 20 万行代码这个量级即便有大量复用也意味着这个应用的功能密度相当高。结合热搜词里的 Claude Code、Obsidian、Markdown、Agent 框架这些关键词可以合理推断这个应用大概率是一个面向知识工作者的 Agent 驱动型工具它把 Markdown 作为输入输出格式把 Obsidian 作为知识库或者前端界面把 Claude Code 这类命令行 Agent 作为执行引擎再用一层 Harness 架构把它们粘合起来。这篇文章想做的事情不是复述那个人的经历而是把这套开发方式拆开讲清楚三件事Harness 架构到底解决什么问题一个人怎么用 Agent 把开发效率拉到这个量级以及 Markdown 和 Obsidian 在这套体系里扮演什么角色。如果你是一个正在尝试用 AI 辅助开发的人或者你想理解 Agent 应用到底该怎么搭这篇内容应该能给你一些可以直接抄作业的思路。2. Harness 架构到底在解决什么问题2.1 从“模型很聪明”到“模型能干活”之间的鸿沟大模型的能力在过去两年提升很快但很多人用下来的感受是聊天很惊艳干活很拉胯。原因不在于模型不够聪明而在于模型缺少一个稳定的执行环境。你让模型写一段代码它能写你让它连续写二十个文件、每个文件之间还有依赖关系、写完还要跑测试、测试失败还要自己修它就开始丢三落四了。Harness 架构要解决的就是这个问题。你可以把它理解成给模型套了一个“工作台”。这个工作台负责几件事第一管理上下文决定每一轮对话里模型能看到什么信息第二管理工具决定模型能调用哪些外部能力比如读写文件、执行命令、搜索网页第三管理状态记录任务进行到哪一步、哪些已经完成、哪些失败了第四管理错误当模型输出不符合预期时决定是重试、回滚还是换一种策略。没有 Harness 的时候你相当于让一个很聪明的人蒙着眼睛在陌生城市里送快递他可能偶尔送对但大部分时候会迷路。有了 Harness你相当于给了他地图、导航、对讲机和一个可以随时查的订单列表。模型本身的智力没变但完成任务的稳定性会提升一个数量级。2.2 Harness 和普通 Agent 框架的区别市面上有很多 Agent 框架比如各种 ReAct 实现、各种多 Agent 协作库。它们和 Harness 架构的区别在于侧重点不同。普通 Agent 框架更关注“怎么让模型调用工具”Harness 更关注“怎么让模型在长时间、多步骤的任务里不跑偏”。举个例子。你让一个普通 Agent 帮你重构一个模块它可能会读文件、分析、改代码、跑测试。如果测试失败它可能会再改一次。但如果改了三轮还没成功它大概率会开始胡言乱语或者陷入死循环。Harness 架构会在这个流程里加入检查点每一轮修改后强制要求模型输出一个结构化的状态报告说明当前进度、遇到的问题、下一步计划。如果连续两轮状态没有实质进展Harness 会触发降级策略比如把任务拆得更细或者换一个更简单的子任务先做。这种设计思路本质上是从“让模型自由发挥”转向“给模型划定轨道”。轨道越清晰模型跑得越稳。代价是灵活性会降低但对于开发这类需要精确性的任务来说稳定性比灵活性重要得多。2.3 为什么一个人需要 Harness一个人开发 20 万行代码最大的瓶颈不是写代码的速度而是上下文切换的成本。你今天写前端明天写后端后天调数据库大后天修 bug。每次切换都要重新加载相关知识这个成本非常高。Harness 架构的价值在于它可以把不同领域的任务封装成不同的 Agent 或者不同的工作流你只需要在高层做决策具体的执行细节交给 Agent 去处理。比如你要给应用加一个导出 Markdown 表格到 Excel 的功能。在传统开发模式下你需要查 Excel 的库怎么用、查 Markdown 表格的解析规则、写转换逻辑、写测试、处理边界情况。在 Harness 模式下你只需要描述清楚需求Harness 会调度一个专门处理表格转换的 Agent 去完成你只需要在最后验收。这个 Agent 可能已经处理过几十个类似的表格转换任务它的上下文里已经积累了大量相关经验。这就是为什么一个人能产出 20 万行代码。不是他打字快而是他把大量重复性的、需要查资料的、需要试错的工作外包给了 Agent。他自己只做那些真正需要人类判断的决策。3. Markdown 和 Obsidian 在这套体系里的位置3.1 Markdown 为什么成了 Agent 时代的通用语言Markdown 在这套体系里的角色类似于 HTTP 在互联网里的角色。它足够简单简单到模型可以稳定地生成和解析它又足够表达力强强到可以承载结构化信息。你让模型输出 JSON它可能会漏括号你让它输出 YAML它可能会缩进错误但你让它输出 Markdown它几乎不会犯格式错误。更重要的是Markdown 天然适合作为人和 Agent 之间的接口。你可以用 Markdown 写需求文档Agent 读完之后直接开始干活。Agent 干完活之后也可以用 Markdown 输出报告你读起来毫无障碍。这种双向的可读性是 JSON 或者代码格式做不到的。热搜词里出现了“markdown换行”“markdown语法”“markdown表格转换excel”“markdown表格复制”“markdown 数学符号”这些词说明大量用户正在把 Markdown 当作日常工作的核心格式。这不是偶然。当你的工作流里有了 Agent 之后你会发现自己越来越依赖 Markdown因为它是唯一一种人和机器都能轻松读写的格式。3.2 Obsidian 作为知识库和前端的双重角色Obsidian 在这套体系里扮演两个角色。第一个角色是知识库。你所有的笔记、文档、需求描述、会议记录都以 Markdown 文件的形式存在 Obsidian 的 vault 里。Agent 可以通过文件系统直接读取这些内容不需要额外的 API 或者数据库。第二个角色是前端界面。Obsidian 的插件体系允许你用 Markdown 渲染出复杂的交互界面这意味着你可以把 Agent 的输出直接展示在 Obsidian 里而不需要单独写一个 Web 前端。热搜词里有“obsidian插件推荐”“obsidian教程”“obsidian创建项目管理台账”“codex obsidian”“weknora和obsidian”这些词说明已经有不少人在探索 Obsidian 和 Agent 的结合方式。一个典型的用法是在 Obsidian 里创建一个项目台账每一行是一个任务任务描述用 Markdown 写。Agent 读取这个台账自动领取任务、执行、更新状态。你打开 Obsidian 就能看到所有任务的进度不需要切换到其他工具。这种用法的好处是极低的前端开发成本。你不需要写 React 组件不需要调 CSS不需要处理路由。Obsidian 已经帮你把渲染、编辑、搜索、链接这些基础能力都做好了。你只需要定义好 Markdown 的格式约定剩下的交给 Obsidian 和 Agent。3.3 Claude Code 作为执行引擎的定位Claude Code 在这套体系里是执行引擎。它提供了命令行环境下的 Agent 能力可以读写文件、执行命令、调用工具。热搜词里有“claude code安装”“claude code使用”“vscode配置claude code”“vscode安装claude code”“claude code下载”这些词说明它的安装和配置是很多人的第一道门槛。Claude Code 的核心优势是它离文件系统足够近。你可以让它直接操作你的项目目录读代码、改代码、跑测试。它不需要你先把代码上传到某个平台也不需要你通过 API 传输大量数据。这种本地优先的设计对于处理大型项目来说非常重要因为大项目的代码量往往超出模型上下文窗口的限制必须依赖文件系统来做增量读取。把 Claude Code 和 Obsidian 结合起来就形成了一个很自然的开发闭环你在 Obsidian 里写需求和任务Claude Code 读取这些 Markdown 文件并执行执行结果写回 Obsidian你在 Obsidian 里验收。整个流程不需要离开你熟悉的编辑器。4. 一个人怎么把开发效率拉到这个量级4.1 任务拆解的粒度控制一个人用 Agent 开发最容易犯的错误是任务拆得太粗。你给 Agent 一个“实现用户登录功能”的任务它大概率会给你一个能跑但漏洞百出的实现。正确的做法是把任务拆到单个文件、单个函数、单个测试用例的粒度。比如“实现用户登录功能”应该拆成定义用户数据模型、写密码哈希函数、写登录接口、写登录接口的单元测试、写登录失败的错误处理、写登录成功的会话管理。每一个子任务都足够小小到 Agent 可以在一次交互里完成小到你可以在一次交互里验收。这种拆解方式的好处是错误隔离。如果登录接口的测试失败了你知道问题出在那个子任务上不会影响其他已经完成的部分。如果你把整个登录功能当成一个任务测试失败的时候你根本不知道是哪一行代码出了问题。4.2 上下文管理的具体做法Agent 的上下文窗口是有限的。20 万行代码的项目不可能把所有代码都塞进上下文。你需要一套上下文管理策略决定每一轮对话里 Agent 能看到什么。我的做法是三层结构。第一层是全局上下文包括项目结构说明、核心约定、常用命令。这部分内容很少变可以放在一个固定的 Markdown 文件里每次对话开始时加载。第二层是任务上下文包括当前任务的描述、相关文件的路径、上次执行的输出。这部分内容随任务变化由 Harness 动态组装。第三层是即时上下文包括 Agent 刚刚读过的文件内容、刚刚执行的命令输出。这部分内容只在当前轮次有效下一轮会被新的内容替换。这种分层的好处是上下文利用率高。全局上下文只加载一次任务上下文只加载相关部分即时上下文用完就丢。Agent 的注意力始终集中在当前需要处理的信息上不会被无关内容干扰。4.3 错误处理和重试策略Agent 执行任务失败是常态不是异常。你需要一套错误处理和重试策略决定失败之后怎么办。最简单的策略是原样重试。Agent 失败了把同样的输入再给它一次。这种策略适用于偶发性的错误比如网络超时、临时性的工具故障。但如果失败是系统性的比如 Agent 理解错了需求原样重试只会浪费 token。更有效的策略是降级重试。第一次失败后把任务拆得更细或者换一种更明确的描述方式。比如 Agent 写一个函数失败了你可以把任务改成“先写函数的签名和注释不要写实现”等签名确认后再写实现。这种分步走的策略成功率会高很多。还有一种策略是换 Agent 重试。不同的 Agent 可能有不同的擅长领域。一个 Agent 写 Python 写得好另一个 Agent 写前端写得好。Harness 可以根据任务类型把失败的任务转给更合适的 Agent。4.4 验收环节的设计Agent 干完活之后你需要验收。验收不是简单地看一眼代码而是要有可执行的验收标准。比如单元测试是否通过、类型检查是否通过、代码风格是否符合规范、性能是否达标。我的做法是给每个任务定义一个验收清单用 Markdown 的 checkbox 格式写在任务描述里。Agent 执行完之后Harness 自动运行验收清单里的检查项把结果写回任务描述。你打开 Obsidian 就能看到哪些任务已经通过验收哪些还需要人工介入。这种设计的好处是验收成本极低。你不需要逐行读代码只需要看验收清单的结果。只有验收失败的任务才需要你仔细看大部分任务都可以自动通过。5. 实操过程中会遇到的坑和排查方法5.1 Agent 执行中断的常见原因热搜词里有“agent execution terminated due to error”和“harness failed to load plugins”说明执行中断和插件加载失败是高频问题。执行中断的原因通常有几类上下文超限、工具调用失败、模型输出格式错误、任务超时。上下文超限是最常见的。Agent 在处理大文件或者长对话时很容易把上下文塞满。解决办法是主动截断在 Harness 层面设置一个阈值当上下文使用量超过 80% 时自动丢弃最早的即时上下文只保留全局上下文和任务上下文。工具调用失败通常是权限问题或者路径问题。比如 Agent 想写一个文件但目标目录不存在或者没有写权限。解决办法是在 Harness 层面做预检查在执行工具调用之前先验证路径是否存在、权限是否足够。模型输出格式错误通常是因为提示词不够明确。比如你要求 Agent 输出 JSON但没有给出 schema它可能会输出一个格式不对的 JSON。解决办法是给出明确的格式示例让 Agent 照着抄。5.2 Markdown 格式问题的处理Markdown 虽然简单但在 Agent 场景下还是会有一些格式问题。比如表格的列对齐、代码块的嵌套、数学符号的转义。热搜词里的“markdown表格转换excel”“markdown表格复制”“markdown 数学符号”都指向这类问题。表格转换 Excel 的常见需求是把 Markdown 表格解析成二维数组再写入 Excel。这个过程中最容易出问题的是单元格内有换行或者竖线。Markdown 表格用竖线分隔列如果单元格内容里也有竖线解析就会出错。解决办法是在生成表格时把单元格内的竖线转义成\|或者在解析时用更复杂的规则处理。数学符号的问题通常出现在 Obsidian 里。Obsidian 用$包裹行内公式用$$包裹块级公式。如果 Agent 生成的 Markdown 里$符号没有正确配对渲染就会出错。解决办法是在 Harness 层面做格式校验检查$的数量是否为偶数$$是否成对出现。5.3 Obsidian 插件冲突的排查Obsidian 的插件生态很丰富但插件之间可能会有冲突。热搜词里的“harness failed to load plugins”可能就和插件冲突有关。常见的冲突表现是某个插件加载失败、Obsidian 启动变慢、某些功能突然不可用。排查插件冲突的步骤是先禁用所有第三方插件只保留核心插件看问题是否还存在。如果问题消失再逐个启用插件直到问题复现。复现时最后启用的那个插件就是冲突源。然后你可以选择禁用那个插件或者找替代方案。另一个常见问题是插件版本不兼容。Obsidian 本身会更新插件也需要跟着更新。如果某个插件长期不更新可能会在新版 Obsidian 上出问题。解决办法是定期检查插件更新或者锁定 Obsidian 的版本等插件更新后再升级。5.4 Token 消耗的优化每个月 40 亿 token 的消耗量成本不低。优化 token 消耗的核心思路是减少无效上下文。具体做法包括压缩全局上下文只保留最必要的信息复用任务上下文相似任务共享上下文缓存工具调用结果避免重复调用。还有一个技巧是用更小的模型处理简单任务。不是所有任务都需要最强的模型。格式转换、文件读写、简单查询这类任务用中等模型就够了。只有复杂的推理和代码生成才需要最强模型。Harness 可以根据任务类型自动选择模型这样能省下不少 token。6. 这套开发方式的适用边界和扩展方向6.1 什么类型的项目适合这套方式这套开发方式最适合功能边界清晰、模块化程度高、以文本处理为主的项目。比如知识管理工具、文档转换工具、数据清洗工具、自动化脚本集合。这些项目的共同特点是输入输出都是文本模块之间耦合度低单个模块的逻辑不复杂。不太适合的是强交互、强实时、强图形的项目。比如游戏、视频编辑、实时通信。这些项目对性能和用户体验的要求很高Agent 生成的代码往往需要大量人工优化效率优势不明显。还有一个边界是项目规模。这套方式在中小型项目上效率提升最明显。项目太大之后上下文管理的复杂度会指数级上升Agent 之间的协调成本也会增加。20 万行代码可能已经接近这套方式的效率上限。6.2 从单 Agent 到多 Agent 的演进单 Agent 能处理的任务是有限的。当任务复杂度超过一定阈值就需要多 Agent 协作。多 Agent 的核心问题是通信和协调。Agent 之间怎么传递信息、怎么避免冲突、怎么保证一致性这些都需要在 Harness 层面设计好。一个常见的多 Agent 架构是主管- worker 模式。一个主管 Agent 负责拆解任务、分配任务、验收结果。多个 worker Agent 负责执行具体任务。主管 Agent 不直接干活只做调度。这种模式的好处是职责清晰主管 Agent 的上下文可以保持得很干净不会被具体任务的细节污染。另一个模式是流水线模式。任务被拆成多个阶段每个阶段由一个专门的 Agent 负责。比如需求分析 Agent、代码生成 Agent、测试 Agent、文档 Agent。这种模式适合流程固定的项目每个 Agent 只需要关注自己那一阶段。6.3 知识沉淀和复用一个人开发 20 万行代码如果不做知识沉淀后面会越来越吃力。知识沉淀的核心是把重复出现的问题和解决方案记录下来形成可复用的模式。我的做法是在 Obsidian 里建一个“模式库”每个模式是一个 Markdown 文件包含问题描述、解决方案、代码示例、注意事项。当 Agent 遇到类似问题时Harness 会先搜索模式库如果有匹配的模式直接把模式内容作为上下文提供给 Agent。这样 Agent 不需要从零开始推理直接套用现成的模式就行。模式库的另一个好处是降低对模型的依赖。模式库越丰富Agent 需要推理的内容就越少token 消耗就越低执行速度也越快。长期来看模式库是这套开发方式里最有价值的资产。6.4 后续可以扩展的方向这套体系还有很大的扩展空间。一个方向是自动化测试的深度集成。目前大部分 Agent 只能跑现成的测试不能自己生成测试用例。如果能让 Agent 根据代码自动生成测试用例验收环节的覆盖率会大幅提升。另一个方向是跨项目的知识迁移。目前模式库是项目内部的如果能把多个项目的模式库打通形成一个跨项目的知识网络Agent 的能力会更强。这需要一套统一的模式描述格式和检索机制。还有一个方向是人机协作的界面优化。目前大部分交互还是通过命令行或者 Obsidian 完成的。如果能做一个更直观的界面让非技术用户也能用这套体系来管理自己的知识工作受众会广很多。7. 一些实操心得和踩坑记录7.1 不要试图让 Agent 一次做太多我刚开始用 Agent 的时候总想让它一次完成一个大功能。结果就是它写了五百行代码跑测试失败然后开始胡乱修改最后把整个文件搞成一团乱麻。后来我学乖了每次只让它做一件事做完验收验收通过再继续。虽然看起来步骤多了但总体效率反而更高因为返工少了。7.2 提示词里要写清楚“不要做什么”Agent 有一个倾向它会做你让它做的事也会做你没让它做的事。比如你让它写一个函数它可能会顺便帮你重构一下周围的代码或者改一下 import 顺序。这些改动有时候是好的有时候会引入 bug。我的做法是在提示词里明确写清楚“只修改这个文件”“不要动其他文件”“不要改 import”。约束越明确Agent 的行为越可控。7.3 定期清理上下文和缓存Agent 的上下文和缓存会随着时间积累变得越来越大。如果不定期清理执行速度会变慢token 消耗也会增加。我的做法是每天结束工作前清理一次即时上下文和工具调用缓存。每周清理一次任务上下文只保留还在进行中的任务。每月清理一次全局上下文把不再适用的约定删掉。7.4 备份比什么都重要Agent 改代码的速度很快快到你可能来不及反应。如果它改错了而你没有备份恢复起来会很麻烦。我的做法是每次让 Agent 执行任务之前先用 git 提交一次当前状态。这样即使 Agent 改错了你也可以一键回滚。这个习惯看起来简单但能省下大量时间。7.5 不要完全信任 Agent 的输出Agent 的输出看起来往往很合理但合理不等于正确。我遇到过好几次 Agent 生成的代码逻辑上说得通但实际跑起来就是不对。原因可能是它理解错了某个 API 的用法或者忽略了某个边界条件。所以验收环节一定要有可执行的检查不能只靠肉眼读代码。7.6 把常用的命令和配置写成脚本Agent 执行任务时经常需要运行一些固定的命令比如跑测试、格式化代码、检查类型。这些命令如果每次都让 Agent 自己拼容易出错。我的做法是把这些命令写成脚本放在项目根目录下Agent 只需要调用脚本就行。这样既减少了出错概率也减少了 token 消耗。7.7 记录每次失败的原因Agent 失败的时候不要只是重试要把失败原因记下来。我建了一个“失败日志”的 Markdown 文件每次失败都记一笔任务描述、失败表现、可能原因、解决办法。积累一段时间后你会发现很多失败是重复的。针对这些重复失败你可以在 Harness 层面做预防比如加一个预检查或者调整提示词模板。7.8 保持对项目的整体掌控用 Agent 开发最大的风险是失去对项目的整体掌控。你让 Agent 改了几十个文件过了一段时间你打开项目发现已经看不懂了。为了避免这种情况我坚持做两件事第一每天花半小时读一遍当天 Agent 改动的代码确保自己理解每一处改动第二每周画一次项目结构图确保自己对模块之间的关系有清晰的认知。这两件事看起来费时间但能保证你在关键时刻还能做出正确的架构决策。7.9 工具选型不要追新Agent 生态变化很快几乎每周都有新工具出来。但工具选型不要追新要追稳。我目前用的工具链是Claude Code 作为执行引擎Obsidian 作为知识库和前端Markdown 作为通用格式Harness 层是自己写的一套轻量调度逻辑。这套组合用了几个月稳定性很好。新工具我会关注但不会轻易替换掉正在用的工具除非新工具能解决一个我当前确实遇到的痛点。7.10 给自己留出不用 Agent 的时间最后一条心得可能有点反直觉不要把所有时间都花在 Agent 上。我每天会留出一到两个小时关掉 Agent自己读代码、写文档、思考架构。这段时间的效率看起来比用 Agent 低但它能帮我保持对项目的直觉。Agent 可以帮你写代码但不能帮你做判断。判断力需要你自己花时间去养。