1. 先搞清楚这个项目到底在做什么一个人九个月20 万行代码每个月消耗 40 亿以上的 token最终交付的是一款基于 Harness 架构的应用。这几个数字摆在一起任何一个写过代码的人第一反应都是这不可能是一个人干的。但如果你真的深入用过 Claude Code 这类 AI 编程工具并且理解 Harness 架构的设计哲学你会发现这个数字组合其实有它内在的合理性。我先把这个项目的核心概念拆开讲清楚。所谓 Harness 架构本质上是一种以 AI Agent 为执行核心、以 Markdown 作为知识载体、以 Obsidian 作为知识管理前端、以 Claude Code 作为代码生成引擎的应用架构模式。它不是一个传统意义上的软件框架更像是一套“人机协作工作流”的工程化封装。你给它一个任务描述它通过 Agent 调度、上下文注入、工具调用、结果校验这几个环节把原本需要多人协作完成的工作压缩到一个人加一套工具链上。这个项目解决的核心问题是如何让一个人具备一支工程团队的产出能力。它适合那些有明确产品方向、但缺乏足够人力预算的独立开发者也适合想理解 AI Agent 工程化落地路径的技术管理者。你不需要是 AI 专家但你得愿意花时间理解 Agent 的工作机制、Markdown 的组织方式、以及 Claude Code 这类工具的能力边界。我之所以对这个项目感兴趣是因为它触及了一个很实际的问题当 token 成本降到每个月几百块钱就能烧掉 40 亿的量级时一个人的产出瓶颈到底在哪里是写代码的速度还是思考架构的深度这个项目给出的答案是——瓶颈在于你如何组织知识、如何设计 Agent 的协作流程、如何让 Markdown 成为你和 AI 之间的“合同”。2. 为什么选 Harness 架构而不是传统开发模式2.1 传统开发模式在单人场景下的三个死穴我试过用传统方式一个人写完整项目踩过的坑很集中。第一个死穴是上下文切换成本。你写完后端写前端写完前端调数据库调完数据库改配置每次切换都要重新加载一遍脑子里的状态。一个人一天能真正高效工作的时间扣除这些切换损耗可能只剩三四个小时。第二个死穴是知识遗忘。你今天想清楚了一个模块的设计逻辑三天后回来改 bug已经忘了当时为什么这么设计。没有团队里的文档沉淀机制知识全在脑子里脑子又不可靠。第三个死穴是质量校验缺失。团队里有 code review一个人写代码没人给你 review错误会一直累积到运行时报错才暴露。这三个问题叠加起来就是为什么一个人做大型项目几乎不可能。Harness 架构针对性地解决了这三个问题。Agent 负责上下文切换你只需要描述任务它自己去调度工具Markdown 负责知识沉淀所有设计决策、接口定义、业务逻辑都写在 Markdown 文件里Agent 每次执行前先读这些文件Claude Code 负责质量校验它生成的代码本身带有一定的自检逻辑而且你可以要求它对关键模块写测试。2.2 Harness 架构的核心组件拆解这个项目的 Harness 架构由四个核心组件构成我用一个表格把它们的关系说清楚组件角色具体工具核心职责知识层大脑Obsidian Markdown存储设计文档、接口定义、业务规则执行层手脚Claude Code Agent读取知识层内容生成代码执行任务调度层神经Harness 框架管理 Agent 生命周期注入上下文校验结果反馈层感官日志 测试 人工确认收集执行结果回写知识层触发下一轮迭代知识层用 Obsidian 是有讲究的。Obsidian 的双向链接机制让 Markdown 文件之间形成网状结构Agent 在读取一个文件时可以顺着链接找到关联的设计文档。这比传统的文件夹层级结构更接近人类联想记忆的方式。比如你写了一个用户认证模块的设计文档里面链接了数据库表结构文档和 API 接口文档Agent 在执行认证模块开发任务时会自动把这些关联文档一起读进来作为上下文。执行层的 Claude Code 负责实际的代码生成。我实测下来Claude Code 在处理有明确接口定义的模块时一次生成可用代码的概率大概在七成左右。剩下的三成需要你补充边界条件或者修正业务逻辑理解偏差。这个比例听起来不高但考虑到它生成的是完整模块而不是代码片段效率提升仍然是数量级的。调度层的 Harness 框架是这个项目最核心的工程化部分。它要解决的是什么时候启动 Agent、给 Agent 喂什么上下文、Agent 执行失败后怎么重试、执行结果怎么回写。这些逻辑如果全靠人工操作那 token 消耗量再大也堆不出 20 万行代码。2.3 为什么 Markdown 是整个架构的基石很多人低估了 Markdown 在这个架构里的地位。它不只是写文档的工具它是人和 Agent 之间的契约格式。你用 Markdown 写清楚一个模块的输入输出、边界条件、异常处理Agent 就能按照这个契约生成代码。你写得越精确Agent 生成的结果越接近你的预期。Markdown 的表格语法在这里特别有用。我用它来定义数据表结构、API 参数、状态码映射Agent 解析表格的能力很强基本不会出错。数学公式用 LaTeX 语法写在 Markdown 里Agent 也能正确理解。甚至换行这种细节都有影响——Markdown 里两个空格加换行才是硬换行这个规则在写 Agent 指令时要特别注意否则你的指令会被合并成一行导致 Agent 理解偏差。Obsidian 的插件生态让 Markdown 的能力进一步扩展。比如 Markdown Preview Enhanced 插件可以渲染数学公式和流程图Dataview 插件可以把 Markdown 文件当成数据库来查询。这些能力在 Agent 调度时非常有用你可以让 Agent 先查询某个标签下的所有任务文档再按优先级依次执行。3. 20 万行代码是怎么被“烧”出来的3.1 Token 消耗的构成分析每个月 40 亿 token这个数字乍看很吓人但拆开来看就合理了。我根据这个项目的描述和常见实践把 token 消耗拆成几个部分上下文注入每次 Agent 执行任务前需要把相关的 Markdown 文档、代码文件、历史对话读入上下文。这部分占总消耗的 40% 左右。一个中等复杂度的模块上下文可能就有几万 token。代码生成Agent 实际生成代码的输出 token占总消耗的 25% 左右。生成 20 万行代码按平均每行 10 个 token 算就是 2000 万 token九个月分摊下来每个月 200 多万看起来不多但实际生成过程中会有大量重试和修正。结果校验Agent 生成代码后需要自我检查或者调用测试工具验证这部分消耗占 20%。校验逻辑本身也要写代码也要消耗 token。知识回写每次任务完成后Agent 要把执行结果、遇到的问题、解决方案回写到 Markdown 文档里这部分占 15%。这样算下来40 亿 token 分摊到九个月每个月大约 4.4 亿每天大约 1500 万 token。如果按 Claude 的定价这个量级的成本确实不低但相比雇一个工程师团队仍然是划算的。3.2 代码生成的实际流程我拿这个项目里一个典型的模块开发流程来举例让你看清楚 20 万行代码是怎么一步步堆出来的。假设你要开发一个“用户权限管理”模块。传统方式下你需要自己设计数据库表、写 API 接口、写业务逻辑、写测试。在 Harness 架构下流程是这样的第一步你在 Obsidian 里创建一个 Markdown 文档描述这个模块的需求。文档里包含功能列表、数据表结构用 Markdown 表格、API 接口定义用代码块写 JSON schema、边界条件、异常处理规则。第二步你给 Harness 框架发一个指令“根据权限管理.md生成后端代码”。Harness 框架读取这个 Markdown 文件同时顺着文档里的链接读取关联的数据库配置文档和项目结构文档把这些内容组装成上下文发给 Claude Code。第三步Claude Code 根据上下文生成代码文件。它可能会生成permission_service.py、permission_model.py、permission_api.py这几个文件。生成过程中它会自己检查代码语法如果发现明显错误会重试。第四步Harness 框架把生成的代码写入项目目录然后触发测试流程。如果测试通过Agent 会把执行结果回写到 Markdown 文档里标记这个模块已完成。如果测试失败Agent 会读取错误日志尝试修复修复不了就把问题记录到文档里等你人工介入。这个流程跑一轮消耗的 token 量大概在 50 万到 100 万之间。一个中等复杂度的模块可能需要跑三五轮才能完全通过。20 万行代码大概对应 200 到 300 个这样的模块九个月时间平均每天完成一个模块左右。这个节奏对于一个有经验的开发者来说是合理的。3.3 代码质量的保障机制一个人写 20 万行代码最大的风险是质量失控。这个项目用了三层保障机制第一层是Markdown 契约。Agent 生成的代码必须符合 Markdown 文档里定义的接口规范不符合就重试。这相当于把 code review 前置到了设计阶段。第二层是自动化测试。每个模块生成后自动跑单元测试测试用例也是 Agent 根据 Markdown 文档里的边界条件生成的。测试不通过就不允许合并。第三层是人工抽检。你不可能检查每一行代码但可以定期抽检关键模块。我建议把抽检重点放在涉及资金、权限、数据一致性的模块上这些地方出错代价最大。注意Agent 生成的测试用例往往偏向“正常路径”对异常路径的覆盖不够。你需要手动补充一些极端情况的测试比如空输入、超长字符串、并发冲突等。4. 实操中踩过的坑和解决方案4.1 Agent 执行失败的常见原因Agent 执行失败是这个项目里最常遇到的问题。我整理了几种典型情况失败现象根本原因解决方案Agent 执行到一半终止上下文超长超出模型窗口限制拆分任务减少单次注入的文档数量生成的代码不符合接口定义Markdown 文档描述有歧义用更精确的 schema 定义接口避免自然语言模糊描述Agent 反复重试同一错误错误信息没有正确反馈给 Agent检查 Harness 框架的错误捕获逻辑确保错误日志被完整传入下一轮插件加载失败Obsidian 插件版本与 Harness 框架不兼容锁定插件版本在项目文档里记录兼容版本号Agent 调用本地模型失败本地模型服务未启动或端口配置错误检查 LM Studio 等服务是否运行确认 API 地址和密钥配置我印象最深的一次是 Agent 在执行一个数据库迁移任务时反复失败查了半天发现是 Markdown 文档里写了一个错误的字段类型Agent 严格按照文档生成代码结果数据库报错。这件事让我意识到Markdown 文档的准确性直接决定 Agent 的执行成功率。你写错一个字段Agent 就会错一路。4.2 Token 消耗的优化技巧40 亿 token 不是小数目优化空间很大。我总结了几个实用的降耗技巧技巧一上下文分层注入。不要每次都把整个项目的文档塞给 Agent。把文档分成“全局层”项目结构、技术栈、编码规范和“模块层”当前模块的设计文档。全局层只在会话开始时注入一次模块层按需注入。这样能省掉大量重复的上下文 token。技巧二用摘要代替全文。对于历史对话和已完成模块的文档不要全文注入让 Agent 先读摘要需要细节时再读全文。Obsidian 的 Dataview 插件可以帮你自动生成摘要。技巧三批量执行相似任务。如果有多个模块的结构类似可以合并成一个任务让 Agent 批量生成。这样上下文只需要注入一次生成多个模块的代码。但要注意批量任务出错时排查难度更大建议只对简单模块用这招。技巧四设置 token 预算上限。在 Harness 框架里给每个任务设置 token 消耗上限超过就暂停等你确认后再继续。这能防止某个任务失控烧掉大量 token。4.3 Obsidian 与 Claude Code 的协作细节Obsidian 和 Claude Code 的协作是这个项目里最需要调优的部分。我试过几种方案最后稳定下来的做法是Obsidian 负责知识管理所有设计文档、任务列表、执行日志都放在 Obsidian 的 vault 里。Claude Code 通过文件系统直接读取这些 Markdown 文件。Harness 框架在中间做调度它监听 Obsidian 里的任务状态变化当某个任务被标记为“待执行”时自动触发 Claude Code 执行。这里有个细节要注意Obsidian 的 Markdown 文件里可能包含一些 Obsidian 特有的语法比如[[双向链接]]、![[嵌入文件]]、dataview查询块。Claude Code 在读取这些文件时需要先做一次语法转换把 Obsidian 特有语法转成标准 Markdown 或者纯文本。否则 Agent 可能会把[[链接]]当成代码的一部分导致理解错误。我的做法是在 Harness 框架里加一个预处理步骤用正则表达式把 Obsidian 特有语法替换掉。比如[[文档名]]替换成文档名![[嵌入文件]]替换成嵌入文件的内容。这个预处理逻辑不复杂但能显著提升 Agent 的理解准确率。5. 一个人如何管理 20 万行代码的项目5.1 项目结构的组织方式一个人管理 20 万行代码项目结构必须极度清晰。这个项目采用的结构是“按功能模块划分按层次组织”project/ ├── docs/ # Obsidian vault 目录 │ ├── 00-项目总览.md │ ├── 01-技术栈.md │ ├── 02-编码规范.md │ ├── modules/ # 各模块设计文档 │ │ ├── 用户认证.md │ │ ├── 权限管理.md │ │ └── 数据同步.md │ └── logs/ # 执行日志 ├── src/ # 源代码 │ ├── core/ # 核心框架代码 │ ├── modules/ # 业务模块代码 │ └── utils/ # 工具函数 ├── tests/ # 测试代码 └── harness/ # Harness 框架配置这个结构的关键在于docs/目录和src/目录的对应关系。每个模块的设计文档在docs/modules/下对应的代码在src/modules/下测试在tests/下。Agent 在执行任务时能通过命名约定快速找到关联文件。5.2 任务拆解与优先级管理20 万行代码不可能一口气写完必须拆成可执行的小任务。这个项目的任务拆解粒度是“一个 Agent 会话能完成的任务”大概对应 200 到 500 行代码。拆得太细调度开销大拆得太粗Agent 容易跑偏。任务优先级用 Markdown 的标签系统管理。在 Obsidian 里给每个任务文档打上#优先级/高、#优先级/中、#优先级/低标签Harness 框架按标签顺序依次执行。高优先级任务是那些阻塞其他模块开发的基础设施比如数据库连接、认证中间件、日志系统。这些必须先做不然后续模块没法开发。我个人的经验是先把核心数据流打通再扩展功能模块。比如先做用户认证和数据存储再做业务逻辑最后做界面和报表。这样每个阶段都有可运行的产物方便验证架构设计是否合理。5.3 版本控制与回滚策略一个人用 Agent 生成代码版本控制特别重要。因为你不可能记住每次 Agent 改了什么出问题时需要快速回滚。这个项目用 Git 做版本控制但提交策略和传统开发不同每个 Agent 任务完成后自动提交一次提交信息包含任务 ID 和简要描述。每天结束时打一个 tag方便按天回滚。关键模块的每次修改都单独提交不和其他模块混在一起。回滚策略是如果某个模块的测试突然不通过了先回滚到上一个通过的提交然后对比差异找出是哪次修改引入的问题。因为每次提交粒度很小定位问题很快。提示Agent 生成的代码提交前建议先跑一遍格式化工具如 Black、Prettier保证代码风格一致。否则 Agent 每次生成的风格可能略有差异累积起来会让代码库变得混乱。6. 这套架构的适用边界和扩展方向6.1 什么场景适合用 Harness 架构Harness 架构不是万能的。我实测下来它最适合的场景是需求相对明确、模块化程度高、有大量重复性代码的项目。比如后台管理系统、数据管道、API 服务、自动化工具。这些项目的共同特点是模块之间的耦合度低接口定义清晰Agent 容易理解任务边界。不适合的场景也很明显需求频繁变动、强交互体验、算法创新为主的项目。比如前端界面开发Agent 生成的界面代码往往需要大量调整才能达到设计效果再比如机器学习模型调优这部分需要人的直觉和经验Agent 帮不上太多忙。6.2 从 20 万行到更大规模的扩展思路如果你想把这套架构扩展到更大的项目比如 50 万行甚至 100 万行需要解决几个新问题问题一上下文窗口不够用。项目越大Agent 需要的上下文越多但模型的上下文窗口是有限的。解决方案是建立更精细的上下文索引让 Agent 通过关键词检索而不是全文注入来获取信息。Obsidian 的搜索功能和 Dataview 插件可以帮上忙。问题二模块间依赖变复杂。小项目里模块依赖简单大项目里依赖关系可能形成网状结构。需要在 Markdown 文档里显式定义依赖关系Harness 框架在执行任务前先检查依赖是否满足。问题三质量一致性难保证。模块多了之后不同模块的代码风格、错误处理方式可能不一致。解决方案是建立更详细的编码规范文档并且在 Agent 生成代码后自动跑 lint 检查。6.3 我个人的几点实操建议如果你打算尝试这套架构我有几个建议第一先从一个小模块开始。不要一上来就搞大项目先拿一个独立的小功能练手跑通整个流程理解 Agent 的工作节奏和 token 消耗规律。第二Markdown 文档要写得像合同一样精确。模糊的描述会导致 Agent 反复试错浪费 token 也浪费时间。接口定义用 schema数据表用表格边界条件用列表异常处理用流程图用 Markdown 的代码块画 ASCII 流程图不要用 Mermaid。第三定期审查 Agent 生成的代码。不要完全放手每周抽时间看一遍关键模块的代码发现问题及时调整 Markdown 文档。Agent 的行为很大程度上取决于你给它的指令质量。第四控制 token 预算。给自己设一个每月 token 消耗上限超过就停下来分析原因。是任务拆解太粗还是文档描述不清还是 Agent 配置有问题找到原因再继续。这套架构最吸引我的地方是它把“写代码”这件事从“逐行敲键盘”变成了“设计知识结构 调度 Agent 执行”。你的核心工作不再是写代码而是想清楚要做什么、怎么描述清楚、怎么验证结果。这个转变需要适应但一旦适应了产出效率的提升是实实在在的。