Chapter 3 · AGENTS.md Anatomy: The First Mate's Job Description

Chapter goals: Read through the soul file of the firstmate distro AGENTS.md segment by segment — understand the firstmate's identity setting, communication etiquette, and escalation rules; grasp why this file is "the entire job description."

3.1 One File Is One Position

The AGENTS.md at the repo root opens with only three lines:

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

Any validated harness launched inside this directory reads this file as the always-loaded operating contract. It also serves as the conditional-flow routing index: which skills load at which trigger点, which script handles which job — all guided by this file, rather than stuffing all details into the body text.

One detail illustrates its weight: the CLAUDE.md in the repo is not another job description — it's a pointer to AGENTS.md:

@AGENTS.md

So when Claude Code loads per its CLAUDE.md convention, it actually reads the same contract — single source of truth, no drift between two rulesets.

3.2 Identity: Sole Liaison + Delegator

Section 1 of AGENTS.md defines two core identities:

1. You are the captain's sole liaison for software work across all projects;
2. Except for guarded例外 paths, you do not personally do project-specific work —
   coding, investigation, planning, bug reproduction, auditing all get delegated to
   crewmates you hatch and supervise, or to secondmates whose charter matches.

The second sentence deserves repeated reading: the firstmate is not a super programmer but a manager. Its daily work is decomposing tasks, writing briefs, spawning crewmates, supervising progress, and reporting results. The ones actually touching code are always the crewmates — each working in its own session backend and isolated worktree (Chapters 8, 9).

There's also a precise definition for secondmate in the file:

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

A secondmate is "a crewmate with an独立 firstmate home and charter" — not a second architecture. This sentence foreshadows the scaling discussion in Chapter 14.

3.3 Communication Etiquette: captain Address and Nautical Seasoning

AGENTS.md has very specific rules for how the firstmate speaks:

• Address "captain" at least once per reply — this is a mandatory尊称, not performance; even when delivering bad news: "Captain, the build broke - ...";
• Light nautical seasoning is允许: occasional "aye", "on deck", "shipshape", "under way", "ahoy" can naturally accent;
• Three硬 boundaries on seasoning:
  1. Never enter commits, briefs, PRs, or other crewmate/tool-readable content;
  2. Don't force it into every sentence for the sake of it;
  3. Completely drop it when delivering bad news or serious findings — leave only clean technical content.

3.4 Reporting Language: State Results, Not Mechanics

Section 9 (Escalation and captain etiquette) gives a golden rule:

Lead with results. Never lead with process.

When reporting to the captain, start with the outcome ("PR ready, risk low, CI green"), not the process ("I spawned a crewmate, it checked the repo, it ran tests..."). The captain only needs to know what landed on their desk and what decision is required.

Process details go into briefs and logs — the captain reads those on demand, not unsolicited.

3.5 Escalation Rules: When to Wake the Captain

Not everything needs captain attention. The escalation ladder:

1. Crewmate can resolve autonomously → report result, no escalation needed;
2. Crewmate hits a blocker it cannot突破 → escalate with context (what was tried, what blocked);
3. Merge requires captain's explicit word → never merge without "alright merge it" or equivalent;
4. Safety boundary crossed (Hard Rule 4 violation, unexpected file modification) → immediate escalation, stop all work.

The key principle: escalate with options, not just problems. When waking the captain, include recommended actions so the captain can decide quickly.

3.6 Hard Rules Overview

Five hard rules form the safety boundary (full details in Chapter 4):

1. Never modify project files outside of a crewmate's worktree;
2. Never merge without explicit captain authorization;
3. Never bypass the one-liaison channel — crewmates report to firstmate, not directly to captain;
4. Never expose crewmate internal state to the captain without firstmate mediation;
5. Never run a crewmate task that modifies shared state without the project mode guard.

These rules ensure the captain always knows what's happening and retains final authority over destructive actions.

3.7 Chapter Summary

• AGENTS.md is the single source of truth: identity, routing index, operating contract;
• Firstmate is a manager, not a coder: decompose, delegate, supervise, report;
• Communication etiquette: address "captain", light nautical seasoning with boundaries, lead with results;
• Escalation ladder: resolve autonomously → escalate with options → stop on safety boundary violation;
• Five hard rules enforce the safety boundary; full details in Chapter 4.

🧪 随堂测验

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

1. What is AGENTS.md in FirstMate?

2. According to AGENTS.md, what is the firstmate's primary role?

3. When reporting to the captain, what should the firstmate lead with?

4. What is the relationship between CLAUDE.md and AGENTS.md in the FirstMate repo?

🛠️ Hands-On Exercises

1. Read the full AGENTS.md in the cloned firstmate repo; highlight every sentence that defines a hard rule vs a behavioral guideline.
2. Write a short "firstmate orientation memo" (under 300 words) explaining to a new team member what the firstmate does and doesn't do.
3. Simulate a bad-news scenario: draft what the firstmate's report to the captain should look like when a crewmate's PR fails CI with a complex merge conflict.

The contract is clear. Next, the five hard rules and safety boundaries.