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.
- What loads when, and precedence
- Which file holds which instruction
- What a fleet worker loads
- How work is divided
- What a team copies, what stays per person
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 withpaths: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 projectloads only the project'ssettings.json. The person's user and local settings do not apply. Their permission rules and hooks do not apply.--strict-mcp-configloads only the MCP servers that the turn names. The person's own MCP servers are not available to the worker.CLAUDE_CONFIG_DIRpoints at an empty directory for each turn. The person's~/.claudeis 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.mdloads as the.claude/CLAUDE.mdof that home directory. This was seen in a worker turn on 2026-11-05 (Claude Code 2.1.318). Thus, a worker under$HOMEreads 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.