在上一篇【AI技术】Vibe Coding 实践指南：从项目规划到高效开发-CSDN博客中，介绍了如何利用 AI 编程工具进行项目规划、任务拆分和代码开发。
但当 AI 开始参与更复杂的项目时，仅仅让它能够编写代码还不够。如何管理 AI 的运行过程？如何让它遵守项目规范？当项目持续迭代、开发会话不断切换时，又该如何保留已有的技术经验？
这些问题涉及一个值得进一步了解的概念：Harness。本文将先简要介绍 Harness 的作用，再结合 DeepSeek Harness（以下简称 DSH）的相关实践，探讨 AI 编程项目如何通过规则、文档和决策笔记实现更好的长期维护。
一、从 Vibe Coding 到 Harness
随着 AI 编程工具的发展，开发者已经可以通过自然语言描述需求，让 AI 分析代码、生成实现方案，甚至执行测试和调用外部工具。
但模型能够生成代码，不代表它就能独立、稳定地完成整个开发任务。
例如，当 AI 修改一个现有项目时，它需要了解项目结构、遵守开发规范、决定何时调用工具，并在修改后检查结果。
如果缺少必要的约束和执行机制，即使模型本身具有较强的编程能力，也可能出现重复实现、遗漏测试或误改其他模块等问题。
因此，AI 编程不仅涉及模型能力，还涉及如何组织和管理模型的运行过程。
1. 什么是 Harness？
Harness 可以理解为围绕 AI 模型构建的一套运行与控制机制。
它可以根据具体产品的设计，负责组织指令和上下文、提供工具调用能力、管理执行流程，并通过权限控制、结果检查等机制约束 AI 的行为。
可以简单理解为：
**模型（Model）**负责理解输入并生成输出。
Agent负责围绕目标进行规划、调用工具和推进多步骤任务。
Harness为这些行为提供运行环境、执行机制和必要的约束。
这是一种便于理解的功能划分，并不是严格统一的技术标准。实际产品中，Agent 与 Harness 的职责往往存在交叉，具体能力也取决于产品实现。
例如，AI 编程工具除了调用模型，还可能需要读取项目文件、执行终端命令、管理上下文，以及根据执行结果决定下一步操作。这些环节共同构成了一个更完整的 AI 编程环境。
因此，Harness 并不只是一个模型 API 的封装。它更值得关注的地方，是如何把模型能力组织成可执行、可控制的工作流程。
2. 为什么要研究 Harness？
如果说 AI IDE 主要帮助开发者完成代码编辑、理解代码和项目开发，那么进一步研究 Harness，就可以关注 AI 在这些工具背后是如何运行的。
例如：
AI 如何获取当前任务需要的上下文？
工具调用如何被组织和执行？
如何限制 AI 的操作范围？
如何让 AI 遵循项目约定？
当任务执行失败时，如何继续处理或验证结果？
这些问题不仅与编程工具有关，也与 AI 在企业办公自动化、数据处理和业务流程中的应用有关。
当 AI 从简单的问答逐渐走向多步骤任务执行时，运行机制与工程约束的重要性也会随之提高。
接下来，我们以 DeepSeek Harness 为例，看看一个 AI 编程项目可以如何管理自己的开发知识。
二、DeepSeek Harness：从运行机制到项目维护
DeepSeek Harness（DSH）是本文讨论的具体案例。
一方面，Harness 关注 AI 如何在一定的运行机制下执行任务；另一方面，项目维护机制关注 AI 执行任务时，应该依据哪些规则、了解哪些系统事实，以及如何利用过去积累的经验。
两者相互配合，但并不是同一回事。
Harness 本身并不能自动保证项目结构合理，也不能保证文档永远准确。要让 AI 更好地参与长期开发，还需要开发者主动组织和维护项目知识。
在 DSH 的相关实践中，有三个值得重点关注的方向：
使用
AGENTS.md等规则文件约束开发行为。使用
docs/等文档组织项目知识。使用
.agents/notes/等笔记机制记录重要决策和历史经验。它们分别对应规则、事实与决策。
三、规则、事实与决策：为什么需要分开管理？
在 AI 编程项目中，规则文件、技术文档和开发笔记很容易混在一起。
例如，一份项目说明可能同时包含代码规范、接口定义、架构设计、历史 Bug 和技术选型原因。项目规模较小时，这种方式似乎没有问题；随着内容增加，查找和维护就会越来越困难。
更合理的做法，是根据不同信息的用途进行分类。
| 信息类型 | 核心问题 | 典型内容 |
|---|---|---|
| 规则 | AI 应该怎么做？ | 编码规范、修改约束、测试要求 |
| 事实 | 当前系统是什么样？ | 架构、接口、数据结构、运行方式 |
| 决策 | 为什么采用当前方案？ | 技术取舍、替代方案、历史经验 |
这种分类的意义，在于让不同信息各自承担明确的职责。
当项目架构发生变化时，应该更新描述当前系统的文档；当技术选型发生变化时，可以记录新的决策及其原因；当开发规范需要调整时，则应修改相应的规则。
如果所有内容都堆积在一个文件里，后续维护就容易出现重复记录、信息过时和规则相互冲突等问题。
四、AGENTS.md：让项目规则更加明确
AGENTS.md 是一种供 AI 编程工具读取的项目指令文件，可以用来描述项目中的开发约定。
例如，一个项目可以在规则文件中要求 AI：
优先遵循现有架构，避免无必要的重构。
修改代码前，先检查是否存在可复用的模块。
避免重复实现已有功能。
修改接口或数据结构时，检查相关文档是否需要更新。
根据修改范围执行适当的测试，并说明尚未验证的内容。
这些规则能够帮助 AI 在执行任务时遵循统一的开发约定，而不是每次都根据当前需求临时决定实现方式。
规则文件应该写多长？
规则并不是越多越好。
如果把所有接口说明、代码细节、操作手册和历史问题都放进 AGENTS.md，文件就会逐渐变成一份难以维护的项目百科。
更合理的方式是：
主规则文件负责通用约束和必要的文档索引。
特定模块的约束放在对应的规则文件中。
详细技术信息放在项目文档中。
历史决策和经验教训放在专门的笔记中。
这样既可以保持主规则文件简洁，也可以让 AI 根据当前任务读取需要的信息。
需要注意的是，AGENTS.md 并不是所有 AI 编程产品都统一强制使用的配置文件。不同工具对规则文件的命名、加载范围和执行方式可能有所不同，应以具体工具的实现为准。
五、docs：让 AI 理解项目当前的状态
规则文件告诉 AI 应该遵守什么约定，但它不能代替对项目本身的描述。
假设一个项目使用 Python 处理业务数据，AI 需要知道输入文件包含哪些字段、数据经过哪些处理步骤、不同模块如何协作，以及最终结果应该是什么格式。
如果这些信息没有被清晰记录，AI 就只能在每次任务中重新分析代码，或者依赖开发者补充说明。
项目文档可以帮助解决这个问题。
常见的文档分类包括：
| 文档类型 | 主要作用 |
|---|---|
| 架构文档 | 介绍整体结构、模块职责和依赖关系 |
| 子系统文档 | 描述特定模块的逻辑、接口和约束 |
| 操作手册 | 记录启动、调试、测试和部署方法 |
| 问题复盘 | 记录重要故障的原因和改进措施 |
例如，当 AI 需要修改数据导出功能时，可以先读取该模块的输入输出约定，而不必重新分析整个项目。
当任务涉及部署环境时，则可以重点查看部署说明。
这里值得注意的是，文档的目的不是复制代码，而是帮助开发者和 AI 更快地理解代码。
如果文档中包含大量重复的接口列表、过时的实现细节或已经失效的操作步骤，不仅增加维护成本，也可能误导 AI。
因此，项目文档需要尽量保持准确，并在重要代码变更后及时同步更新。
六、Agent Notes：为什么还要记录技术决策？
如果说规则解决了行为约束问题，文档解决了当前系统的描述问题，那么还有一个容易被忽略的问题：
为什么项目最终采用了当前方案，而不是其他方案？
这正是决策笔记的价值所在。
在 DSH 的相关讨论中，.agents/notes/ 是值得关注的笔记组织方式之一。它可以用于保存重要的技术取舍、问题解决经验和历史决策。
这里的关键不是目录名称，而是为这些具有长期参考价值的信息提供明确的位置。
1. 只记录结果还不够
假设一个项目需要处理大量 Excel 数据。
开发者最初考虑使用低代码工作流，但测试后发现，复杂的数据清洗和批量处理逻辑更适合使用 Python 脚本实现。
如果只保留最终代码，未来的 AI 可能不知道为什么选择 Python，也不知道此前评估过哪些替代方案。
一份决策笔记可以记录：
背景：当时需要解决什么问题。
决策：最终采用了什么方案。
原因：选择该方案的依据。
替代方案：评估过哪些其他方案，以及没有采用的原因。
影响：这一决定对后续开发有哪些约束。
这样，未来的 AI 不仅能看到当前的实现，还能理解当初的技术取舍。
2. 为什么失败的方案也值得记录？
开发过程中，被放弃的方案往往比最终实现更容易被遗忘。
例如，某种方案可能存在性能不足、维护成本过高、依赖特定平台或难以适配现有架构等问题。
如果这些原因没有被记录，未来的 AI 就可能再次尝试同样的方案，重复之前已经付出的时间和成本。
决策笔记可以将这些经验转化为可复用的信息，帮助后续开发者减少重复试错。
不过，记录失败方案并不意味着永远禁止重新尝试。随着业务需求、技术能力和依赖版本发生变化，过去不合适的方案也可能重新变得可行。
因此，笔记应该记录当时的背景和判断依据，而不是简单地把某个方案标记为永久不可用。
3. 什么时候需要写 Notes？
不是每一次代码修改都值得记录。
调整按钮样式、修复简单的变量错误，通常没有必要单独编写决策笔记。
更适合记录的情况包括：
重要的技术选型。
涉及多个模块的架构调整。
复杂问题的排查与解决。
容易重复出现的问题及其解决经验。
会影响后续开发方式的重要技术约束。
判断标准很简单：如果未来的开发者或 AI 可能因为不了解这次决策的原因而重复犯错，那么这项信息就值得保留。
七、当项目持续演进，如何避免文档过时？
规则、文档和决策笔记并不是建立完成后就可以永久不管的东西。
随着代码不断迭代，旧文档可能与当前实现不一致，过去的技术决策也可能不再适用。
因此，项目维护不仅需要积累知识，还需要持续更新知识。
1. 当前事实与历史决策分开
架构文档应该主要描述当前系统。
如果项目已经从方案 A 迁移到方案 B，当前架构文档就应该反映方案 B。
至于为什么进行迁移、为什么放弃方案 A，则可以保留在决策笔记中。
这样既能让读者快速理解当前系统，也不会丢失重要的历史原因。
2. 重要变更后同步更新文档
当代码修改涉及架构、接口、数据结构或关键处理流程时，应检查相关文档是否需要更新。
不必要求每一次小型修改都产生新的文档，但应避免重要变更已经完成，文档却仍然停留在旧版本。
3. 新决策说明与旧决策的关系
当项目需要推翻原有方案时，可以新增一条决策记录，说明新的背景、变化原因以及对旧方案的替代关系。
旧记录可以保留为历史信息，但应明确标记其状态，避免未来的 AI 将过时的决策误认为当前约定。
4. 通过测试验证实际结果
文档描述的是系统事实、开发约定或预期行为，最终实现仍然需要通过代码检查、自动化测试和必要的人工审查进行验证。
不能因为规则写得完整，就认为 AI 一定会遵守所有约束；也不能因为文档看起来准确，就认定实际代码没有问题。
规则、文档、决策笔记与测试需要相互配合，才能共同支撑长期维护。
八、普通开发者可以借鉴什么？
研究 DSH 的意义，并不是照搬它的所有目录结构，而是理解这些工程实践背后的目的。
对于个人开发者和中小型项目，可以从三个方面开始。
第一步：建立清晰的项目规则
完善 AGENTS.md 或当前 AI 编程工具支持的项目规则文件，明确基本架构约束、依赖管理原则、测试要求和文档更新约定。
保持主规则简洁，避免把所有技术细节都塞进去。
第二步：维护一份可靠的架构文档
先记录项目用途、核心模块、主要数据流和关键依赖。
随着项目复杂度增加，再逐步补充接口、数据库、部署和子系统文档。
第三步：只为重要决策建立笔记
在进行重要技术选型、解决复杂问题或调整架构时，记录背景、最终决策、选择原因以及被放弃的方案。
普通的小型修改则不必强行增加文档。
对于规模较大的项目，还可以逐步引入自动化测试、文档检查和持续集成，降低文档过时与实现偏离的风险。
需要强调的是，这些做法会带来额外的维护工作。项目越小，越应该控制规则和文档的复杂度；只有当项目开始出现明显的重复试错、知识丢失或维护困难时，才有必要进一步完善这套机制。
总结
从 Vibe Coding 到 Harness，我们关注的问题逐渐从如何使用 AI 提高开发效率，扩展到如何组织 AI 的运行过程，以及如何让 AI 长期参与同一个项目。
Harness 提供了组织和约束 AI 执行过程的机制，而 DSH 的相关实践则进一步展示了项目规则、技术文档和历史决策在长期维护中的价值。
AGENTS.md负责约束开发行为，docs/负责描述当前系统，Agent Notes 负责保存重要的技术取舍和历史经验。再结合测试与代码审查，这些机制能够帮助开发者减少重复实现、重复试错和文档失效带来的维护成本。
对于个人开发者而言，不必一开始就建立复杂的工程体系。把规则写清楚、把关键架构记录下来、把重要决策沉淀下来，再根据项目规模逐步完善，就已经是一个值得尝试的起点。
AI 编程的价值不仅在于更快地生成代码，还在于让项目能够持续演进，让开发经验能够被继承。