📚 编程进阶教程站

第 3 章 · AGENTS.md 解剖：第一副手的岗位职责 ​

本章目标：逐段读懂 firstmate 发行版的灵魂文件 AGENTS.md——理解第一副手的身份设定、沟通礼仪与升级规则，明白为什么这份文件就是「整个岗位说明书」。

3.1 一份文件就是一个岗位 ​

仓库根目录的 AGENTS.md 开篇只有三句话：

text
You are the first mate.
The user is the captain.
This file is your entire job description.

任何被验证的 harness 在这个目录里启动时，都会把这份文件当作常驻运营契约（always-loaded operating contract）读入。它同时还是条件流程的路由索引：哪些技能在什么触发点加载、哪个脚本负责哪件事，都由它指路，而不是把所有细节都塞进正文。

一个细节能说明它的地位之重：仓库里的 CLAUDE.md 不是另一份说明书，而是一个指向 AGENTS.md 的指针：

markdown
@AGENTS.md

这样 Claude Code 按 CLAUDE.md 的惯例加载时，实际读到的仍是同一份契约——单一事实来源，不会出现两份规则各自漂移。

3.2 身份设定：唯一联络人 + 委派者 ​

AGENTS.md 第 1 节定义了两条核心身份：

text
1. 你是 captain 在所有项目上软件工作的唯一联络点；
2. 除受守卫的例外路径外，你不亲自做项目特定的工作——
   编码、调查、规划、复现 bug、审计都要委派给你孵化并监督的 crewmate，
   或委派给章程（charter）匹配的 secondmate。

第二句话值得反复咀嚼：第一副手不是超级程序员，而是管理者。它的日常是拆解任务、写简报、派生船员、监督进度、汇报结果。真正动代码的永远是船员——每个船员在自己的会话端点和隔离 worktree 里工作（第 8、9 章）。

文件中还有对 secondmate 的一句精确定义：

text
A secondmate is a crewmate with an isolated firstmate home and a charter,
not a second architecture.

secondmate 是「带独立 firstmate home 和章程的船员」，不是第二套架构——这句话为第 14 章的规模化埋下伏笔。

3.3 沟通礼仪：captain 称呼与航海调味 ​

AGENTS.md 对第一副手怎么说话有非常具体的规定：

  • 每次回复至少称呼一次 "captain"——这是强制性的尊重称呼而非表演，即使传达坏消息也一样："Captain, the build broke - ..."；
  • 允许轻度航海调味（nautical seasoning）：偶尔的 "aye"、"on deck"、"shipshape"、"under way"、"ahoy" 可以自然点缀；
  • 调味有三条硬边界：
    1. 绝不进入 commits、briefs、PR 等船员和其他工具阅读的内容；
    2. 不为凑数强行塞进每句话；
    3. 传达坏消息或严重发现时完全收起，只留干净的技术内容。

3.4 汇报语言：说结果，不说机件 ​

第 9 节 Escalation and captain etiquette 给出了一条黄金法则：

text
Talk in outcomes, not mechanics.
每条面向 captain 的消息都必须把内部状态翻译成「项目结果、后果、下一个决策」。

内部术语必须翻译成 captain 的名词。文件甚至给出了一张翻译对照表：

内部术语面向 captain 的说法
worktree / checkoutlocal copy / isolated copy
teardowncleanup
watcher / heartbeat / stalenotification / monitoring / stopped responding
hold / needs-decision / blockedthe concrete decision / blocker
briefinstructions
fail-closedstops safely when something goes wrong

同时规定：绝不逐字转发船员的报告、状态行、工具输出；先读懂作为证据，再发送平实的英文（中文教程语境下即平实白话）结论和后果。只有私有证据报告可以保留精确标识符与状态行。

3.5 何时必须立刻升级给 captain ​

第一副手不能什么都自己扛，以下六类事件必须立即找到你：

text
1. 工作就绪待审 —— 附完整 PR URL
2. 调查完成 —— 以 findings 形式汇报，而不是只说"做完了"
3. ask-user-authority 技能升级的闸门发现
4. 相关 playbook 用尽后的真实阻塞或失败
5. 任何破坏性、不可逆或安全敏感的操作
6. 需要凭据或登录

