星澜

天接云涛连晓雾，星河欲转千帆舞

06. AI Agent 与 Harness：Repo Instructions、Skills 与团队工作流

mingzaily / Codex / 2026-03-29

上一篇《05. AI Agent 与 Harness：Agent Harness、Graph 与退款 Agent》讲的是：如果自己开发一个退款 agent，agent harness 该怎么落。

但对大多数团队来说，眼前更现实的任务并不是马上造一套业务 agent 系统，而是先把 Codex、Claude Code 这类现成 agent 用稳。

这时候真正需要补的，往往不是另一种 harness，而是仓库里的这些东西：

放到一个典型的后端团队里，这件事会变得很具体：

问题也会跟着收敛成一句话：

在这种团队里，怎么把默认工作方式写成 agent 也能稳定遵守的仓库规则？

结论

repo instructions + skills + 验证流程 = 把团队默认工作方式显式化，让 agent 可以稳定照着做。

团队上下文要写清楚

很多团队装了 MCP、写了几句提示词，就以为自己已经在做 harness。
但如果 agent 连“这个仓库到底怎么工作”都不知道，它其实还是进不了团队的真实语境。

所以第一步不是堆工具，而是把上下文写明白。

像一个 gin + gorm + redis 的 Go 团队，至少要把这些共识显式化：

这些东西如果只存在于资深同事脑子里，agent 是用不稳的。

这套仓库约定的五层结构

放到这种团队里，一版最小可用的仓库规则，通常至少要补下面五层。

1. AGENTS.md 作为总入口

AGENTS.md 最重要的作用，不是堆很多原则，而是给 agent 一个稳定入口。

它至少应该回答：

比如一个 Go 后端团队的 AGENTS.md，至少应该能长成这样：

## Stack
- HTTP: gin
- DB access: gorm
- Cache: redis
- Observability: tracing + structured logs

## Architecture
- handler 保持薄，业务逻辑放 service
- repository 负责数据库访问
- 外部调用必须带 context

## Conventions
- gin handler 只做参数解析、响应返回、调用 service
- gorm 事务必须放在 service 层统一管理
- redis key 使用 app:domain:biz:id 格式
- 写缓存时必须说明 TTL 和失效策略
- 新增外部调用必须补 span 和关键日志字段

## Required Verification
- go test ./...
- golangci-lint run
- 变更缓存逻辑时，说明 key / TTL / invalidation
- 变更 DB schema 时，说明 migration 和兼容性风险

这类信息越清楚，agent 越不容易乱猜。

2. 用 skill 把高频任务拆开

AGENTS.md 只能做总入口。
高频任务如果都堆在里面，很快就会变成一大坨。

所以第二层通常应该是 skill。

对这个团队来说，优先级最高的通常是这几类 skill：

为什么要拆？

因为这些任务往往都有稳定套路。

比如“新增 gin endpoint”这个 skill，就可以直接写清楚：

这样 agent 做的就不是“自由发挥”，而是按团队的稳定手法做事。

3. MCP 不只是装上去，还要有使用协议

很多团队现在已经会装：

但真正决定效果的，往往不是“有没有装”，而是：

agent 知不知道什么时候该用、先用哪个、查完之后怎么落回代码修改。

这种团队里，MCP 的使用协议最好直接写清楚：

日志 MCP

适合用来：

tracing MCP

适合用来：

dbhub MCP

适合用来：

GitHub / fetch MCP

适合用来：

也就是说：

MCP server 提供的是工具入口，repo instructions 和 skills 定义的是工具使用方法。

对这个团队来说，done definition 要写得很具体

如果 repo instructions 里只有“请注意规范”“请先思考再动手”，通常是不够的。
它要能明确回答：

什么才算完成。

比如这个团队里，至少可以把 done 写成下面这种硬标准：

改 gin 接口

改 gorm 查询或事务

改 redis 逻辑

改 tracing / logging

你会发现，这套 repo instructions / 验证流程 一旦把 done 写具体，agent 的行为质量会直接稳定很多。

这种团队里，落地顺序通常是什么

如果从零开始搭，顺序通常是这样的：

第一层：先补总入口

第二层：再补高频 skill

第三层：把 MCP 用法写成协议

第四层：固定验证命令

比如：

如果是某些高风险模块，还可以要求：

第五层：把结果报告结构化

最终交付最好至少交代：

这一步很重要，因为它会把“我改好了”这种模糊说法，变成真正能 review 的交付物。

一个真实任务会怎么走

假设现在有一个任务：

新增退款申请接口，并要求补 trace、日志和缓存失效逻辑。

在仓库规则比较完整的团队里，路径通常会是：

  1. agent 先读 AGENTS.md
  2. 再加载“新增 gin endpoint”和“处理 redis cache”两个 skill
  3. 如果是线上问题回溯，再通过 tracing MCP 和日志 MCP 先定位现状
  4. 按团队分层约定改 handler / service / repository
  5. 补 trace、补结构化日志、补缓存失效
  6. 跑固定命令
  7. 按固定格式交付结果

这时就能看出来，这套仓库约定做的并不是“让模型更聪明”，而是：

让它更像一个刚加入团队、但已经拿到完整 onboarding 和 SOP 的工程师。

这套仓库约定不该做什么

这件事同样重要。
repo instructions 和 skills 很容易越写越重，最后变成：

更清楚的分法是：

所以像下面这些东西：

这些更应该落进 agent harness，而不是只写在仓库提示词里。

几句话总结

  1. 对使用现成 coding agent 的团队来说，关键不是再发明一个新名词，而是把 repo instructions、skills、MCP 使用约定、验证命令和交付格式写清楚。
  2. 对 gin + gorm + redis 团队来说，最重要的是把默认做事方式显式写出来。
  3. MCP server 提供的是工具入口，repo instructions 和 skills 定义的是使用方法。
  4. 这套仓库约定最怕空泛，done definition 越具体，agent 越容易稳定。
  5. 它解决的不是“系统怎么运行”，而是“在这个仓库里，事情应该怎么做”。