最近我重新整理 Better Harness 的 references 目录时，发现一个有意思的问题：里面积累的实践越来越完整，但第一次接触 Coding Agent 工程化的人，反而更难判断应该先做什么。

如果你已经让 Coding Agent 修改过真实项目，大概见过这样的场景：它能很快找到代码、完成修改，甚至运行测试；但换一次对话，又要重新猜测项目使用什么命令、 哪些文档可信、哪些文件不能修改。你不断补充 Prompt，项目里的经验却没有真正留下来。

问题不只是 Agent 缺少上下文，而是项目还没有把自己的工作方式，变成 AI 可以发现、执行和验证的工程接口。

AGENTS.md、核心文档、Skill、CLI、MCP、Hook、测试与权限，分别解决这条路径上的不同问题。单独看，它们像一组不断增加的配置；放回项目的成长过程，顺序其实很清楚：

写清项目入口 → 连起核心知识 → 沉淀重复流程 → 接入执行工具 → 回到真实任务

阶段	要解决的问题	主要产物
进入项目	Agent 不知道怎样开工	AGENTS.md
理解项目	文档存在，但任务中找不到	知识路由
复用经验	同类流程需要反复解释	Skill
执行流程	方法有了，却缺少可靠工具	CLI、MCP、Hook
持续改进	这次经验没有进入下一次任务	Agent Work Loop

一个 Agent 友好的项目，不是安装了多少工具，而是项目知识能否被发现，流程能否被执行，结果能否被验证，经验能否进入下一次任务。

第一步：先用 AGENTS.md 给 Agent 一张项目地图

假设一个新人第一天加入项目，我们通常不会直接递给他全部架构文档，而会先告诉他：项目做什么、代码在哪里、怎样启动、修改后运行什么测试，以及哪些地方不要碰。

Coding Agent 进入仓库时，也需要这样一张地图。这是 AGENTS.md 最容易理解的用途。

不同 Coding Agent 对文件名和加载范围的支持有所不同，但 AGENTS.md 承担的内容应该尽量稳定：项目使用的包管理器和运行时、安装与测试命令、无法从目录结构推断的约定、生成文件的位置，以及涉及凭据、数据库迁移和发布时的安全边界。

Agent 能从代码中看出来的内容，没有必要再写一遍。真正值得写进去的，是它看不出来、却很容易猜错的事实。例如：

• 仓库里同时存在 npm 和 pnpm 的痕迹，当前究竟使用哪一个；
• 某个目录看起来像源码，实际上由工具生成；
• 完整测试需要半小时，修改一个模块时应该先运行哪条聚焦命令。

如果还不知道怎样起步，可以先在仓库根目录创建一份很短的 AGENTS.md：

# AGENTS.md

- 安装依赖：`pnpm install`
- 修改后先运行：`pnpm test -- <相关测试>`
- 不要直接修改：`dist/`、`generated/`
- 修改模块边界前：阅读 `docs/ARCHITECTURE.md`
- 涉及数据库迁移或发布：先请求人工确认

这只是最小示意，命令和路径必须替换为项目中真实可用的内容，并且亲自运行一遍。

一份实用的 AGENTS.md 应该简短、准确、可执行，并且与当前项目直接相关。AGENTS.md Review 还强调了一个重要原则：渐进式披露。根目录只保留多数任务都需要的说明，更详细的架构、设计和工作流程，通过链接按需读取。

第一步不必追求一份完美的 Agent 手册。先写清入口、命令、风险和文档导航，让 Agent 能够正确进入项目。

第二步：把核心文档接到任务路径上

有了项目地图，Agent 只是知道怎样开工，还不知道代码为什么这样组织。真正影响修改质量的知识，仍然散落在架构决策、设计规范、测试策略和运行手册中。

第二步要做的，是让这些文档从“仓库里存在”，变成“任务进行到这里时能够被找到”。

常见的核心文档包括 ARCHITECTURE.md、DESIGN.md、编码规范、测试指南、发布说明和 Runbook。名字不必统一，但职责应该清楚：架构文档解释模块边界和依赖方向，设计文档保存界面与交互约束，编码规范记录团队特有的技术选择，测试与运行手册说明如何验证和诊断系统。

只在 AGENTS.md 末尾放一串链接还不够。更有效的写法，是同时给出读取条件：

• 修改模块边界前，阅读 ARCHITECTURE.md；
• 调整公共界面前，检查 DESIGN.md；
• 改变发布流程前，阅读 Runbook。

这一小句把文档接到了具体任务上，也形成了一条最小的知识路由。

同一个事实最好只有一个权威来源。架构约束属于架构文档，AGENTS.md 只负责把 Agent 带过去；测试命令如果已经由脚本提供，文档负责解释如何选择，而不是再复制一份可能过期的命令。Knowledge Asset Review 因此关注的不是文档数量，而是面对具体任务时，一份知识能否被找到、是否仍然准确、读完以后能否采取行动。

到了这一步，AGENTS.md 负责导航，核心文档负责解释，源码和测试提供最终事实。项目开始拥有一套 Agent 可以使用的知识路由，而不再依赖一个巨大的万能 Prompt。

第三步：从重复工作中提炼第一个 Skill

文档适合解释稳定知识，但有些任务不只是“知道什么”，还包含一套反复出现的判断和步骤。

