1. 一个人九个月二十万行代码，这件事到底在说什么
先把标题里的数字拆开看。一个人，九个月，二十万行代码，每个月四十亿以上的 token 消耗，最终产物是一个 Harness 架构的应用。这几个数字放在一起，任何一个写过代码的人都会先愣一下——不是因为二十万行有多夸张，而是因为“一个人”和“九个月”这两个约束条件，配上“四十亿 token 每月”这个量级，说明整个开发范式已经和传统的手写代码完全不是一回事了。
传统意义上，一个二十万行代码量的应用，哪怕是一个中等复杂度的桌面软件或者后端服务，通常需要一个五到十人的团队干上一到两年。而这里是一个人，九个月。差距从哪来？答案就藏在“每月四十亿 token”这个数字里。四十亿 token 是什么概念？如果按主流大模型 API 的计费方式粗略估算，输入输出混合计算，这大概对应着每月数万到十几万美元的推理成本。换句话说，这个人不是在“写”代码，而是在“驱动”一个由大模型参与的代码生成与编排系统，自己更多扮演的是架构师、审核者和调试者的角色。
那 Harness 架构又是什么？这里的 Harness 不是指某个具体的商业产品，而是一种架构思路——把大模型能力、工具调用、上下文管理、任务编排这几件事用一个统一的“挽具”串起来，让 Agent 能够稳定地执行复杂任务。你可以把它理解成一个“给 AI 套上缰绳”的框架：模型本身是野马，能力很强但容易跑偏，Harness 就是那套缰绳、鞍具和路标，让它能沿着既定路线把活干完。热搜词里出现的 deepseek harness、harness anything、harness engineering、harness 使用教程，基本都指向这个方向。
这个项目真正值得聊的地方，不是“一个人干了团队的活”这种励志叙事，而是它揭示了一套可复现的方法论：如何用 Markdown 作为知识载体，用 Obsidian 作为知识库和项目管理台，用 Claude Code 这类 Agent 工具作为执行引擎，用 Harness 架构把三者粘起来，最终让一个人也能撑起一个大型应用的开发。热搜词里 Markdown、Obsidian、Claude Code、Agent、Harness 这几个词高频共现，本身就说明了这套组合拳正在成为很多独立开发者的标配。
这篇文章适合谁看？如果你是一个独立开发者，正在琢磨怎么用 AI 工具把自己的产出放大十倍；如果你是一个小团队的技术负责人，想知道 Agent 架构到底能落地到什么程度；如果你只是对 Obsidian、Claude Code、Harness 这些词好奇，想知道它们凑在一起能干什么——那接下来的内容应该对你有用。我会尽量把每个环节的“为什么”讲清楚，而不是只丢一堆工具名和命令。
2. 整体架构设计：为什么是 Harness 而不是普通 Agent 脚本
2.1 从“写代码”到“编排代码生产”的思维转变
很多人第一次接触 Agent 开发，脑子里想的还是“我写一个脚本，调用一下 API，让模型帮我生成一段代码”。这个思路在任务简单的时候没问题，但一旦任务复杂度上来，比如要维护一个二十万行代码量的项目，立刻就会崩。原因很简单：单次 API 调用没有记忆，没有状态，没有任务分解能力，也没有错误恢复机制。你让它改一个函数，它可能把整个文件重写一遍；你让它加一个功能，它可能把已有的接口签名改掉。
Harness 架构要解决的就是这个问题。它的核心思路是把“一次调用”变成“一个可持续运行的任务循环”。这个循环里至少包含几个关键角色：任务规划器负责把大目标拆成小步骤，执行器负责调用模型和工具完成每一步，上下文管理器负责决定每一步该给模型看哪些信息，校验器负责检查输出是否符合预期，记忆模块负责把有用的信息沉淀下来供后续步骤使用。这五个角色不是五个独立的服务，而是 Harness 这个“挽具”里的五个功能模块，它们协同工作，让 Agent 能够长时间、多步骤地推进任务。
为什么不用现成的 Agent 框架？市面上的 Agent 框架不少，但大多数要么太轻，只能做 demo；要么太重，配置复杂到让人放弃。Harness 架构的好处是它足够薄，你可以自己控制每一层的实现细节，同时又足够结构化，不会写着写着就变成一团乱麻。热搜词里的 harness engineering、agent 框架、agent 开发，讨论的其实就是这个层面的问题：怎么设计一套既灵活又稳定的 Agent 运行环境。
2.2 Markdown + Obsidian + Claude Code 的三层分工
这套组合里，三个工具各司其职，分工非常清晰。
Markdown 是知识载体。为什么不用数据库或者 JSON？因为 Markdown 对人友好，对模型也友好。人可以直接读、直接改，模型解析起来也几乎没有歧义。热搜词里 markdown 换行、markdown 语法、markdown 表格转换 excel、markdown 转 word 工作流 coze 这些词频繁出现，说明 Markdown 在实际工作流里的使用场景非常广。在这个项目里，Markdown 承担的是“规格说明书 + 任务清单 + 知识笔记”三重角色。每一个功能模块的设计文档是 Markdown，每一个待办任务是 Markdown，每一次调试的经验记录也是 Markdown。
Obsidian 是知识库和项目管理台。Obsidian 的核心能力是双向链接和本地文件管理，这两点让它非常适合做 Agent 项目的“外部大脑”。你可以把项目里所有的 Markdown 文件用 Obsidian 组织起来，用双链建立模块之间的关联，用标签做分类，用 Dataview 插件做任务看板。热搜词里 obsidian 插件推荐、obsidian 教程、obsidian 创建项目管理台账、obsidian 的 docxer 怎么用，这些都是在讨论怎么把 Obsidian 用成一个真正的生产力工具，而不是一个单纯的笔记软件。在这个项目里，Obsidian 就是那个“总控台”，所有任务的状态、所有模块的依赖关系、所有踩过的坑，都在这里一目了然。
Claude Code 是执行引擎。Claude Code 这类工具的核心价值在于它能在本地文件系统上直接操作，读文件、写文件、运行命令、查看输出，形成一个完整的“感知-决策-执行”闭环。热搜词里 claude code 安装、claude code 使用、vscode 配置 claude code、claude code 下载、claude code desktop 国内下载，说明很多人已经在尝试把它接入自己的工作流。在这个项目里，Claude Code 负责把 Obsidian 里的任务描述读进来，理解上下文，然后生成代码、修改文件、运行测试，把结果写回 Obsidian。
这三层的关系可以这样理解：Obsidian 是大脑皮层，负责长期记忆和全局规划；Markdown 是神经元之间的信号，负责传递具体信息；Claude Code 是运动皮层，负责把决策变成实际动作。Harness 架构则是把这些连起来的神经网络，确保信号传递不丢包、不串线、不无限循环。
2.3 为什么每月要烧四十亿 token
四十亿 token 这个数字听起来吓人，但拆开看就合理了。一个二十万行代码的项目，如果每一行代码在生成、审查、修改、测试的过程中平均被模型“看”过二十遍，那就是四百万行次的处理量。每行代码加上上下文，平均按一百 token 算，就是四亿 token。这还只是代码本身，再加上设计文档、任务描述、调试日志、错误信息、对话历史，四十亿 token 一个月并不夸张。
关键在于，这些 token 不是白烧的。Harness 架构的一个重要设计目标就是“让每一 token 都花在刀刃上”。具体做法包括：上下文窗口的精细管理，只把当前步骤真正需要的信息喂给模型；缓存机制的合理使用，避免重复计算相同的内容；任务分解的粒度控制，不让模型一次面对过大的上下文。热搜词里 agent execution terminated due to error、codex 无法发送消息、显示更新 agent 沙盒、harness failed to load plugins，这些报错信息背后，往往就是上下文管理没做好导致的。
提示：token 消耗量不是衡量项目质量的指标，但它是衡量 Agent 系统是否在“认真干活”的一个参考。如果一个 Agent 项目每月 token 消耗很低，大概率说明它做的事情太简单，或者上下文管理太粗糙，大量信息被浪费了。
3. 核心细节解析：Harness 架构里那些容易踩坑的地方
3.1 上下文管理：决定 Agent 能不能干长活的命门
Harness 架构里最核心、也最容易出问题的模块就是上下文管理。你可以把它想象成一个“信息调度员”：每一步任务开始前，它要决定从庞大的知识库里抽取哪些信息放进模型的上下文窗口。抽多了，token 浪费，模型注意力被稀释；抽少了，模型缺信息，输出质量下降；抽错了，模型被误导，直接跑偏。
这个项目里采用的策略是“分层上下文”。第一层是全局上下文，包括项目整体架构、核心接口定义、编码规范，这部分内容相对稳定，可以长期驻留。第二层是模块上下文，包括当前正在处理的模块的设计文档、相关代码文件、依赖关系，这部分内容按需加载。第三层是任务上下文，包括当前具体任务的描述、上一步的输出、相关的错误信息，这部分内容每一步都在变。
分层的好处是，你可以给每一层设置不同的加载策略和过期策略。全局上下文可以缓存，模块上下文可以预加载，任务上下文必须实时更新。热搜词里 markdown preview enhanced、markdown 阅读器、markdown 数学符号，这些工具层面的讨论，其实都指向同一个需求：怎么让 Markdown 内容在 Agent 工作流里被高效地解析和呈现。
实操中有一个细节特别重要：Markdown 文件的标题层级要规范。H2 和 H3 的编号不只是给人看的，也是给 Agent 看的。Agent 在解析 Markdown 时，会依赖标题层级来判断内容的归属关系。如果标题层级混乱，Agent 提取上下文时就会出错。这也是为什么我在项目里强制要求所有 Markdown 文件必须使用规范的标题编号。
3.2 任务分解：怎么让 Agent 不迷路
二十万行代码的项目，不可能让 Agent 一次性完成。必须把大任务拆成小任务，小任务拆成具体步骤。但拆任务这件事本身也有讲究。拆得太粗，Agent 一步做太多事，容易出错且难以定位问题；拆得太细，Agent 频繁切换上下文，效率低下且容易丢失全局观。
这个项目里采用的任务分解粒度是“一个函数或一个文件级别”。具体来说，每个任务对应一个明确的产出物：要么是一个新文件的创建，要么是一个现有文件的修改，要么是一个测试用例的编写。每个任务在 Obsidian 里是一条独立的笔记，包含任务描述、输入依赖、预期输出、验收标准四个字段。Claude Code 每次只处理一个任务，完成后把结果写回笔记，然后 Harness 决定下一个任务是什么。
这种粒度控制的好处是，每一步的输入输出都很明确，出了问题容易回滚，也容易定位是哪一步出的错。热搜词里 agent 项目、吴恩达 agent 教程、pi agent、hermes agent，这些内容讨论的其实都是 Agent 任务分解的方法论。不同框架的叫法不一样，但核心思路是一致的：把复杂任务拆成可验证的小步骤。
注意：任务分解的粒度不是越细越好。如果一个任务小到“改一个变量名”，那 Agent 在上下文切换上的开销会远大于任务本身的价值。我的经验是，一个任务的工作量控制在模型单次输出能完成的范围内，通常是几百到几千 token 的产出量。
3.3 错误恢复：Agent 卡住了怎么办
Agent 跑长任务，出错是常态。常见的错误包括：模型输出格式不符合预期、工具调用失败、上下文超限、任务陷入死循环。Harness 架构必须有一套错误恢复机制，否则一个任务卡住，整个项目就停摆了。
这个项目里的错误恢复策略分三级。第一级是重试，对于偶发性的格式错误或工具调用失败，直接重试一到两次，大多数情况下能解决。第二级是回退，如果重试无效，把任务状态回退到上一个检查点，重新加载上下文，换一种提示词策略再试。第三级是人工介入，如果回退也解决不了，Harness 会把任务标记为“阻塞”，在 Obsidian 里生成一条待办笔记，等人来处理。
热搜词里 harness failed to load plugins、agent execution terminated due to error、codex 无法发送消息、显示更新 agent 沙盒，这些报错信息对应的就是不同级别的错误。插件加载失败通常是环境配置问题，Agent 执行终止通常是上下文或权限问题，消息发送失败通常是网络或接口问题。排查的时候要按这个顺序去定位：先看环境，再看上下文，最后看网络。
4. 实操过程：从零搭起一套能跑二十万行代码的 Harness 系统
4.1 环境准备与工具链搭建
第一步是把基础环境搭起来。你需要一台性能还过得去的开发机，内存至少 32G，因为 Obsidian 加上 Claude Code 加上各种开发工具，内存占用不小。操作系统不限，Windows、macOS、Linux 都可以，但建议用 macOS 或 Linux，因为命令行工具的支持更好。
工具链的核心是三个：Obsidian、Claude Code、以及一个代码编辑器（VS Code 或 Cursor 都行）。Obsidian 去官网下载安装，热搜词里 obsidian 下载、obsidian 安装、obsidian 教程这些内容可以帮助你快速上手。Claude Code 的安装方式根据平台不同有所差异，热搜词里 claude code 安装、安装 claude code、vscode 安装 claude code、vscode 配置 claude code 这些内容覆盖了主流场景。
安装完成后，需要做几项配置。Obsidian 里要开启“本地文件优先”模式，确保所有笔记都是纯 Markdown 文件，方便 Agent 直接读写。Claude Code 要配置好工作目录，指向你的项目根目录。VS Code 里建议安装 Markdown 相关的插件，比如 Markdown Preview Enhanced，方便预览 Agent 生成的文档。
# 以 macOS 为例，检查基础环境 node --version # 建议 18 以上 git --version # 版本管理必备 python3 --version # 部分工具依赖环境搭好之后，先别急着写代码。花半天时间把 Obsidian 的目录结构规划好。我的建议是分成四个顶层目录：docs放设计文档，tasks放任务笔记，logs放运行日志，src放实际代码。每个目录下面再按模块分子目录。这个结构一旦定下来，后面就不要轻易改，因为 Agent 的上下文加载策略会依赖这个结构。
4.2 用 Obsidian 搭建项目管理台账
Obsidian 在这个项目里不只是笔记软件，它是整个项目的“指挥中心”。具体怎么用？我把它分成三个功能区。
第一个功能区是“模块地图”。每个功能模块在 Obsidian 里有一条主笔记，笔记里用双链列出这个模块依赖的其他模块、被哪些模块依赖、相关的设计文档、相关的任务列表。这样你打开任意一个模块笔记，就能看到它在整个项目里的位置和关系。热搜词里 obsidian 创建项目管理台账，说的就是这个用法。
第二个功能区是“任务看板”。用 Obsidian 的 Dataview 插件，可以把tasks目录下的所有任务笔记聚合成一个看板视图，按状态（待办、进行中、阻塞、完成）分组。每个任务笔记的 frontmatter 里写上状态、优先级、所属模块、预计工作量。Harness 每次启动时，先读这个看板，决定当前该处理哪个任务。
第三个功能区是“经验库”。每次调试解决的问题、每次发现的坑、每次总结的技巧，都写成一条独立的笔记，打上标签。这些笔记在后续任务中会被 Harness 作为上下文加载，避免重复踩坑。热搜词里 weknora 和 obsidian、codex obsidian、obsidian 的 docxer 怎么用，这些都是在探索 Obsidian 和其他工具的联动方式，思路是一样的：让知识沉淀下来，让 Agent 能复用。
--- status: in-progress priority: high module: auth estimate: 2h --- # 任务：实现用户登录接口的参数校验 ## 输入依赖 - [[auth-module-design]] - [[api-convention]] ## 预期输出 - `src/auth/validator.py` 中的 `validate_login_params` 函数 ## 验收标准 - 用户名长度 3-32 字符 - 密码长度 8-64 字符 - 返回结构化错误信息上面这个任务笔记的模板，我在项目里用了九个月，几乎没有改过。frontmatter 里的字段是给 Harness 读的，正文是给人和模型读的。这种“人机双读”的设计，是 Markdown 作为知识载体的最大优势。
4.3 配置 Claude Code 作为执行引擎
Claude Code 的配置核心是两件事：工作目录和权限。工作目录要指向项目根目录，这样它才能读写docs、tasks、src这些目录。权限方面，建议开启文件读写和命令执行权限，但要对危险命令做白名单限制。热搜词里 claude code 使用、claude code 下载、claude code desktop 国内下载，这些内容可以帮助你完成基础配置。
配置好之后，先做一个最小验证：让 Claude Code 读一个 Markdown 文件，然后根据文件内容生成一个简单的 Python 脚本。如果这一步能跑通，说明基础链路没问题。如果报错，优先检查工作目录和权限配置。
# 在项目根目录启动 Claude Code cd /path/to/project claude # 在交互界面里输入 # 读取 tasks/example-task.md，根据任务描述生成对应的代码文件验证通过后，就可以把 Harness 的调度逻辑接进来了。Harness 的核心是一个循环：读任务看板，选一个待办任务，加载上下文，调用 Claude Code，收集输出，更新任务状态，写日志。这个循环可以用 Python 写，也可以用 Shell 脚本写，关键是逻辑要清晰，错误处理要完善。
4.4 参数计算与 token 预算控制
每月四十亿 token 的消耗，如果不做预算控制，很容易失控。我的做法是给每个任务设置 token 预算，超出预算就暂停并报警。预算的计算方式是：任务预计产出量乘以一个系数，再加上上下文加载的预估量。系数根据任务类型调整，代码生成类任务系数高一些，文档整理类任务系数低一些。
具体来说，一个中等复杂度的代码生成任务，预计产出五百行代码，每行平均二十 token，就是一万 token。上下文加载预估五千 token。系数取三，总预算就是四万五千 token。如果实际消耗超过这个数，说明任务分解粒度有问题，或者上下文管理有漏洞，需要回头检查。
这个预算机制在九个月里帮我省下了大量不必要的消耗。热搜词里 deepseek harness、deepseek harness 安装、deepseek harness 插件、deepseek harness 用 skill、deekseek harness，这些内容说明很多人也在探索不同模型和 Harness 的结合方式。不管用哪个模型，预算控制的思路是一样的：先算清楚一笔账，再决定怎么花。
5. 常见问题与排查技巧实录
5.1 Agent 跑着跑着就卡住不动了
这是最常见的问题。表现是 Claude Code 或者 Harness 循环突然没有输出，日志停在某一行不再更新。原因通常有三个：上下文超限、工具调用死循环、模型接口超时。
排查顺序是这样的。先看日志最后一行是什么操作，如果是上下文加载，那大概率是上下文超限，需要检查当前任务的上下文大小，看看是不是加载了过多不必要的信息。如果是工具调用，检查是不是陷入了“调用-失败-重试-再调用”的死循环，这时候需要给重试次数设上限。如果是模型接口调用，检查网络连接和 API 配额。
提示：给 Harness 加一个“心跳检测”机制，每隔三十秒检查一次任务状态，如果超过五分钟没有进展，自动触发回退。这个机制在九个月里帮我自动恢复了上百次卡死。
5.2 Markdown 解析出错导致上下文混乱
Markdown 虽然简单，但解析起来也有坑。最常见的是换行问题，热搜词里 markdown 换行、markdown 语法、markdown 表格复制、markdown 表格转换 excel，这些都是在讨论 Markdown 的细节。在 Agent 工作流里，一个换行符处理不当，就可能导致整个段落被解析成代码块，进而导致上下文加载错误。
我的做法是制定一份严格的 Markdown 规范，所有文件必须遵守。比如：标题必须用 ATX 风格（##而不是下划线），列表必须用-而不是*，代码块必须标注语言，表格必须对齐。这份规范放在docs目录下，Harness 每次加载上下文时先读这份规范，确保解析一致性。
5.3 任务状态不同步，Agent 重复劳动
这个问题在多任务并行的时候特别容易出现。表现是 Agent 反复处理同一个任务，或者跳过了某个已完成的任务。根因是任务状态没有及时同步到 Obsidian 的看板里。
解决办法是给任务状态更新加一个“写后读”校验：每次更新任务状态后，立即重新读取看板，确认状态已经生效。如果没生效，重试更新。这个机制看起来笨，但非常有效。热搜词里 agent execution terminated due to error、显示更新 agent 沙盒，这些报错有时候就是状态同步失败导致的。
| 问题现象 | 可能原因 | 排查方法 | 解决措施 |
|---|---|---|---|
| Agent 无输出 | 上下文超限 | 检查日志最后操作 | 缩减上下文，重试 |
| 任务重复执行 | 状态未同步 | 检查看板状态 | 加写后读校验 |
| Markdown 解析错 | 语法不规范 | 检查文件格式 | 统一 Markdown 规范 |
| 插件加载失败 | 环境配置问题 | 检查插件目录 | 重装或更新插件 |
| 接口调用超时 | 网络或配额 | 检查网络和配额 | 重试或切换模型 |
5.4 独家避坑技巧：三个我踩过的坑
第一个坑是“过度依赖模型记忆”。早期我试图让模型记住整个项目的架构，结果上下文经常超限。后来改成“按需加载”，每个任务只加载相关模块的信息，问题就解决了。模型不需要知道整个项目，它只需要知道当前任务需要知道的部分。
第二个坑是“任务描述太模糊”。比如“优化登录模块”这种任务，模型根本不知道从哪下手。后来我强制要求每个任务必须有明确的输入依赖和验收标准，任务描述必须具体到函数级别。这个改变让任务成功率从六成提升到了九成以上。
第三个坑是“忽略日志”。早期我不怎么看 Harness 的运行日志，出了问题就重启。后来发现日志里其实记录了每一步的上下文大小、token 消耗、工具调用结果，这些信息对优化系统非常关键。现在我会定期分析日志，找出 token 消耗异常的任务，回头优化任务分解策略。
6. 这套方法能复制到什么程度
九个月下来，我的体会是：Harness 架构加 Markdown 加 Obsidian 加 Claude Code 这套组合，确实能把一个人的产出放大到接近一个小团队的水平，但它不是魔法。它放大的是你的架构能力和判断力，而不是替代它们。如果你自己都说不清楚一个模块该怎么设计，Agent 也帮不了你。如果你能把设计写清楚，Agent 就能帮你把设计变成代码，而且速度很快。
这套方法最适合的场景是：需求相对明确、模块边界清晰、有大量重复性编码工作的项目。比如后端服务、数据处理管道、工具类应用。不太适合的场景是：需求高度不确定、需要大量探索性试错、强依赖人类直觉和审美的项目。比如前沿算法研究、交互设计创新。
热搜词里 harness anything、harness engineering、agent 开发、ai agent，这些词的热度说明这个方向正在被越来越多的人关注。但工具和框架只是表象，真正决定成败的是你对项目的理解深度，以及你把这些理解转化成清晰 Markdown 文档的能力。二十万行代码不是目的，四十亿 token 也不是目的，目的是用这套方法把你想做的东西做出来。
最后分享一个小技巧：每周花半小时回顾 Obsidian 里的经验库，把重复出现的坑合并成一条，把过时的经验删掉。这个习惯让我的 Harness 系统在九个月里越来越稳，token 消耗越来越低，任务成功率越来越高。系统是养出来的，不是一次搭出来的。
