🛠️ 第6章 AGENTS.md:给 Agent 的项目说明书
📄 一句话概括

规则有两个维度:硬还是软、团队还是个人。四象限决定它落在哪个文件里。 团队那份进仓库、会被 review;个人那份只在你机器上。混在一起就是负担。 冲突时永远团队硬规则赢——否则硬规则就不硬了。

📝 本章和前面几章的关系

上一篇讲「按目录分层」,这一篇讲「按人分层」。两种分层经常同时存在: 一个仓库里既有团队共识,也有你的个人习惯。 Demo 把十条真规则按两个维度分堆,然后真的落成两个文件, 最后演示一次冲突:个人偏好撞上团队硬规则,谁赢。

一、硬规则与软偏好

硬规则:违反了必须拦。软偏好:违反了提一下,不拦。 判断方法很简单:这条规矩破了,会不会出事故? 会,是硬的;不会,是软的。

规则 硬还是软 为什么
提交前必须跑测试 硬 不跑就可能提交坏代码
data/ 不许改 硬 改了就没了
注释用中文 软 看不懂也能跑
函数不超过四十行 软 长了难读,但不致命

硬规则要少。 三条到五条是合理量级——多了就变成「什么都要拦」,而什么都要拦的结果是什么都拦不住。 软偏好的价值在于「说出来」。 不说,它就按默认风格写;说了,大多数时候会照做。 但它不该被强制执行——强制执行的软偏好,本质上是你把自己的口味当成了规矩。

二、个人偏好放哪

放你自己的机器上,不进仓库。 具体位置各工具不同,但形状一样:一个用户级配置文件。 为什么不能进仓库?三个理由,一个比一个实际: ① 会被同事看到,然后被 review; ② 会被当成团队约定,然后别人也跟着用; ③ 你换项目时它跟着走,但你不想让它跟着走。 Demo 里两个文件的行数和 token 都算出来了: 仓库那份八行七十三 token、个人那份五行五十七 token。 都很小,因为它们只写「不一样的地方」。 个人偏好最容易写多。 一个自查:这条如果同事也这么干,会不会妨碍你? 会,那它其实该进团队规则——你不是在表达偏好,你是在提要求。

三、别把个人习惯写成团队规矩

这是这一篇最实用的一段。 因为很多「团队规矩」其实是某个人的习惯,被写下来之后,所有人陪着遵守。

看起来像团队规矩 其实是
缩进用两个空格 个人习惯,编辑器能配
提交信息用英文 可能是约定,也可能只是你的习惯
函数不超过四十行 团队约定(影响可读性)
注释必须有作者名 多半是个人习惯,甚至过时了

一个检验方法:这条规矩换个同事不遵守,会不会出事故? 会,写进仓库;不会,写进你自己的配置。 冲突怎么办?Demo 里演了一次: 团队硬规则「提交前必须跑测试」对上个人软偏好「小改动可以跳过」。 判定是团队硬规则赢。 理由不是「团队大」,是「硬规则的定义就是不可被偏好覆盖」。 否则它就不叫硬规则了。

四、动手 Demo:团队规矩与个人偏好:四象限分堆

这个 Demo 拿十条真规则,按「硬软」和「团队个人」两个维度分堆,输出每条该落在哪个文件。 然后真的落成两个文件,量一下各自多大。 最后演示一次冲突判定。 「硬软」和「团队个人」这两个判断是人做的, Demo 只是把判断结果落成文件——这一点得说清楚,不是算出来的。

RULES_10 = [
    (u"提交前必须跑一遍测试", u"硬", u"团队"),
    (u"小改动可以跳过测试直接提交", u"软", u"个人"),
    (u"别动我本地的 .env", u"硬", u"个人"),
]

for r in RULES_10:
    where = (u"仓库 AGENTS.md" if r[2] == u"团队"
             else u"个人配置")
    P(u"  %s -> %s" % (r[0], where))

实跑输出:

--------------------------------------------------------------------
团队规矩与个人偏好:四象限分堆
--------------------------------------------------------------------


  ① 十条真规则,按两个维度分
  --------------------------------------------------------------------
