1. 先搞清楚这个项目到底在做什么一个人九个月二十万行代码每个月消耗四十亿以上的 token最终交付一个基于 Harness 架构的应用。这组数字放在任何一个技术社区里都足够炸裂但真正值得琢磨的不是数字本身而是它背后暴露出来的一套工作方式——一个人如何借助 AI Agent 把产能拉到过去需要一个团队才能达到的量级。先把概念理清楚。这里说的Harness不是某个具体的库或者框架名字而是一种架构思路把 AI Agent 当作一个可以被“套上缰绳”的执行单元用一层外壳去约束它的输入、输出、工具调用和状态管理。你可以把它理解成给一匹力气极大但方向感不稳定的马装上马具——马还是那匹马但你能控制它往哪走、走多快、什么时候停。这个比喻其实很贴切Harness 这个词本身就是“马具、挽具”的意思。那这个项目具体解决什么问题简单说它要解决的是AI Agent 在真实生产环境里不可控、不可复现、不可维护这三个老大难。你让 Claude Code 或者别的 Agent 去写代码单次任务它可能干得漂亮但一旦任务链条变长、上下文变复杂、需要跨会话保持状态它就开始飘。Harness 架构的核心价值就是把这匹“飘”的马拴住让它的行为变得可预测、可回滚、可审计。适合谁来参考三类人。第一类是独立开发者或者小团队想用 AI 把产能放大但不知道怎么系统化落地第二类是在做 Agent 相关产品的工程师需要一套工程化的约束方案第三类是重度使用 Obsidian、Markdown 做知识管理同时想把 Agent 接进自己工作流的人。如果你只是偶尔用 AI 写个函数这个项目的思路对你可能偏重但里面关于上下文管理和状态持久化的技巧依然值得看。九个月二十万行代码这个比例平均下来每天大概七百多行有效代码。注意“有效”两个字——这不是复制粘贴堆出来的行数而是在 Agent 辅助下经过反复迭代、测试、重构后沉淀下来的。四十亿 token 一个月按三十天算每天一亿多这个消耗量说明 Agent 几乎全程在线承担了大量重复性、探索性的工作。这两个数字放在一起其实揭示了一个关键事实AI 辅助开发不是让你少干活而是让你把精力从“写”转移到“设计约束和验证结果”上。2. 为什么是 Harness 架构而不是直接裸用 Agent2.1 裸用 Agent 的三个致命伤我最早接触 Agent 开发的时候也是直接调 API 让它干活结果踩了一堆坑。第一个坑是上下文漂移对话轮次一多Agent 就忘了最初的目标开始自由发挥。第二个坑是工具调用失控你给它开放了文件读写权限它可能在你没预期的时候改了一堆不该改的文件。第三个坑是状态丢失会话一断之前积累的中间结果全没了下次得从头再来。这三个问题在单次简单任务里不明显但一旦项目规模上去就是灾难。二十万行代码的项目如果每次 Agent 都从零开始理解上下文光是重复读取和解析就要烧掉海量 token而且结果还不稳定。Harness 架构要解决的就是这个——它把 Agent 的运行环境、工具集、状态存储、输出格式全部标准化让 Agent 每次启动都能站在一个确定的起点上。2.2 Harness 架构的核心分层我理解的 Harness 架构大致分四层这个分层是我在实际项目里摸索出来的不一定和某个官方定义完全一致但逻辑上是自洽的。最底层是状态层负责持久化。这里 Markdown 和 Obsidian 就派上用场了。为什么用 Markdown 而不是数据库因为 Markdown 是纯文本人和 Agent 都能直接读写diff 友好版本控制友好而且 Obsidian 的双向链接天然适合做知识图谱。Agent 每次任务的输入、输出、中间决策全部以 Markdown 文件的形式落盘下次启动直接读文件恢复状态。这比把状态塞进向量数据库要透明得多出问题的时候你能一眼看出是哪一步的上下文错了。第二层是工具层也就是 Agent 能调用的能力集合。这一层的关键是最小权限原则Agent 需要读文件就只给读权限需要写就限定在特定目录需要执行命令就白名单化。Claude Code 在这方面做得比较克制它的工具调用是有明确边界的这也是我选它作为主力 Agent 的原因之一。第三层是编排层负责把大任务拆成小步骤控制每一步的输入输出。这一层是 Harness 的灵魂。一个二十万行的项目不可能让 Agent 一口气写完必须拆成几百上千个原子任务每个任务有明确的输入、输出和验收标准。编排层要做的就是调度这些任务处理失败重试管理任务之间的依赖关系。第四层是验证层负责检查 Agent 的输出是否符合预期。这一层最容易被忽略但恰恰是最重要的。没有验证Agent 写的东西你不敢用有了验证你才能放心让它自动化跑。验证可以是单元测试、类型检查、lint也可以是更复杂的语义检查。2.3 这套架构相比其他方案的取舍市面上做 Agent 编排的方案不少有基于图的有基于事件流的也有纯 prompt 链的。我最终选择 Harness 这种“外壳约束”的思路核心原因是可控性优先于灵活性。图编排很灵活但调试起来痛苦事件流很优雅但状态追踪复杂。Harness 的思路是把复杂度收敛到几个明确的边界上牺牲一部分灵活性换取可预测性。这个取舍在个人项目里尤其重要。一个人做项目最怕的就是系统太复杂自己都理不清。Harness 架构的每一层职责清晰出问题的时候你能快速定位是哪一层的问题。而且因为状态全部落盘成 Markdown你甚至可以直接用 Obsidian 打开看用人类的眼睛去审查 Agent 的决策过程这在调试阶段价值巨大。3. 核心细节拆解Markdown、Obsidian 与 Agent 的三角关系3.1 为什么 Markdown 是 Agent 状态存储的最优解很多人做 Agent 项目第一反应是上数据库Postgres 加 pgvector看起来很专业。但我实测下来对于个人项目Markdown 文件系统反而是更优解。原因有三。第一可读性。Agent 的状态如果存在数据库里你调试的时候得写查询语句才能看到。存在 Markdown 里直接打开文件就能看甚至可以用 Obsidian 的图谱视图直观地看到任务之间的关联。调试效率差好几倍。第二可版本控制。Markdown 是纯文本git diff 一目了然。Agent 改了什么东西你 review 的时候清清楚楚。数据库的变更日志可读性差远了。第三Agent 原生友好。Claude Code 这类工具本身就是围绕文件系统设计的它读写 Markdown 文件的能力是内置的、经过优化的。你让它去操作数据库反而要额外写工具封装增加出错概率。具体怎么组织这些 Markdown 文件我的做法是按任务层级建目录。顶层是项目概览往下是模块再往下是具体任务。每个任务一个 Markdown 文件文件头用 YAML frontmatter 记录元数据比如任务状态、依赖、创建时间。正文部分记录任务描述、Agent 的决策过程、输出结果。这样一套结构下来整个项目的状态就是一棵可浏览的文件树。注意Markdown 的换行是个坑。标准 Markdown 里单个换行不产生新段落需要空行或者行尾加两个空格。Agent 生成内容的时候经常忽略这一点导致格式错乱。我的做法是在 Harness 的验证层加一个 Markdown lint 检查格式不对就打回重写。3.2 Obsidian 在项目里扮演的角色Obsidian 在这个项目里不是可有可无的装饰而是核心基础设施。它承担了三个职能。第一个职能是知识库。项目开发过程中积累的技术决策、踩坑记录、参考资料全部以 Markdown 形式存进 Obsidian vault。Agent 需要背景知识的时候直接从 vault 里检索。这比把知识塞进 prompt 要高效得多因为 vault 可以无限大而 prompt 有窗口限制。第二个职能是可视化调试。Obsidian 的图谱视图能把 Markdown 文件之间的链接关系画出来。当 Agent 的任务依赖关系出问题时我打开图谱一看哪个任务孤立了、哪个依赖断了一目了然。这个功能在排查复杂依赖问题时救过我好几次。第三个职能是人机协作界面。有些决策我不想让 Agent 全自动做就在 Obsidian 里写一个待办笔记Agent 读到之后把它的建议写回来我再人工确认。这种人机来回的方式比纯自动化更稳尤其在项目早期需求还不明确的时候。关于 Obsidian 的插件我推荐几个实际用下来有价值的。Dataview 插件可以用类 SQL 的语法查询笔记做任务看板特别方便。Templater 插件可以自动化生成任务笔记的模板保证格式统一。还有一个 Markdown 表格转换的工具能把表格导出成 Excel方便做数据分析。至于数学公式如果你做的是算法类项目MathJax 插件是必须的行内公式用单个美元符号块级公式用双美元符号这个语法 Agent 有时候会写错需要在验证层检查。3.3 Agent 选型Claude Code 与其他方案的对比主力 Agent 我选的是 Claude Code理由前面提过一部分这里展开说。Claude Code 的核心优势是它的工具调用设计得很克制文件操作、命令执行、代码搜索这几个核心能力都有明确的边界和确认机制。你可以在配置里精确控制它哪些目录能碰、哪些命令能跑。这种克制在长时间运行的项目里是优点因为它降低了失控风险。安装 Claude Code 本身不复杂但配置有几个关键点。第一是工作目录的设定一定要限定在项目目录内不要给它整个文件系统的访问权。第二是模型的选择如果预算有限可以用本地模型但实测下来复杂任务上本地模型和云端模型的差距还是很明显的尤其是长上下文推理。第三是会话管理Claude Code 的会话是可以持久化的但要注意定期清理不然上下文会越滚越大。其他方案我也试过。有些 Agent 框架更灵活支持自定义工具但配置复杂度高调试成本大。有些则太封闭扩展性差。Claude Code 在灵活性和易用性之间找到了一个不错的平衡点尤其适合个人开发者。至于 DeepSeek 相关的 Harness 方案社区里讨论很多安装和插件生态也在快速完善如果你对成本敏感可以关注但我在这个项目里没有深度使用就不多评价了。4. 实操过程从零搭建一套可运行的 Harness 工作流4.1 环境准备与目录结构设计动手之前先把目录结构定下来这个结构会贯穿整个项目。我的做法是分四个顶层目录。project/ ├── harness/ # Harness 核心配置和脚本 │ ├── config/ # Agent 配置、工具白名单 │ ├── prompts/ # 各类任务的 prompt 模板 │ └── validators/ # 验证脚本 ├── state/ # Agent 状态存储Markdown 文件 │ ├── tasks/ # 任务状态 │ ├── context/ # 上下文快照 │ └── logs/ # 运行日志 ├── knowledge/ # Obsidian vault知识库 │ ├── decisions/ # 技术决策记录 │ ├── references/ # 参考资料 │ └── pitfalls/ # 踩坑记录 └── src/ # 实际项目代码这个结构的关键是state 和 knowledge 分离。state 是 Agent 运行时产生的、频繁变动的状态knowledge 是相对稳定的、人类和 Agent 共享的知识。分开之后state 可以频繁清理和重建knowledge 则长期积累。很多人把这两个混在一起结果就是状态文件越堆越多知识反而被淹没。环境准备阶段还要装几个基础工具。Git 是必须的用来做版本控制。Node.js 或者 Python 看你的项目类型用来跑验证脚本。Obsidian 用来浏览 knowledge 目录。Claude Code 按官方文档装好配置好 API 访问。4.2 任务拆解与 Prompt 模板设计二十万行代码不可能一口气写完必须拆。我的拆解粒度是单个任务不超过 Agent 一次会话能完成的范围大概是几百行代码或者一个独立的功能点。拆得太粗Agent 会中途迷失拆得太细编排开销太大。每个任务对应一个 Markdown 文件用统一的模板。模板大概长这样--- task_id: TASK-001 status: pending depends_on: [TASK-000] module: auth created: 2024-01-15 --- ## 任务描述 实现用户登录接口支持邮箱密码登录返回 JWT。 ## 输入 - 用户模型定义见 state/context/user-model.md - 接口规范见 knowledge/references/api-spec.md ## 验收标准 - 单元测试覆盖率 80% 以上 - 通过 lint 检查 - 错误处理符合项目规范 ## 执行记录 Agent 执行后填写这个模板的设计要点是输入明确、验收标准可量化。Agent 最怕的就是模糊指令你告诉它“写个好点的登录接口”它给你的东西大概率不符合预期。把输入和验收标准写清楚它的输出质量会稳定很多。Prompt 模板我按任务类型分了几套功能实现类、重构类、测试类、文档类。每套模板的侧重点不同。功能实现类强调输入输出和边界条件重构类强调保持行为不变测试类强调覆盖率和边界文档类强调结构清晰。模板放在 harness/prompts 目录下编排脚本根据任务类型自动选用。4.3 编排脚本与状态流转编排脚本是整个 Harness 的调度中心。我用 Python 写了一个简单的调度器逻辑不复杂核心就是循环扫描 state/tasks 目录找到 status 为 pending 且依赖已满足的任务调用 Claude Code 执行执行完更新状态。状态流转大概是这几个pending 到 in_progress 到 review 到 done失败的话到 failed。review 状态是留给人工检查的不是所有任务都需要但关键任务我会过一眼。这个状态机看起来简单但实际跑起来能避免很多混乱。比如一个任务失败了调度器不会傻乎乎地继续往下跑而是停下来等你处理。编排脚本里有个细节值得说上下文注入。每个任务执行前脚本会把相关的 context 文件和 knowledge 文件的内容拼进 prompt。拼多少是有讲究的拼太少 Agent 缺信息拼太多浪费 token 还稀释重点。我的做法是只拼直接相关的间接相关的让 Agent 自己去检索。Claude Code 有文件搜索能力你告诉它去哪找它自己会去读。4.4 验证层让 Agent 的输出可信验证层是我花时间最多的地方也是最值得投入的地方。没有验证Agent 的输出你不敢直接用整个自动化就失去意义。验证分三级。第一级是语法级跑 lint、类型检查、格式检查。这一级最快能挡掉大部分低级错误。第二级是行为级跑单元测试、集成测试。这一级慢一些但能发现逻辑错误。第三级是语义级这个最难需要人工或者用另一个 Agent 来审查。我的做法是让一个独立的 Agent 扮演 reviewer 角色专门挑毛病它的输出我再人工过一遍。三级验证全过任务才算 done。这个流程看起来繁琐但实际跑下来因为大部分任务在第一级就被挡回去了Agent 会自己修真正需要人工介入的比例并不高。四十亿 token 一个月很大一部分就是烧在 Agent 自己反复修错上。这个消耗是值得的因为它把人工从重复劳动里解放出来了。5. 常见问题与排查技巧实录5.1 Agent 跑偏了怎么办这是最常见的问题。Agent 执行到一半方向偏了开始做一些任务描述里没要求的事。排查思路是先看 state/logs 里的执行日志找到它偏离的那个点然后看那个点的上下文里有什么误导信息。大部分跑偏的原因是上下文里有歧义。比如任务描述里说“优化性能”Agent 可能理解为重构代码也可能理解为加缓存。解决办法是把模糊词替换成具体指标比如“把接口响应时间从 200ms 降到 100ms 以内”。另一个常见原因是知识库里有冲突信息Agent 读到两条矛盾的参考自己选了一条错的。解决办法是定期清理知识库过时的决策记录要标记废弃。5.2 Token 消耗失控怎么控制四十亿 token 一个月听起来吓人但拆开看是可控的。失控通常发生在两个环节一是上下文注入太多二是 Agent 反复重试。上下文注入的问题前面说了只拼直接相关的。重试的问题要靠验证层解决验证标准越明确Agent 一次过的概率越高。另外我还会设置重试上限同一个任务失败三次就停下来人工介入不让它无限烧下去。还有一个技巧是缓存。有些任务的输入是重复的比如每次都要读同一份规范文档。这种可以缓存起来不用每次都重新读。Claude Code 本身有 prompt caching 机制配置好了能省不少。5.3 Markdown 格式错乱的排查Agent 生成的 Markdown 经常有格式问题最常见的是换行、表格对齐、代码块语言标注。这些问题不影响内容但影响可读性和后续处理。我的做法是在验证层加一个 Markdown lint 步骤用现成的 lint 工具跑一遍不通过就打回。表格转换 Excel 的时候格式问题尤其明显列对不齐会导致转换失败所以表格的格式检查要更严格。数学公式的语法也要检查行内公式和块级公式的符号不能混。5.4 常见问题速查表问题现象可能原因排查方向解决手段Agent 中途跑偏上下文有歧义查执行日志找偏离点替换模糊词为具体指标Token 消耗暴涨上下文注入过多或反复重试看单任务 token 消耗精简上下文、设重试上限任务卡住不动依赖未满足或状态未更新查任务依赖图手动修复依赖或重置状态Markdown 格式乱Agent 忽略格式规范跑 lint 检查验证层加格式检查验证一直不通过验收标准太严或 Agent 能力不足看失败原因分布调整标准或换更强模型知识库检索不到文件命名或链接不规范查 Obsidian 图谱统一命名和链接规范5.5 几个踩过的坑第一个坑是过早追求全自动化。我一开始想让整个流程无人值守结果 Agent 在关键决策上做了一堆错误选择返工成本比省下的时间还多。后来改成关键节点人工确认整体效率反而更高。自动化的边界要慢慢扩不能一步到位。第二个坑是知识库不维护。项目跑久了知识库里堆了一堆过时信息Agent 读到之后被误导。现在我每周花半小时清理知识库把废弃的决策标记掉把新的经验补进去。这半小时的投入回报率极高。第三个坑是忽视 Agent 的“疲劳”。长时间运行的会话Agent 的表现会下降上下文越长越明显。我的做法是定期开新会话把必要的状态从 Markdown 里重新加载。这相当于给 Agent 一个“重启”让它回到清醒状态。第四个坑是验证标准写得太死。一开始我把验收标准写得很细结果 Agent 为了通过验证做了一堆无意义的适配。后来改成抓大放小核心指标严格次要指标宽松Agent 的创造力反而被释放出来了。6. 这套工作流的扩展方向跑通基础流程之后我陆续加了一些扩展效果不错分享几个。第一个扩展是多 Agent 协作。单个 Agent 做复杂任务容易顾此失彼我试过让一个 Agent 写代码、一个 Agent 写测试、一个 Agent 做 review三个角色互相制衡。这个模式在关键模块上效果很好但开销也大适合用在核心功能上不适合全项目铺开。第二个扩展是知识库自动更新。Agent 每次踩坑之后让它自动把坑记录到 knowledge/pitfalls 目录。这样知识库会随着项目推进自动积累不用我手动整理。当然自动生成的内容质量参差不齐需要定期人工筛选。第三个扩展是跨项目复用。Harness 的配置、prompt 模板、验证脚本这些其实是可以跨项目复用的。我把通用的部分抽出来做成模板新项目直接套用启动成本大幅降低。这也是为什么第一个项目花了九个月后面类似规模的项目时间能压缩不少。第四个扩展是与现有工具链集成。比如把 Obsidian 的任务看板和 git 的 issue 系统打通Agent 可以直接从 issue 里读任务完成后自动更新状态。这种集成让整个工作流更顺滑减少手动搬运。关于并发的问题一个人做项目其实不太需要高并发但如果你的 Agent 任务之间没有依赖可以并行跑多个。Claude Code 支持多会话只要注意状态隔离就行。并发的主要瓶颈是 API 速率限制和成本不是技术问题。最后说一个我个人的体会。这套工作流的核心不是让 AI 替你思考而是让 AI 替你执行。思考的部分——做什么、为什么做、做到什么程度——还是得你自己来。Harness 架构的价值就在于把执行部分标准化、可预测化让你能把精力集中在真正需要人类判断的地方。九个月二十万行代码听起来是 AI 的功劳但真正决定项目成败的是那套约束 AI 的缰绳设计得好不好。