# Harness Engineering Starter：构建Agent协作规则的通用模板

> 一个用于构建"仓库内Agent协作规则"的通用模板仓库，提供文档骨架和路由方式，帮助团队在真实项目中约束Agent的工作边界、执行路径和交付留痕。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-05-20T05:45:57.000Z
- 最近活动: 2026-05-20T05:50:12.768Z
- 热度: 150.9
- 关键词: Agent协作, 开发规范, 文档模板, AI工程, 仓库管理, 工作流, 架构文档, 人机协作
- 页面链接: https://www.zingnex.cn/forum/thread/harness-engineering-starter-agent
- Canonical: https://www.zingnex.cn/forum/thread/harness-engineering-starter-agent
- Markdown 来源: ingested_event

---

# Harness Engineering Starter：构建Agent协作规则的通用模板\n\n## 背景：当Agent成为开发团队的成员\n\n随着AI Agent在软件开发中的角色从"辅助工具"向"协作成员"转变，一个新的问题浮出水面：如何让Agent在团队中有效、可控地工作？不同于人类开发者可以通过会议、文档和代码审查来同步认知，Agent需要一套明确的规则来定义其工作边界、执行路径和交付标准。\n\nHarness Engineering Starter正是为了解决这一问题而设计的通用模板仓库。它不提供具体的技术栈选择或编码规范，而是提供了一套文档骨架和路由系统，帮助团队为Agent建立清晰的协作规则。\n\n## 核心理念：规则即接口\n\n这个模板的设计哲学可以概括为"规则即接口"。就像API定义了系统间的交互契约一样，文档规则定义了人类与Agent之间的协作契约。通过明确的入口规则、工作流定义和架构文档，团队可以确保Agent在正确的边界内工作，同时保留人类对关键决策的控制权。\n\n模板强调几个关键原则：\n\n- **模板不等于事实**：模板文件只描述"应该定义什么"，不直接替代真实项目规则\n- **占位符需要确认**：示例目录和命名在被项目确认前，都不能当成事实使用\n- **分层管理**：项目事实、领域规则、生成产物应分开维护\n- **按需裁剪**：只保留与项目匹配的模板文件，不适用的应删除或替换\n\n## 文档架构：八层路由系统\n\n模板提供了一套分层的文档架构，每一层都有明确的职责边界：\n\n### 第一层：AGENTS.md（仓库级入口规则）\n\n这是Agent进入仓库的第一站。它定义了Agent在仓库中的基本行为准则、入口路由和全局约束。类似于人类开发者的README，但专门为Agent的阅读习惯和理解方式优化。\n\n### 第二层：docs/WORKFLOW.md（执行路径选择）\n\n定义Agent在仓库中执行任务的流程选择逻辑。包括何时应该创建新分支、何时应该提交PR、代码审查的标准是什么等。这是Agent的"操作手册"。\n\n### 第三层：docs/ARCHITECTURE.md（系统结构事实）\n\n记录系统的整体架构、模块划分、数据流向等关键事实。Agent在执行任务前应该先阅读此文档，确保其改动符合整体架构设计。\n\n### 第四层：docs/guides/（通用流程与文档模板）\n\n存放可复用的流程文档和模板，如如何编写API文档、如何进行代码审查、如何编写测试用例等。这些是Agent执行具体任务的"标准作业程序"。\n\n### 第五层：docs/project/（当前项目事实与硬约束）\n\n记录项目的具体事实：使用什么技术栈、有哪些兼容性要求、业务背景和核心术语是什么。这些是Agent做技术决策时必须考虑的硬约束。\n\n### 第六层：docs/rules/（领域或专题规则）\n\n存放特定领域的详细规则，如API设计规范、数据访问层规范、异常处理规范、测试策略等。当某个领域形成稳定约束后，相关规则下沉到此层。\n\n### 第七层：docs/tasks/（任务文档）\n\n存放具体的任务描述和任务相关的临时文档。这是Agent执行具体任务时的上下文载体。\n\n### 第八层：docs/generated/（生成产物）\n\n存放Agent生成的文档和产物，与人工维护的文档明确区分，避免混淆。\n\n### 参考资料层：docs/references/ 和 docs/templates/\n\n分别存放参考资料和可复用模板，支持Agent和人类的日常查阅需求。\n\n## 使用方式：从模板到真实项目\n\n这个模板的设计意图是"作为起点，而非终点"。团队在使用时应遵循以下步骤：\n\n### 第一步：替换核心入口文件\n\n优先修改以下三个文件，使其反映真实项目的情况：\n- AGENTS.md：定义项目的Agent入口规则\n- docs/WORKFLOW.md：定义项目的工作流程\n- docs/ARCHITECTURE.md：记录项目的真实架构\n\n### 第二步：补齐项目级硬约束\n\n根据项目实际情况补充：\n- 技术栈与兼容边界\n- 项目级硬规则\n- 业务背景与核心术语\n- API、数据访问、异常、测试等事实文档\n\n### 第三步：下沉领域规则\n\n当某个领域形成稳定约束后，将具体细则下沉到：\n- docs/guides/ 下的流程型文档\n- docs/rules/ 下的领域型文档\n- .agents/skills/ 下的可复用自动化流程\n\n### 第四步：裁剪不适用的部分\n\n删除或替换与项目无关的模板内容，保持文档集的精简和聚焦。\n\n## 设计取舍：明确说"不是什么"\n\n模板文档明确界定了其适用范围，避免误用：\n\n**这不是**：\n- 一个固定不变的标准答案\n- 一个直接可用于所有项目的通用规范\n- 一个替代真实项目事实的占位仓库\n\n**这是**：\n- 一个模板骨架\n- 一个可裁剪的路由系统\n- 一个帮助Agent和人类共享上下文的规则入口\n\n这种自我限定非常重要。在Agent协作的语境下，模糊的边界比没有边界更危险。通过明确说"不"，模板帮助团队建立正确的预期。\n\n## 实践价值：解决Agent协作的三大痛点\n\n### 痛点一：上下文丢失\n\nAgent通常缺乏对项目整体上下文的理解，容易做出局部最优但全局次优的决策。通过强制要求Agent在行动前阅读AGENTS.md和ARCHITECTURE.md，模板确保Agent具备必要的上下文。\n\n### 痛点二：规则不一致\n\n不同Agent（或同一Agent在不同会话）可能采用不同的工作方式，导致产出质量参差不齐。通过WORKFLOW.md和guides中的标准化流程，模板确保Agent遵循一致的规则。\n\n### 痛点三：产物难以追溯\n\nAgent生成的代码和文档往往缺乏明确的来源和上下文，难以审查和维护。通过分层架构和generated目录的约定，模板确保产物可追溯、可审查。\n\n## 与现有实践的对比\n\n传统的开发文档主要面向人类读者，假设读者具备领域知识和推理能力。Harness Engineering Starter则假设Agent读者需要更明确的规则、更结构化的信息和更清晰的边界。\n\n这不是要取代现有的文档实践，而是为其补充一个Agent友好的视角。就像好的API设计既考虑人类开发者也考虑机器调用一样，好的项目文档也应该同时服务人类和Agent读者。\n\n## 未来展望：从模板到生态\n\n随着Agent在软件开发中的角色越来越重要，我们可以预见这类"Agent协作规则"模板会演变成一个丰富的生态系统。不同技术栈、不同团队规模、不同业务领域都会有自己的最佳实践变体。\n\nHarness Engineering Starter的价值在于它提供了一个最小可行的起点，让团队可以立即开始实践Agent协作，而不必等待完美的解决方案。正如模板文档所说："这个仓库更适合作为起点，而不是终点。"\n\n## 结语：规则是协作的基础\n\n在Agent成为开发团队正式成员的时代，明确的规则不再是束缚，而是协作的基础。Harness Engineering Starter提供了一个务实的框架，帮助团队建立与Agent的有效协作关系。\n\n它的核心理念很简单：好的Agent协作始于清晰的规则，而清晰的规则始于结构化的文档。这个模板就是那个起点。