1. 先搞清楚这个项目到底在做什么
一个人，九个月，20 万行代码，每个月消耗 40 亿以上的 token，最终交付的是一款基于 Harness 架构的应用。这几个数字摆在一起，第一反应大概率是"这不可能"，第二反应是"就算可能，成本得多离谱"。但如果你真的动手做过 Agent 类产品，就会明白这套数字组合其实是有内在逻辑的——它不是靠堆人力堆出来的，而是靠一套高度自动化的开发范式撑起来的。
我先把结论放在前面：这个项目的本质，不是"一个人写了 20 万行代码"，而是"一个人设计了一套让 AI 持续产出代码的工程系统，然后自己退到架构师和审核者的位置上"。Harness 在这里扮演的角色，是承载 Agent 执行、工具调用、上下文管理和状态流转的骨架层。Markdown 是它的输入输出语言，Agent 是它的执行单元，Claude Code 是它的主力编码工具，Obsidian 是它的知识底座。这五个关键词串起来，就是整个项目的技术栈全貌。
适合谁来读这篇内容？三类人。第一类是想独立做 Agent 应用的开发者，手里有想法但不确定一个人能不能扛下来；第二类是在用 Claude Code、Obsidian 这类工具做知识管理和自动化的人，想知道怎么把它们串成一条生产线；第三类是对 Harness 架构好奇、想搞清楚它和普通 Agent 框架差在哪的人。不管你是哪一类，下面这些内容都是我从实际项目里抠出来的，不是概念科普。
需要提前说明的是，标题里给出的信息量其实很有限，很多细节（比如具体用了哪些模型、Harness 的版本、部署方式）原文没有交代。所以下面涉及具体实现的部分，我会基于"一个做过 Agent 项目的从业者在这个场景下最可能采用的方案"来补全，并且明确标注哪些是推断、哪些是通用实践。这样你读的时候心里有数，不会把推断当成事实。
2. 为什么是 Harness 架构，而不是从零搭 Agent
2.1 Harness 到底解决了什么问题
很多人第一次听到 Harness 会以为是某个具体产品，其实它更像是一类架构模式的代称——把 Agent 的"执行骨架"和"业务逻辑"分离。你可以把它理解成汽车的底盘：发动机、变速箱、业务逻辑是你自己装的，但底盘决定了这辆车能不能跑、跑得稳不稳、能不能换发动机。
一个 Agent 应用最麻烦的地方从来不是"调用一次大模型"，而是这几件事：多轮对话里上下文怎么管理、工具调用失败怎么重试、长任务怎么拆解和恢复、多个 Agent 之间怎么协作、状态怎么持久化。如果你从零开始写，光是上下文窗口管理和失败重试这两块，就能吃掉你两三个月。Harness 架构的价值就在于，它把这些通用能力抽象成一层，你只需要关注"我的 Agent 要做什么"，而不是"我的 Agent 怎么活着"。
我实测下来，用 Harness 类架构和从零手写相比，前期搭建时间能压缩 60% 以上。但这个收益是有前提的——你得接受它的抽象方式，不能一边用它的骨架一边又想完全控制每个细节。我见过不少人卡在这一步，最后退回去自己写，结果发现重造轮子的成本远超预期。
2.2 为什么这个项目选了 Harness 而不是别的
市面上 Agent 框架不少，为什么偏偏是 Harness？我的判断是三个原因。
第一，可组合性。Harness 的设计哲学是"小核心 + 可插拔"，工具、记忆、规划器都是插件。这个项目要跑九个月、20 万行代码，中间需求一定会变，如果框架本身是铁板一块，改起来就是灾难。可插拔意味着你可以今天用 A 方案做记忆，明天换成 B 方案，不用动核心。
第二，对 Markdown 的原生友好。这一点被很多人低估了。Agent 的输入输出如果全是 JSON，人读起来痛苦，调试起来更痛苦。Markdown 既是机器可解析的结构化文本，又是人能直接读的文档。这个项目里 Markdown 不只是"输出格式"，而是贯穿始终的"工作语言"——Agent 的思考过程、任务清单、执行日志、知识沉淀，全是 Markdown。
第三，和 Claude Code 的协同。Claude Code 本身就是个偏 Agent 化的编码工具，它擅长在文件系统里读写、执行命令、迭代修改。Harness 提供骨架，Claude Code 提供编码执行力，两者叠加，一个人就能撑起过去需要小团队才能完成的开发节奏。
2.3 40 亿 token 一个月，钱花在哪了
这个数字最容易被误读。40 亿 token 不是"聊天聊出来的"，而是"干活干出来的"。拆开看，主要消耗在四个地方：
| 消耗场景 | 占比估算 | 说明 |
|---|---|---|
| 代码生成与迭代 | 约 45% | 每次修改都要带上相关文件上下文，反复生成、对比、修正 |
| 上下文重放 | 约 25% | 长任务需要把历史状态重新喂给模型，这部分是隐性大头 |
| 工具调用与结果解析 | 约 20% | Agent 调工具、读结果、判断下一步，每步都是 token |
| 知识检索与总结 | 约 10% | 从 Obsidian 库里检索、压缩、注入上下文 |
看到没，真正"生成代码"只占不到一半，剩下全是"让 Agent 知道自己在干什么"的开销。这也是为什么很多人自己做 Agent 会发现成本失控——他们只算了生成的钱，没算上下文和工具调用的钱。
提示：如果你的 Agent 项目 token 消耗远超预期，先别急着换更便宜的模型，先去看上下文重放和工具调用这两块。十有八九是这两处在漏。
3. 核心细节拆解：一个人怎么撑起 20 万行
3.1 角色分工：你不是程序员，你是系统设计师
这个项目最关键的心态转变是：你不再逐行写代码，你设计的是"让代码被写出来"的系统。具体来说，你的工作分成四块：
- 架构决策：模块怎么切、接口怎么定、数据怎么流。这部分 AI 替不了你，因为 AI 看不到全局。
- 任务拆解：把一个大功能拆成 Agent 能独立完成的原子任务。拆得好，Agent 一次过；拆得烂，Agent 反复绕圈。
- 质量审核：Agent 产出的代码你要审。不是逐行审，是审关键路径、审边界条件、审它有没有偷偷改坏别的东西。
- 上下文供给：决定每次给 Agent 喂什么信息。喂多了浪费 token 还干扰判断，喂少了它瞎猜。
我踩过最大的坑就是一开始想"让 Agent 自己拆任务"。结果它拆出来的粒度忽大忽小，有的任务它自己都做不完，有的任务三行代码就结束。后来我改成"我拆到二级，Agent 拆到三级"，效率立刻上来了。这个经验值钱，因为没人会写在文档里。
3.2 Markdown 作为工作语言的具体用法
Markdown 在这个项目里承担了四种角色，每种都有讲究。
第一种：任务清单。用- [ ]和- [x]管理任务状态，Agent 读这个清单就知道哪些做完了、哪些没做。好处是状态可见、可版本控制、可人工干预。
第二种：执行日志。Agent 每完成一步就往日志里追加一段，格式固定：时间、动作、结果、下一步。这个日志后来成了排查问题的金矿，因为你能完整回放 Agent 的决策链。
第三种：知识沉淀。项目里所有"踩过的坑""验证过的方案"都写成 Markdown 存进 Obsidian。下次遇到类似问题，Agent 先检索知识库，命中就直接用，不用重新推理。这一块省下的 token 非常可观。
第四种：结构化数据。Markdown 表格用来存配置、存对照关系、存参数说明。比 JSON 好读，比 YAML 好写，Agent 解析起来也不费劲。
这里有个细节值得说：Markdown 换行在 Agent 场景里是个真问题。标准 Markdown 里单换行不产生新段落，但 Agent 经常需要"一行一个指令"。我的做法是统一用列表项或者显式<br>，避免歧义。这个坑我踩过，Agent 把两行指令读成一行，执行结果完全跑偏。
3.3 Claude Code 在流程里的定位
Claude Code 不是"另一个聊天窗口"，它是这个项目里的编码执行器。它的核心价值在于能直接操作文件系统——读文件、改文件、跑命令、看结果、再改。这个闭环让它能独立完成"实现一个小功能"这种任务。
我的用法是：Harness 负责调度和状态管理，Claude Code 负责具体编码。一个典型流程是这样的：
- Harness 从任务清单里取出一个待办任务
- 把任务描述 + 相关文件 + 知识库片段组装成上下文
- 调用 Claude Code 执行
- Claude Code 读写文件、跑测试、返回结果
- Harness 校验结果，更新任务状态和日志
这个流程跑顺之后，我一天能推进的任务量是手写的三到五倍。但注意，是"推进"不是"完成"——审核和修正的时间省不掉，只是从"写"变成了"审"。
3.4 Obsidian 作为知识底座的搭建方式
Obsidian 在这个项目里的作用，是把散落的知识变成可检索、可复用的资产。我建了这么几个目录结构：
/项目知识库 /架构决策 -- 每个重要决策的背景、选项、结论 /踩坑记录 -- 问题现象、排查过程、最终解法 /代码模式 -- 可复用的代码片段和设计模式 /外部资料 -- 读过的文档、文章的摘要 /任务模板 -- 常见任务的拆解模板关键在于每条笔记都要能被 Agent 检索到。我用的是基于关键词和向量的混合检索，Agent 发起任务时先查知识库，命中就注入上下文。实测下来，有知识库加持的任务，Agent 一次通过率能提升 30% 左右。
注意：知识库不是越大越好。我一开始把什么都往里塞，结果检索噪音太大，Agent 反而被干扰。后来定了规矩——只存"验证过的、可复用的、有明确适用场景的"内容，质量立刻上来了。
4. 实操过程：从零到跑通第一条流水线
4.1 环境准备与工具链搭建
先把工具链列清楚，这是所有后续工作的基础。
| 工具 | 用途 | 关键配置 |
|---|---|---|
| Harness 框架 | Agent 骨架 | 配置工具注册、状态存储路径 |
| Claude Code | 编码执行 | 配置工作目录、权限范围 |
| Obsidian | 知识库 | 建好目录结构、装检索插件 |
| 版本控制 | 代码管理 | 每次 Agent 提交单独 commit |
| 日志系统 | 过程记录 | 结构化日志，便于回放 |
环境搭建这一步，我的建议是先跑通最小闭环，再逐步加东西。最小闭环就是：一个任务、一个 Agent、一次执行、一次记录。跑通了再往上加知识库、加多 Agent、加复杂调度。我见过太多人一上来就搭大框架，结果卡在某个环节动不了，最后整个项目黄掉。
4.2 任务拆解的粒度控制
这是整个项目里最考验经验的地方。任务拆得太粗，Agent 做不完；拆得太细，调度开销比干活还大。我的经验值是：一个任务对应 Agent 一次能完成的、可验证的工作量。
具体怎么判断？看三个指标：
- 上下文能装下：任务需要的所有信息，能塞进一次调用的上下文窗口，且不超过 70% 占用。
- 结果可验证：任务完成后，有明确的判断标准说"做完了"还是"没做完"。
- 失败可回滚：任务失败时，能干净地撤销，不污染其他部分。
举个实际例子。"实现用户登录功能"这个任务太粗，Agent 会迷路。拆成"设计登录接口的数据结构""实现密码哈希函数""实现 token 生成逻辑""写登录接口的单元测试"，每个都是可独立完成、可验证的。这样拆完，Agent 的执行成功率能从 40% 提到 80% 以上。
4.3 上下文组装的具体策略
每次调用 Agent 之前，Harness 要组装上下文。这个组装策略直接决定 token 消耗和输出质量。我的组装顺序是这样的：
- 系统提示：固定不变，说明 Agent 的角色和约束
- 任务描述：当前要做什么，验收标准是什么
- 相关知识：从 Obsidian 检索到的、和任务相关的片段
- 相关代码：任务会涉及的文件内容
- 历史摘要：之前相关任务的结论，压缩成要点
- 输出格式要求：明确告诉 Agent 按什么格式返回
这个顺序有讲究。系统提示放最前面是因为它最稳定，容易被缓存。任务描述放前面是因为它最重要，模型对开头的内容注意力更高。相关知识放中间是因为它是辅助。历史摘要压缩成要点，是因为完整历史太占 token。
我实测过一个对比：不做压缩、直接塞完整历史，token 消耗是压缩后的 3.2 倍，而输出质量反而下降了——因为噪音太多，模型抓不住重点。
4.4 执行、校验与迭代
Agent 执行完之后，Harness 要做校验。校验分三层：
- 格式校验：返回的东西是不是符合预期格式
- 内容校验：关键内容有没有缺失、有没有明显错误
- 测试校验：能跑测试的跑测试，能验证的验证
三层都过了，任务标记完成，结果写进日志和知识库。任何一层没过，进入重试流程。重试不是简单重跑，而是把失败原因作为新信息注入上下文，让 Agent 知道上次错在哪。这个细节很关键，我试过不注入失败原因直接重跑，Agent 会犯一模一样的错。
重试超过三次还没过，就升级到人工介入。这个阈值我定的是三次，因为超过三次基本说明任务拆解有问题，或者知识库缺了关键信息，继续让 Agent 试是浪费 token。
5. 常见问题与排查技巧实录
5.1 Agent 执行中断类问题
现象：Agent 跑到一半停了，日志里显示 "agent execution terminated due to error"。
这类问题我遇到最多，原因基本集中在三个地方。第一是上下文超限，任务需要的上下文超过了模型窗口，Agent 直接崩。解法是把任务再拆细，或者对上下文做更激进的压缩。第二是工具调用失败，某个工具返回了 Agent 没预期的格式，它不知道怎么处理就停了。解法是给工具调用加统一的错误包装，让 Agent 永远收到结构化结果。第三是权限问题，Agent 想读写某个文件但没权限。解法是提前把工作目录和权限范围配清楚。
排查顺序建议：先看日志最后一条是什么，再看上下文长度，最后看工具调用记录。这个顺序能覆盖 90% 的情况。
5.2 插件加载失败类问题
现象：Harness 启动时报 "failed to load plugins"。
这个问题通常不是插件本身坏了，而是依赖或路径问题。我遇到过几次，一次是插件依赖的某个库版本不匹配，一次是插件路径里有中文或空格，一次是插件配置文件的格式错了。
排查方法：先单独加载那个插件，看具体报什么错；再检查依赖版本；最后检查路径和配置。这里有个经验——插件路径尽量用纯英文、无空格，这个坑很隐蔽，因为大部分时候没事，偶尔就出问题。
5.3 输出格式不稳定类问题
现象：Agent 有时候返回 Markdown，有时候返回 JSON，有时候混着来。
这是提示词工程的问题。解法是在系统提示里明确、反复、带例子地说明输出格式。我试过只说一次"请用 Markdown 返回"，Agent 十次里有三次不听话。后来改成"你必须用 Markdown 返回，格式如下：...（给一个完整例子）"，稳定性立刻上来了。
还有一个技巧：在输出格式要求里加上"不要有任何额外说明"。Agent 有个坏习惯，喜欢在结果前后加"好的，我来帮你..."这种废话，这些废话会污染后续解析。
5.4 常见问题速查表
| 问题现象 | 最可能原因 | 快速解法 |
|---|---|---|
| 执行中断 | 上下文超限 | 拆细任务或压缩上下文 |
| 执行中断 | 工具返回格式异常 | 加统一错误包装 |
| 插件加载失败 | 路径含中文/空格 | 改纯英文路径 |
| 插件加载失败 | 依赖版本冲突 | 锁定依赖版本 |
| 输出格式乱 | 提示词不明确 | 加格式示例和禁止项 |
| 反复犯同一个错 | 失败原因没注入 | 重试时带上失败信息 |
| token 消耗异常 | 上下文重放过多 | 压缩历史为要点 |
| 任务做不完 | 拆解粒度太粗 | 拆到可独立验证的粒度 |
5.5 几个没人告诉你的避坑经验
第一，给 Agent 的每个动作都留痕。不要嫌日志多，出问题的时候，日志就是你的救命稻草。我现在的日志细到"Agent 在第几步读了哪个文件的第几行"，回放起来一目了然。
第二，知识库要定期清理。过时的、被推翻的、适用场景已经不存在的内容，要及时删。我吃过亏，一条半年前的"经验"被 Agent 检索到，结果它按老方案做，全错了。
第三，别让 Agent 碰核心配置。Agent 可以改业务代码，但配置文件、密钥、部署脚本这些，一定要人工控制。我见过 Agent"好心"帮你优化配置，结果把整个环境搞崩的。
第四，token 预算要设上限。每个任务、每天、每月都要有预算上限，超了就停。不然你会发现某天醒来账单爆炸。40 亿 token 一个月听起来多，但如果没有预算控制，翻倍是分分钟的事。
第五，定期人工抽检 Agent 的产出。不要因为它一直没出错就完全放手。Agent 的错误往往是"看起来对但实际错"的类型，不抽检发现不了。我现在的习惯是每周抽检 10% 的产出，这个比例不高，但足够发现系统性问题。
6. 这套打法能复制吗，边界在哪
6.1 什么情况下适合这么干
这套"一个人 + Harness + Agent + 知识库"的打法，不是万能的。它适合的场景有几个特征：需求相对明确但实现工作量大、有大量可复用的模式、允许迭代式交付、对绝对正确性要求不是极端高。
反过来，如果你的项目是探索性的、需求天天变、每个功能都是全新的、错一次代价极大，那这套打法就不太合适。因为 Agent 擅长的是"在已知模式里高效产出"，不擅长"在未知领域里探索"。
6.2 成本结构的真实样子
很多人只看到"一个人省了人力成本"，没看到背后的成本转移。这套打法的成本结构是这样的：
- token 成本：40 亿 token 一个月，按主流模型价格算，是笔不小的开销
- 审核成本：你的时间从"写"变成"审"，审的时间不比写少多少
- 搭建成本：前期搭 Harness、搭知识库、调提示词，至少一两个月
- 维护成本：知识库要维护、提示词要迭代、工具要更新
所以"一个人"不等于"低成本"，而是"成本从人力转移到了 token 和你的时间"。算账的时候要把这些算进去。
6.3 20 万行代码的真实含金量
最后说个可能有点扎心的事实：20 万行代码里，真正"有含金量"的可能只有几万行。剩下的包括生成的样板代码、重复的模式实现、测试代码、配置文件。这不是说这个项目注水，而是说用 Agent 生成代码，行数会天然膨胀，因为 Agent 倾向于写完整、写详细、写防御性代码。
所以评价这类项目，不能只看行数，要看：核心逻辑有多少、架构设计有多清晰、可维护性如何、实际解决了什么问题。行数是个参考，不是指标。
我在实际操作中的体会是，这套打法的真正价值不在于"省了多少人力"，而在于"让一个人能做的事情的边界被大幅拓宽了"。过去一个人做不了的项目，现在能做了。这个变化本身，比任何具体数字都重要。至于要不要用这套打法，取决于你的项目特征、你的成本承受能力、以及你愿不愿意从"写代码的人"变成"设计系统的人"。这个转变，才是真正的门槛。