| 规则 | 硬软 | 团队个人 | 该落在哪 |
|---|---|---|---|
| 提交前必须跑一遍测试 | 硬 | 团队 | 仓库 AGENTS.md |
| data/ 下不许改任何文件 | 硬 | 团队 | 仓库 AGENTS.md |
| 不许新增第三方依赖 | 硬 | 团队 | 仓库 AGENTS.md |
| 新增接口必须更新 docs/api.md | 硬 | 团队 | 仓库 AGENTS.md |
| 注释用中文 | 软 | 团队 | 仓库 AGENTS.md |
| 函数不超过四十行 | 软 | 团队 | 仓库 AGENTS.md |
| 提交信息用中文写两段 | 软 | 团队 | 仓库 AGENTS.md |
| 小改动可以跳过测试直接提交 | 软 | 个人 | 个人配置(软) |
| 我习惯用四个空格缩进 | 软 | 个人 | 个人配置(软) |
| 别动我本地的 .env | 硬 | 个人 | 个人配置(硬) |

  7 条进仓库,3 条进个人配置。

  ② 两个文件各写一段
  --------------------------------------------------------------------
  仓库里的 AGENTS.md:8 行、73 token
  个人配置里的 AGENTS.md:5 行、57 token
  仓库那份第一条:- 提交前必须跑一遍测试
  个人那份第一条:- 小改动可以跳过测试直接提交
  ! 分开放的理由很实际:团队那份会进版本库、会被同事看到、会被 review;个人那份只在你自己机器上。
  混在一起,你的个人习惯就变成了别人的负担。

  ③ 冲突:个人偏好撞上团队硬规则
  --------------------------------------------------------------------
  团队硬规则:提交前必须跑测试
  个人软偏好:小改动可以跳过测试直接提交
  判定:团队硬规则 赢——因为硬规则的定义就是「不可被偏好覆盖」。
  这里有个顺序问题:谁先被读到不算数,谁的级别高才算数。
  如果个人偏好能覆盖硬规则,那硬规则就不硬了。

  ④ 别把个人习惯写成团队规矩
  --------------------------------------------------------------------
| 看起来像团队规矩的 | 其实是 |
|---|---|
| 缩进用两个空格 | 个人习惯,编辑器能配 |
| 提交信息用英文 | 可能是团队约定,也可能只是你的习惯 |
| 函数不超过四十行 | 团队约定(影响可读性) |
| 注释必须有作者名 | 多半是个人习惯,甚至过时了 |

  ! 一个检验方法:这条规矩换个同事不遵守,会不会出事故?会,写进仓库;不会,写进你自己的配置。

十条分下来:七条进仓库、三条进个人配置。 注意「个人」那三条里有一条是「硬」的——「别动我本地的 .env」。 所以「个人」不等于「软」,这是两个独立的维度。 两个文件的行数:八行和五行。 都很小,因为只写「不一样的地方」——团队共识写仓库,你的例外写自己那儿。 冲突那一段是这一篇的落点: 团队硬规则赢。 而且理由要记准:不是「团队优先」,是「硬规则不可被偏好覆盖」。 这两句听着差不多,含义差很远——前者是组织关系,后者是逻辑关系。 最后那张表值得抄下来当模板用。 四行里有三行是「个人习惯」,说明大部分所谓的团队规矩,来源都是某个人的口味。

30 秒实验

  1. 翻一遍你仓库里的 AGENTS.md,逐条问「这条破了会出事故吗」。 不会的,往下挪成软偏好。
  2. 写下你真正的三条个人偏好。 如果写不出来,说明你一直在用别人的规矩。
  3. 找一条你以为是团队规矩、其实是个人习惯的。 问问同事怎么看。

常见误区

  1. 「我的偏好就是团队标准。」 一个人用叫偏好,十个人遵守才叫标准。 而十个人遵守需要他们同意。
  2. 「个人配置没用,反正我一个人开发。」 一个人开发更该分开。 因为你会换项目——偏好跟着走,规矩留下来。
  3. 「硬规则越多越安全。」 硬规则多了会互相打架,然后你开始给例外。 给到第五个例外时,这套规则就废了。
自测三问(点开对答案) 1. 「个人」和「软」是一回事吗? —— **不是,两个独立维度。** **「别动我本地的 `.env`」既是个人、又是硬**——**它不该进仓库,但违反了必须拦。** 2. 个人偏好为什么不该进仓库? —— **会被 review、会被同事当成团队约定、换项目时跟着走。** **三个理由一个比一个实际。** 3. 个人偏好和团队硬规则冲突时谁赢?为什么? —— **团队硬规则赢。** **理由不是「团队大」,是「硬规则的定义就是不可被偏好覆盖」**——**否则它不叫硬规则。**

下一篇 6.4 讲一件更组织化的事:角色分工、交接协议与值班边界。

相关笔记