Fleet docs v0.2.0-rc.448

How instructions govern the work

Agents in swarm-lab follow written instructions. Claude Code loads these instructions from CLAUDE.md files, rules and skills. This page tells you which file holds which instruction, when each file loads, and which file wins.

Sources: Anthropic's Claude Code docs, read on 2026-11-05: memory, skills, settings, CLI reference. The worker part comes from fleet/internal/driver/claude/claude.go.

What loads when

  • At start, Claude Code reads every CLAUDE.md from the filesystem root down to the start directory. It joins them. A file does not replace another file.
  • Rules in .claude/rules/ load at start. A rule with paths: in its frontmatter loads only when Claude reads a file that matches.
  • Skills cost one line each at start: the name and the description. The body loads only when the skill is used. Thus a long procedure goes in a skill, not in CLAUDE.md.
  • Auto memory is notes that Claude writes. It is per repository and per machine.

Precedence

CLAUDE.md files do not override each other. Claude reads all of them, broadest first. The file nearest to the start directory comes last. When two instructions disagree, Claude can pick either. Thus, remove the conflict. Do not rely on order.

Skills use a different rule. If two skills have the same name, the enterprise skill wins, then the personal skill (~/.claude/skills/), then the project skill. Plugin skills have a namespace (/plugin:skill), so they never clash.

Settings (settings.json) use a third rule: managed, then --settings on the command line, then .claude/settings.local.json, then .claude/settings.json, then ~/.claude/settings.json. Instructions are context, not enforcement. To stop an action every time, use a hook or a permission rule in settings.

Which file holds which instruction

Kind of instruction File Loads
Company policy that nobody can change managed CLAUDE.md and managed-settings.json always
A person's preferences and their machine's facts ~/.claude/CLAUDE.md always, on that machine
How a team operates: autonomy, what to ask first, reports the CLAUDE.md of the directory that holds the repos in every repo below it
The rules of one repo, each with the failure that caused it the repo's CLAUDE.md in that repo
A rule for one part of the repo .claude/rules/<topic>.md, with paths: when that part is read
A rule that applies to every shell command .claude/rules/<topic>.md, no paths: always
A procedure with steps: release, deploy, hand off .claude/skills/<name>/SKILL.md when used
A brief or ticket template a file next to the skill that uses it when the skill reads it
A block that must hold every time a hook or a deny rule in settings.json enforced
A fact that Claude learned about how a person works auto memory always, first 200 lines

Keep durable facts about a repo in the repo: its CLAUDE.md, docs/, or a comment at the point of use. Memory holds preferences about how to work, not facts about code.

What a fleet worker loads

A fleet worker is claude -p that the node starts for one turn. The driver adds these flags (fleet/internal/driver/claude/claude.go, Command):

claude -p --output-format stream-json --verbose --setting-sources project --strict-mcp-config
       --session-id <agent id>   (turn 1)   or   --resume <agent id>   (later turns)
       --mcp-config <the project's servers and "fleet mcp">
       --permission-mode bypassPermissions --disallowedTools BashOutput,KillShell
       --model <model>
       CLAUDE_CONFIG_DIR=<a new directory for this turn>

The driver also has a fenced mode (dontAsk and an allow list). No runner or node sets it at this time. The disallowed tools come from WorkerDisallow in fleet/internal/server/wire.go.

  • --setting-sources project loads only the project's settings.json. The person's user and local settings do not apply. Their permission rules and hooks do not apply.
  • --strict-mcp-config loads only the MCP servers that the turn names. The person's own MCP servers are not available to the worker.
  • CLAUDE_CONFIG_DIR points at an empty directory for each turn. The person's ~/.claude is not the config directory, so their auto memory, plugins and personal skills do not load.
  • CLAUDE.md files still load from every directory on the path to the workdir. When the workdir is under a home directory, ~/.claude/CLAUDE.md loads as the .claude/CLAUDE.md of that home directory. This was seen in a worker turn on 2026-11-05 (Claude Code 2.1.318). Thus, a worker under $HOME reads the person's user CLAUDE.md, and a worker in a pod does not.
  • In a git worktree, the skill search stops at the worktree root. Skills in a parent directory outside the repo do not load in a worker. Rules files in that parent directory did load in the same turn.

If a worker must follow a rule, put the rule in the repo. Do not put it only in a person's home directory.