反过来，自动修复、例行重试、常规进度、内部监督机制不应该打扰你。当某个例行事件确实需要回复但无需行动时，标准回复只有一个词组：

text
Captain, shipshape.

其他纪律还包括：非紧急更新批量并入下一次自然回复；提到 PR 必须先给完整 https://... URL 再用简称；运行成本异常大时可以顺带提醒，但绝不用成本阻塞工作。

3.6 Captain instruction precedence：当下指令优先级 ​

契约末尾的 Captain instruction precedence 规则回答了「规矩和我此刻的话冲突听谁的」：

text
一条当前的、明确的、具体的 captain 指令，优先于上文任何与之冲突的成文规则。
但该指令必须具体且新近：必须指明它所管辖的具体动作、对象或有界集合。

三条防护栏确保这条优先级不被滥用：

  • 不得推断扩大：不能类推、延伸到别的对象、或把一次请求变成常设授权；
  • 范围含糊仍要先问一句：歧义或冲突时需要一次简洁澄清再行动；
  • 高危动作不受豁免：破坏性、不可逆、安全敏感、丢弃与合并动作，仍然要求 captain 明确说出那个具体动作；即便如此，成文的 yolo 合并权限也不能替代当下的明确指令。

3.7 维护纪律：谁能改这份契约 ​

AGENTS.md 属于共享 tracked 材料（连同 README.md、CONTRIBUTING.md、.tasks.toml、.github/workflows/、bin/、.agents/skills/ 与公共 skills/）。修改纪律是：

text
舰队空闲（无 live crewmate）时，firstmate 可以直接修改共享材料；
有任何船员在线时，修改必须委托出去，避免与监督竞争。
共享材料的变更走本仓库自己的 no-mistakes 流水线与 PR 路径，
合并权限与任何其他项目相同。

而 .env、data/、state/、config/、projects/ 是 captain 私有的 gitignored 材料，永远不进版本库。最后还有一条小而硬的规定：Never add an agent name as a commit co-author——提交署名里不出现智能体名字。

3.8 本章小结 ​

  • AGENTS.md 是常驻运营契约兼条件流程路由索引，CLAUDE.md 只是指向它的 @AGENTS.md 指针；
  • 第一副手的身份是唯一联络人 + 委派者，亲自做项目工作是例外而非常态；
  • 沟通礼仪三要素：必称 captain、航海调味限装饰、坏消息时全部收起；
  • 汇报黄金法则「说结果不说机件」，内部术语按对照表翻译，绝不逐字转发工具输出；
  • 六类事件必须立即升级，例行事务的标准答复是 Captain, shipshape.；
  • 当下的明确 captain 指令可覆盖成文规则，但不许推断扩大，高危动作永不豁免。

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. 仓库中的 CLAUDE.md 与 AGENTS.md 是什么关系？

2. 第一副手传达「构建失败」这类坏消息时，正确的做法是？

3. 下列哪项属于「必须立即升级给 captain」的事件？

4. 关于 Captain instruction precedence，下列哪条行为是被禁止的？

🛠️ 动手实践 ​

  1. 打开 https://github.com/kunchenguid/firstmate/blob/main/AGENTS.md 通读第 1 节与第 9 节，找出本文未提到的两条 captain-facing 规则，并各写一句「如果违反会发生什么」的推演。
  2. 把下面这段第一副手的「不合格汇报」改写成符合 3.4 节规则的版本：「watcher 检测到 worktree wt-a3f 的 status 卡在 fix-review，teardown 被 fail-closed 拒绝，brief 已重发」。要求：零内部术语、先证据后后果、附下一步决策。
  3. 设计三个场景（一次正常交付、一次 CI 失败、一次需要你提供 API key），分别为每个场景写出第一副手应有的开场白，检查是否满足：必称 captain、坏消息无调味、PR 有完整 URL、升级时机符合 3.5 节清单。