每次发布都要检查版本、变更记录和产物；每次排查线上问题都要收集日志、缩小范围并验证修复；每次代码审查都要核对最终变更、测试证据和风险边界。如果团队每次都要重新提醒 Agent，这段过程就值得被观察。

Skill 可以理解为一份由 Agent 按需加载的工作手册。它回答的是一种任务应该怎样完成：何时触发、需要哪些输入、按什么顺序执行、产出什么结果、如何验证，以及遇到什么情况应该停止并交给人。

但重复出现，不等于立即创建 Skill。一个实用的 Skill Discovery 门槛是：相似需求至少出现过两次；或者虽然只发生过一次，但成本高、风险大，并且很可能再次发生。在此基础上，还要确认输入相对稳定、步骤能够复用、结果可以检查，而且没有被现有文档、脚本或 Skill 覆盖。

如果不知道第一个 Skill 应该从哪里来，可以翻看最近几次与 Agent 的对话：

• 哪些要求已经解释过两次？
• 哪些检查每次都要手工提醒？
• 哪些失败修复以后很可能再次出现？

它们通常比一张通用的 Skill 推荐清单更值得优先处理。

例如，团队连续几次在代码审查中遇到同一类问题：Agent 只检查了未暂存的修改；测试运行在较早的代码上，最终提交又发生了变化；总结写着“测试通过”，却没有记录具体命令。与其继续往 AGENTS.md 增加提醒，不如把“审查最终变更”整理成一个 Skill，固定收集变更范围、运行对应检查、记录验证证据，并列出尚未覆盖的风险。

Prompt 解决的是这一轮怎么做；Skill 则让下一次遇到同类任务的 Agent，仍然沿着同一种方法工作。

第四步：把重复流程变成可执行的工程接口

写出 Skill，只是定义了方法。要让流程真正运行起来，Agent 还需要读取数据、执行检查或操作外部系统。

这时不必立刻增加一个 MCP Server。对于已经拥有脚本或命令行工具的项目，CLI 通常是成本最低、也最容易复现的起点。一个 Agent-friendly CLI 应该：

• 能从 --help 中发现用法；
• 支持非交互执行；
• 输出稳定，必要时提供 JSON 等结构化格式；
• 失败时返回明确的错误和退出状态；
• 为耗时操作提供超时；
• 修改外部状态前支持 plan 或 dry-run。

这样的 CLI 可以同时服务开发者、Agent、脚本和 CI，也容易在本地复现 Agent 的操作。团队已经使用 gh、kubectl 或内部运维 CLI 时，优先把这些能力整理成稳定接口，通常比为每个 Agent 宿主重新包装一套工具更轻。

CLI 优先并不意味着拒绝 MCP。当外部系统缺少合适的命令行入口，或者需要结构化资源发现、宿主集成、持续交互时，MCP 仍然合适。关键是让 CLI 与 MCP 建立在同一套底层能力和权限规则上，而不是分别定义输入、输出和错误语义。

此外，并不是所有问题都应该由 Skill 提醒。能够被程序明确判断的规则，例如禁止修改生成文件，应该交给脚本、Hook 或 CI 自动检查；涉及生产环境、凭据和不可逆操作，则继续保留权限控制、沙箱或人工确认。

Agent Customize Routing 背后的原则很简单：先建设稳定的底层能力，再为问题选择最小、最合适的承载机制。工具数量不代表成熟度；职责清楚、过程可复现、结果能验证，才说明它真正进入了工程流程。

第五步：回到真实任务，让项目记住经验

Agent 完成修改、测试显示通过时，我们很容易马上开始下一个需求。先别急着结束：打开最终代码变更，确认测试覆盖的是这次修改后的版本，再检查它是否走完了必要的 Review 和 CI。代码写完只是过程的一部分，结果能够被验证和交付，这次任务才算完成。

Better Harness 把从理解需求、找到知识、执行修改到验证交付的过程，称为 Agent Work Loop 。在这个循环中，AGENTS.md 帮助 Agent 进入项目，核心文档提供上下文，Skill 与工具推动任务执行，测试、Hook 和权限守住结果与边界。

交付以后，再回头看一眼这次任务：Agent 是否又重新寻找了一遍启动命令？是否在同一个目录上再次犯错？是否仍然需要人提醒某项检查？也要留意那些已经奏效的路径，例如某个排查步骤是否连续帮助了几次任务。

这些反复出现的摩擦和有效经验，才是下一轮改进的起点。可以借助 Loop Discovery ，判断它们应该沉淀在哪里：

• 稳定事实，写回 AGENTS.md 或核心文档；
• 重复方法，整理成 Skill；
• 确定性的操作和检查，交给 CLI、脚本、Hook 或 CI；
• 确实需要外部资源发现或持续交互时，再使用 MCP；
• 高风险、不可逆的操作，保留权限边界和人工确认。

不过，写进仓库并不代表实践已经生效。等下一次类似任务到来，Agent 能否找到它、用上它，并因此少一次返工或提醒，才决定这项实践是否值得保留。

所谓持续改进，不是不断增加配置，而是让这一次任务留下的东西，真正帮助下一次。

如果刚刚开始，就选择一个最近发生的真实任务：让 Agent 从理解需求走到验证与交付，结束时只沉淀一件最值得复用的经验。

项目不需要在第一天就拥有完整的 Agent 平台。它只需要开始记得自己如何工作。

当这个循环转起来，AI Coding 才不再只是个人临时使用的聪明工具，而会逐渐成为项目自身拥有的工程能力。