AI 编程 Agent 的工作方式：Tool、Skill、AGENTS.md 与 Harness

AI 编程已经不只是生成一个函数。编程 Agent 可以读取仓库、搜索代码、修改文件、运行命令、检查测试，并根据结果继续迭代。

模型只是其中的推理核心。真正让它能在项目里完成工作的是一整套上下文、工具、规则、执行循环和安全控制。

从一个 Bug 看完整过程

用户提出：

修复登录按钮点击没有反应的问题，并补充测试。

一个完整流程可能是：

读取项目规则
→ 搜索登录组件和相关测试
→ 在浏览器或测试中复现
→ 分析事件、状态和接口调用
→ 修改最小范围代码
→ 运行目标测试和类型检查
→ 查看 Diff
→ 报告原因、改动和验证结果

如果测试失败，Agent 会读取错误信息并决定下一步。这个“观察、行动、再观察”的循环，是它与一次性代码生成的重要区别。

核心概念对照

概念	解决的问题	在 Bug 场景中的作用
模型	如何理解和生成	分析报错、推理原因、生成修改
Agent	谁组织整个任务	决定查什么、改什么、何时验证
Context	当前能看到什么	用户要求、代码、规则、测试输出
Tool	怎样执行动作	读写文件、Shell、Git、浏览器
Skill	某类任务怎样做	规定复现、修复、回归的工作流
`AGENTS.md`	在当前仓库遵守什么	包管理器、修改范围、测试命令
MCP	怎样连接外部系统	访问 GitHub、设计稿或数据库
RAG	怎样找到外部知识	检索规范、历史故障或内部文档
Memory	哪些信息跨任务保留	用户偏好、长期项目背景
Harness	怎样运行并约束 Agent	组装上下文、执行工具、权限和停止条件

`AGENTS.md` 与 Skill

AGENTS.md 是仓库或目录级的项目指令文件。它适合记录：

项目结构和技术栈。
统一包管理器和常用命令。
编码规范与模块边界。
哪些文件不能修改。
完成任务后的验收要求。

OpenAI 的 AGENTS.md 文档说明，Codex 会按目录层级发现项目指导，并让更具体位置的规则覆盖上层通用规则。

Skill 是可复用的专项工作流。例如“制作 PDF”“查询官方文档”“执行数据库迁移检查”。在 Codex 中，Skill 是一个包含必需 SKILL.md 以及可选脚本、参考资料和资源的目录，详见 Build skills。

两者的区别可以压缩成：

1 2	AGENTS.md：在这个项目里长期遵守什么 Skill：遇到这一类任务时通常怎样完成

项目规则与专项流程可以同时生效，Skill 不能绕过更高优先级的权限和项目约束。

Harness 不是一个 Markdown 文件

Agent Harness 是运行 Agent 的外部执行系统。它通常负责：

接收用户目标
→ 发现项目规则与可用 Skill
→ 组装 Context
→ 把工具 Schema 提供给模型
→ 校验并执行 Tool Call
→ 返回执行结果
→ 控制循环、预算和停止条件

Harness 还会涉及文件和网络沙箱、用户审批、任务状态、日志、超时、重试以及并行任务管理。它不等同于某个统一的 HARNESS.md 标准。

文字指令告诉 Agent 应该怎样做，操作系统权限和 Harness 策略决定它实际上能不能做。即使某个 Skill 要求联网，也不能绕过网络限制。

Tool、MCP 和 RAG 怎样配合

假设任务变成：

根据公司登录安全规范，修复 GitHub 第 123 号 Issue，并创建 PR。

可以拆成：

通过 GitHub MCP 读取 Issue
→ 通过 RAG 找到登录失败锁定规范
→ 使用本地文件 Tool 修改代码
→ 使用 Shell Tool 运行测试
→ 人工审查 Diff
→ 通过 GitHub MCP 创建 PR

这里，RAG 提供“失败多少次、锁定多久”的知识；MCP 提供连接 GitHub 的方式；Tool 执行读写和测试；Agent 负责组织步骤；Harness 负责权限、反馈和停止。

怎样给编程 Agent 下任务

一个高质量任务至少包含四部分：

Goal

明确最终行为，而不是只说“优化一下”。

1	修复登录按钮在请求失败后一直保持 loading 的问题。

Context

提供入口、复现方式和已知现象。

1	入口在 src/pages/login，接口返回 500 时可以稳定复现。

Constraints

说明范围和不能破坏的行为。

1	不要更换请求库，不修改接口契约，保留现有视觉样式。

Done when

给出可验证完成标准。

1	失败后 loading 恢复，错误提示出现，相关单元测试和类型检查通过。

人仍然负责什么

Agent 可以加快搜索、样板代码、测试补充、迁移和文档整理，但最终责任没有转移：

产品负责人定义真实问题和验收标准。
技术负责人决定架构边界和风险接受。
开发者审查 Diff、数据迁移、依赖和安全影响。
团队使用测试、Lint、扫描、灰度和监控做可执行门禁。
生产密钥、高风险命令和发布权限不能因为“由 AI 操作”而放宽。

一个团队级闭环

清晰 Issue
→ Agent 读取规则与代码
→ 小步修改并运行验证
→ 人与 Agent 共同审查 Diff
→ CI 执行统一门禁
→ 灰度发布与监控
→ 失败案例沉淀为测试、规则或 Skill

随着失败案例不断转化为自动检查，Agent 的工作环境会更清晰、更可验证。这比单纯写一段越来越长的 Prompt 更可靠。

一句话记忆

1 2	模型负责想，Agent 负责组织，Tool 负责做，MCP 负责接系统， RAG 负责找知识，Skill 提供流程，AGENTS.md 规定项目规则，Harness 负责运行与约束。

OpenAI 的 Agents SDK 指南也把模型响应与 Agent 运行区分开：前者由应用自行管理循环，后者由 SDK 提供 Agent 循环和生命周期能力。