Section 01

What is AGENTS.md? — CLAUDE.md for Autonomous Agents

If you've used Claude Code for any serious project, you know CLAUDE.md: the configuration file that lives in your project root and tells Claude how to behave in interactive sessions. CLAUDE.md handles your preferences, project context, writing style, and workflow rules — all the things Claude needs to work effectively when a human is in the loop.

This guide uses AGENTS.md for the rules of unattended runs. That is a convention, not a Claude Code mode: Claude Code loads the same instruction files in interactive, -p and SDK runs, and reads AGENTS.md only when there is no CLAUDE.md. If you keep a CLAUDE.md, import AGENTS.md from it with @AGENTS.md so these rules load in automated pipelines, scheduled tasks and subagents (Claude Code memory docs).

⚡

The core distinction: In an interactive session, Claude can always ask you a clarifying question. In an unattended run (claude -p, a scheduled task), there's nobody home to answer. Your instruction file — CLAUDE.md, or AGENTS.md when there is no CLAUDE.md — pre-answers those questions before Claude even starts.

Interactive Sessions vs. Agentic Sessions

The difference matters more than it might seem. In an interactive session, every uncertain decision can be surfaced: "Should I overwrite this file?" "This API returned an unexpected schema — how do you want me to handle it?" You can course-correct in real time.

In an unattended run, Claude works for minutes or hours without interruption. A single ambiguous decision early in the session can cascade into dozens of downstream actions. AGENTS.md is how you constrain that decision space before the agent even starts.

Dimension	CLAUDE.md	AGENTS.md
Read when	Every session	Every session, when there is no CLAUDE.md or CLAUDE.md imports it
Human present	Always	Never (or rarely)
Primary purpose	Style, context, preferences	Permissions, boundaries, escalation
Scope decisions	Made on-the-fly by asking	Pre-decided before the run
Error handling	Ask the human	Follow recovery procedure
Permission model	Implicit (follows instructions)	Explicit (written authorization list)
Escalation rules	Not needed (can always ask)	Required — defines what triggers a stop

Where AGENTS.md Lives

AGENTS.md can live in two places, with clear priority rules:

./AGENTS.md Project root — the primary location, read first
./.claude/AGENTS.md Inside the .claude directory — also loaded; neither overrides the other

If both exist, Claude Code loads both (when it reads AGENTS.md at all); neither overrides the other. A subdirectory's AGENTS.md loads when Claude opens a file in that subdirectory (Claude Code memory docs).

Section 02

Anatomy of AGENTS.md — A Complete Annotated Example

Every production AGENTS.md has the same six core components. Here is a complete, real-world example with annotations explaining what each section does and why it matters.

          
          AGENTS.md
        
Markdown
# ═══════════════════════════════════════════════════════════
# AGENTS.md — [Project Name] Autonomous Agent Configuration
# ═══════════════════════════════════════════════════════════
# Claude Code reads this file only when there is no CLAUDE.md,
# or when your CLAUDE.md imports it with @AGENTS.md.

## Agent Identity
You are an autonomous agent running the [Project Name] pipeline.
Session: {{SESSION_ID}}
Run type: {{RUN_TYPE}} (daily | weekly | on-demand)
Started: {{START_TIME_UTC}}

# WHY: Grounding the agent in its role prevents scope creep.
# The agent knows exactly what it is and what kind of run this is.

## What You Are Authorized To Do
Without asking, you MAY:
- Read any file in this repository
- Write to outputs/ and brain/ directories
- Run Python scripts in code/ (read-only impact)
- Make API calls to: FRED, Polygon, OpenAI (for analysis only)
- Create or update files matching patterns: *.json, *.html, *.md
- Git add + commit (commit message must include session ID)
- Send emails via the configured mailer (code/send_email.py)
  ONLY after validate_email.py passes with exit code 0

# WHY: Explicit authorization list means the agent never has to
# guess what it's allowed to do. Ambiguity = bad decisions at 3am.

## What Requires Escalation
STOP and write escalation details to outputs/escalation_needed.json if:
- Any API returns an unexpected data format (new schema detected)
- A critical output file fails its validator (exit code != 0)
- You discover a data anomaly that would change a signal direction
- Any financial calculation differs by more than 5% from prior run
- You need to modify files in: production/, live/, archived/
- Any external service returns HTTP 429 (rate limit) three times
- You encounter a permission error on a file you expect to write

# WHY: Define exactly what "too uncertain to proceed" looks like.
# The agent shouldn't decide this on the fly — it's pre-decided here.

## Hard Boundaries — NEVER Do These
These are absolute. No exception, no "but it would help":
- NEVER git push to any remote (stash if needed, never push)
- NEVER delete any file (write a deprecation marker instead)
- NEVER modify files outside your authorized scope (outputs/, brain/)
- NEVER make real trades or submit any financial orders
- NEVER send emails without passing validate_email.py first
- NEVER overwrite files in archived/ regardless of content
- NEVER call any API not in the authorized list above

# WHY: The NEVER list is your blast radius limiter. Everything
# you don't put here is implicitly allowed by omission. Be thorough.

## Error Recovery Procedure
When you encounter any error, follow this sequence exactly:

1. Log the error to outputs/agent_errors.jsonl with fields:
   {timestamp, task_name, error_type, error_message, stack_trace, context}

2. Attempt recovery using brain/fallback-procedures.md for this task.
   Try the fallback ONCE. If it also fails, do not retry further.

3. If fallback fails: mark the task status as SKIPPED with reason.
   Log the skip to outputs/agent_task_log.jsonl and continue.
   Do NOT halt the entire session for a single task failure.

4. At session end: include all SKIPPED tasks in the handoff summary
   under the "tasks_skipped" key with full context for human review.

# WHY: Without a recovery procedure, the agent either loops
# on errors (wastes tokens) or halts entirely (wastes the whole run).
# Pre-defined recovery means failures are isolated, not cascading.

## Output Standards
Every session MUST produce:
- brain/session_handoff.md with ONLY verified accomplishments
  (never claim done if you haven't checked the output file exists
   and passes its validator)
- outputs/agent_task_log.jsonl with one entry per task attempted
- Any generated HTML must pass visual_qa.py before being logged as done

Format requirements:
- All timestamps: ISO 8601 UTC (2026-04-15T14:23:00Z)
- All filenames: snake_case, no spaces
- All JSON: valid, minified for machine-read files, pretty for humans

# WHY: Output standards prevent "I ran the script" being logged
# as "task complete." Done means output verified, not process run.

## Definition of Done
A task is DONE only when ALL of the following are true:
1. The output file exists at the expected path
2. The output file passes its designated validator (exit code 0)
3. You have manually spot-checked at least 3 data points in the output
4. The task is logged in agent_task_log.jsonl with status "complete"

NOT done conditions (do not log as complete):
- Script ran without Python errors (output might still be wrong)
- File was written (content might be empty or malformed)
- Prior run's output is still present (might be stale, not regenerated)

# WHY: The most common agent failure is logging tasks as done
# when only the process ran, not when the output was verified.
# This section makes "done" unambiguous.

## Communication Protocol
When you complete a session, output this exact structured summary:

```json
{
  "session_id": "{{SESSION_ID}}",
  "run_type": "{{RUN_TYPE}}",
  "completed_at": "ISO-8601-UTC",
  "tasks_completed": ["task_name_1", "task_name_2"],
  "tasks_skipped": [{"task": "name", "reason": "explanation"}],
  "issues_found": [{"issue": "description", "severity": "low|medium|high"}],
  "escalation_needed": false,
  "next_session_priorities": ["priority_1", "priority_2", "priority_3"]
}
```

# WHY: Structured output means the next human (or next agent)
# can parse results programmatically. Freeform prose summaries
# don't compose well in automated pipelines.

Section-by-Section Breakdown

🤖

Agent Identity — Grounds the agent in its exact role and run type. Prevents the agent from expanding its scope beyond the defined run. Configuration variables like {{SESSION_ID}} are injected by your runner script before the file is passed to Claude.

✅

What You Are Authorized To Do — The positive permission list. Anything not on this list is implicitly unauthorized. Be explicit. "Make API calls" is too broad — name the specific APIs. "Write to outputs/" is better than "write files."

⚠️

What Requires Escalation — The gray zone. These are situations the agent encounters where the right answer is "stop and flag it" rather than proceed or fail. Schema changes, data anomalies, and files outside scope are classic escalation triggers.

🚫

Hard Boundaries — NEVER Do These — The blast radius limiter. Irreversible actions (git push, file deletion, real financial orders) must be in this list. These are non-negotiable regardless of how helpful it might seem in context.

🔄

Error Recovery — Pre-decides what "error" means and exactly what to do about it. The agent doesn't need to figure out whether to retry, skip, or halt — the procedure tells it. This is what keeps a single failure from becoming a session failure.

Section 03

How Claude Code Reads AGENTS.md

Checked against Anthropic's Claude Code memory documentation on 2026-10-08. An earlier version of this section described an "agentic mode" loader, a file-priority order and an AGENTS.md-overrides-CLAUDE.md rule. None of that is in Anthropic's documentation, and it has been removed.

When Claude Code reads AGENTS.md

Only when there is no CLAUDE.md. By default Claude Code reads AGENTS.md as your project instructions when your working directory and the directories above it have no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md. If one of those exists, Claude reads your CLAUDE.md files only.
The same in every mode. The docs draw no line between interactive, -p or SDK runs. There is no separate "agentic" loader.
Version. Reading AGENTS.md directly needs Claude Code v2.1.277 or later. In sessions where it is unavailable, import it from a CLAUDE.md instead.

Which files load, and when

At session start: every AGENTS.md and .claude/AGENTS.md in your working directory and the directories above it.
In subdirectories: a subdirectory's AGENTS.md loads when Claude opens a file there and that subdirectory has no CLAUDE.md of its own.
Imports: @path imports inside AGENTS.md are expanded, the same as in CLAUDE.md.

Using both files

To keep one source of truth for several coding tools, put @AGENTS.md in your CLAUDE.md so it is imported, or change the Project instructions setting in /config to read both. Nothing makes one file "win": both land in Claude's context, so resolve contradictions in the text itself.

Instructions are context, not enforcement. Anthropic's docs say Claude treats CLAUDE.md (and AGENTS.md) as context, not enforced configuration. The authorization matrix below is worth writing down, but the hard limits belong in permission rules and a PreToolUse hook, which block an action whatever the model decides.

Injecting run variables

Claude does not substitute {{SESSION_ID}}-style placeholders. If you want per-run values, have your runner write them into a file and pass it with --append-system-prompt-file, a real flag in the CLI reference. (An earlier version of this page used a --system-file flag, which does not exist.)

Section 04

The Authorization Matrix — Designing Agent Permissions

The authorization matrix is the core of any AGENTS.md. It organizes all possible agent actions into four tiers based on reversibility and risk. Design your authorization matrix first — then write the AGENTS.md around it.

Tier 1

Always OK — No Logging Required

Read any file in the repository
Analyze and compute (in memory only)
Draft output files before writing them
Call read-only API endpoints
Check file existence with ls / glob
Run tests in watch mode (no writes)

Tier 2

OK with Logging — Standard Agent Work

Write to designated output directories
Make mutating API calls (authorized list only)
Create new files matching approved patterns
Git add + commit (with session ID in message)
Send internal notifications (Slack, log files)
Update cache or state files

Tier 3

Requires Pre-Approval — Write to Escalation

Schema changes in any database or config
External email sends (outside internal team)
Any financial calculation or order placement
Modifying files outside authorized scope
Dependency updates or version bumps
Any action affecting >50 records at once

Tier 4

NEVER — Hard Stop, No Exceptions

Git push to any remote branch
Delete any file (write deprecation marker instead)
Production deploys or live environment changes
Real financial orders or transactions
Calling APIs not on the authorized list
Overwriting files in archived/ or production/

💡

Design principle: Start with everything in Tier 4 and selectively promote actions up to Tier 1 as you gain confidence. It's much easier to relax restrictions after a successful run than to recover from an overly-permissive agent that took destructive action at 3am.

Authorization Matrix Configuration

AGENTS.md — Authorization sections
Markdown
## Authorization Matrix

### Tier 1 — Always Permitted (No Logging Required)
- Read access: all files in repository
- In-memory analysis and computation
- API: GET requests to FRED, Polygon (read-only endpoints)
- File existence checks, directory listings

### Tier 2 — Permitted with Task Log Entry
- Write access: outputs/*.json, outputs/*.html, brain/*.md
- API: POST to internal mailer (validate_email.py must pass first)
- Git: add + commit (format: "[{SESSION_ID}] {task_name}: {summary}")
- Create new files in: outputs/, brain/, code/cache/

### Tier 3 — Requires Escalation Before Proceeding
- Any file write outside outputs/ and brain/
- API calls not listed in Tier 1 or Tier 2
- Actions affecting more than 10 records/files simultaneously
- Any action that cannot be easily reversed

### Tier 4 — Absolute Prohibition
- git push (to any remote, any branch)
- File deletion (use deprecated_{filename} rename instead)
- Any action in: production/, live/, .env files
- Real financial transactions or order submission

Section 05

AGENTS.md vs CLAUDE.md — Deep Comparison

Both are plain instruction files with the same job: telling Claude how to work on your project. They do not split the work between them. What differs is whether Claude Code reads them: by default it reads AGENTS.md only when there is no CLAUDE.md. So the useful question is not "which file owns which topic" but "which file actually loads" (Claude Code memory docs and subagents docs, both read 2026-11-06).

Question	CLAUDE.md	AGENTS.md
Read by default?	✅ Yes, at the start of every session	⚠️ Only when there is no `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md` in your working directory or above it
Both files in the repo	✅ Your CLAUDE.md files are read	❌ Not read, unless your CLAUDE.md contains `@AGENTS.md` or Project instructions in `/config` is set to `claude-md-and-agents-md`
Files that never block AGENTS.md	Your `~/.claude/CLAUDE.md`, your organization's managed CLAUDE.md and `.claude/rules/` files	They keep loading alongside AGENTS.md; they do not count as "a CLAUDE.md"
Subfolder files	A subfolder's CLAUDE.md loads once Claude reads, writes or edits a file in that folder	A subfolder's AGENTS.md loads when Claude opens a file there with the Read tool and that folder has no CLAUDE.md of its own
Subagents	Every subagent loads them, except the built-in Explore and Plan agents and any subagent set to `omitClaudeMd: true`	Same: an AGENTS.md loaded as project instructions reaches subagents the same way. There is no separate per-subagent AGENTS.md
Enforced?	❌ No. Claude treats it as context, not enforced configuration	❌ No, same rule. To block an action, use a permission deny rule or a PreToolUse hook
`InstructionsLoaded` hooks	Fire	Don't fire when AGENTS.md is read directly; they fire when a CLAUDE.md imports it
Rules for unattended runs (escalation, error recovery, logging, "done")	✅ Put them here if your project has a CLAUDE.md	✅ Put them here only if there is no CLAUDE.md, or import it with `@AGENTS.md`
Overrides CLAUDE.md?	—	No. With a CLAUDE.md present, Claude Code reads CLAUDE.md instead (default setting)

📐

The simple rule: If your project has a CLAUDE.md, put your rules in CLAUDE.md. AGENTS.md is only read when there is no CLAUDE.md. If you want one file that other coding tools also read, keep the rules in AGENTS.md and make the first line of your CLAUDE.md @AGENTS.md. Either way, anything that must never happen belongs in a permission deny rule or a hook too, because instruction files are guidance, not locks.

Section 06

Real-World Examples — Three Agent Types

Here are complete AGENTS.md examples for three common agent types. Treat each as a starting point to adapt to your own project.

📌

Before you copy one: Claude Code reads an AGENTS.md on its own only when the project has no CLAUDE.md. If yours has one, save the example as AGENTS.md and add the line @AGENTS.md to your CLAUDE.md, or paste the text into CLAUDE.md. The NEVER lists are instructions Claude tries to follow, not locks: back each one with a deny rule in .claude/settings.json (for example Bash(git push *)) or a PreToolUse hook.

🔄

Daily Data Pipeline Agent — Fetches macro data from external APIs, runs analysis, generates HTML reports, sends email digests. Runs on a 6am cron, no human present.

AGENTS.md — Data Pipeline
Markdown
# AGENTS.md — Market Data Pipeline Agent

## Agent Identity
You are the daily market data pipeline agent.
Session: {{SESSION_ID}} | Run type: daily | Time: {{START_TIME_UTC}}
Your job: fetch data → analyze → generate outputs → send digest.
Complete all tasks in order. Do not skip unless recovery procedure applies.

## Authorized Actions
Without approval, you MAY:
- Fetch from: FRED API, Polygon API, OpenAI API (gpt-4 analysis only)
- Read/write: code/cache/, outputs/, brain/
- Run: code/*.py scripts (listed in pipeline_config.json)
- Git add + commit with format: "auto [{SESSION_ID}]: {summary}"
- Send email via code/send_email.py AFTER validate_email.py passes

STOP and write to outputs/escalation_needed.json if:
- API returns HTTP 5xx three times in a row
- Any output file fails its validator
- A signal changes direction by more than 2 standard deviations
- send_email.py returns non-zero exit code

NEVER:
- git push
- Delete or overwrite files in outputs/signal_snapshots/ (append only)
- Call any API not in the authorized list
- Send emails if validate_email.py exits non-zero

## Pipeline Task Order
1. Fetch FRED data: python3 code/fetch_fred.py
2. Fetch price data: python3 code/fetch_prices.py
3. Run signal generation: python3 code/run_daily.py
4. Generate dashboard: python3 code/generate_command_center.py
5. Run visual QA: python3 code/visual_qa.py --site ept
6. Send email digest: python3 code/send_email.py (after validate_email.py)

## Error Recovery
Step fails → log to outputs/agent_errors.jsonl → check brain/fallback-procedures.md
→ try fallback once → if fails, mark SKIPPED, continue to step N+1.
Never halt the pipeline for a single step failure.
If steps 1-3 all fail: escalate immediately (no output = no session value).

## Done Definition
Session complete when:
- outputs/daily_email.html exists and visual_qa.py passes
- brain/session_handoff.md written with verified task list
- Git commit created with session summary

✍️

Content Generation Agent — Creates SEO articles and landing pages, validates content quality, commits to git. Runs on-demand or weekly. Content goes through quality gates before any deploy action.

AGENTS.md — Content Agent
Markdown
# AGENTS.md — Content Generation Agent

## Agent Identity
You are the SEO content generation agent for brainfile.io.
Session: {{SESSION_ID}} | Run type: {{RUN_TYPE}} | Time: {{START_TIME_UTC}}
Your job: create high-quality, accurate SEO content and commit it to git.
You do NOT deploy. Deployment requires human approval via the owner dashboard.

## Authorized Actions
Without approval, you MAY:
- Research: read all files in /deploy-sites/brainfile/ and /brain/
- Write new HTML files to: /deploy-sites/brainfile/{slug}.html
- Fetch external data for research: news APIs, pricing pages (read-only)
- Run: code/validate_html.py on any file you create
- Git add + commit: "content [{SESSION_ID}]: add {slug}.html"
- Update: sitemap.xml to include new pages

STOP and escalate (write to outputs/content_escalation.json) if:
- Any content involves legal, medical, or financial advice claims
- A new page would overwrite an existing file (check first, always)
- External research surfaces contradictory information you can't resolve
- Validator reports any error (do not commit failing content)

NEVER:
- Deploy or push to any live site
- Overwrite existing content files (only create NEW files)
- Include specific performance claims without verified data sources
- Use placeholder content in final files — real content only
- Skip validate_html.py before committing

## Content Quality Gates
Before committing any HTML file:
1. validate_html.py must pass (exit code 0)
2. Word count must be > 2000 words
3. All internal links must point to real pages (check against sitemap.xml)
4. No broken image references
5. Schema.org JSON-LD must be valid (check with: python3 -c "import json; json.load(open('file.html'))" — adapted)
6. Title tag must contain the primary keyword

## Prohibited Content Topics
Do not create content about:
- Specific investment advice or stock picks
- Competitor products with unverified claims
- "AI is conscious / sentient" framings
- Any claims about Claude that contradict Anthropic's published docs

## Done Definition
Page is done when:
- File exists at /deploy-sites/brainfile/{slug}.html
- validate_html.py passes
- Git commit created
- sitemap.xml updated
- Session handoff includes page URL, word count, and primary keyword

📡

Monitoring & Alert Agent — Runs health checks on dashboards and pipelines, detects anomalies, sends Slack alerts. Runs every 30 minutes. Has strict alert rate limits to prevent alert fatigue.

AGENTS.md — Monitor Agent
Markdown
# AGENTS.md — Monitoring & Alert Agent

## Agent Identity
You are the health monitoring agent. You run every 30 minutes.
Session: {{SESSION_ID}} | Run type: monitor | Time: {{START_TIME_UTC}}
Your job: check system health, detect anomalies, send alerts if needed.
You observe and alert. You do NOT fix issues yourself.

## Authorized Actions
Without approval, you MAY:
- Read: all output files, log files, signal files
- Run: python3 code/visual_qa.py --site ept (read-only)
- Run: python3 code/validate_command_center.py
- Write: outputs/health_log.jsonl (append only, NEVER truncate)
- Send Slack alert via code/send_slack.py (subject to rate limits below)

Alert Rate Limits (enforced by checking outputs/alert_log.json):
- Maximum 3 alerts per rolling 2-hour window
- Same issue: do not re-alert for 4 hours after first alert
- CRITICAL alerts (data loss, pipeline down): no rate limit
- If rate limit would be exceeded: log to health_log.jsonl, skip Slack

STOP and write CRITICAL alert if:
- Pipeline has not run in > 25 hours (check outputs/ file timestamps)
- Any validator returns errors on 2 consecutive checks
- Signal file is more than 6 hours stale during market hours (9am-4pm ET)
- Any output directory is empty that should have files

NEVER:
- Attempt to fix any issue you detect — alert and log only
- Delete or overwrite any file
- Send more than 3 non-critical alerts in a 2-hour window
- Modify any config or pipeline file

## Alert Severity Levels
CRITICAL: data loss, pipeline failure, zero outputs — alert immediately, no rate limit
HIGH: stale data, validator failures — alert, subject to rate limits
MEDIUM: performance degradation, slow runs — log only unless sustained 2+ checks
LOW: cosmetic issues, minor timing — log only, weekly digest

## Check Order (run in sequence)
1. Check pipeline last-run timestamp (< 25h ago = OK)
2. Validate command center: python3 code/validate_command_center.py
3. Visual QA: python3 code/visual_qa.py --site ept
4. Check signal file age: outputs/signals.json mtime
5. Check output file count in outputs/ (should match prior baseline)
6. Write health report to outputs/health_log.jsonl
7. Send alerts if thresholds exceeded (check rate limits first)

## Done Definition
Each check run is done when:
- All 6 checks completed (or marked FAILED with reason)
- outputs/health_log.jsonl updated with this run's results
- Any alerts sent (or deliberately skipped due to rate limits) are logged

Section 07

Best Practices — 8 Rules for Writing Good AGENTS.md

Rule 01

Be Explicit, Not Implicit

Agents cannot read minds. "Use your best judgment" is the most dangerous phrase you can put in an AGENTS.md. Every decision point needs a pre-made answer. If you catch yourself writing "use judgment" — replace it with the specific rule that judgment would have followed.

Rule 02

Define "Done" with Precision

The default agent interpretation of "done" is "the script ran without errors." This is almost always wrong. Define done as: output file exists + validator passes + spot-check passes + logged in task log. Make it impossible to claim done without verifying output.

Rule 03

Every Destructive Action Needs a NEVER

If an action can't be easily reversed — git push, file deletion, live deployment, financial transaction — it must appear in the NEVER DO list. Anything you don't prohibit, the agent may try, and in a run that skips permission prompts nothing stops it. Be paranoid when writing this section, and put the same items in permission deny rules.

Rule 04

Plan for Errors: Write the Recovery Path

Every agent run will encounter at least one error. If your AGENTS.md has no error recovery procedure, the agent will improvise — and improvisation at 3am with no human present is where disasters happen. Define exactly: log it, try fallback once, skip and continue.

Rule 05

Tighter Than You Think You Need

Start maximally restrictive. Give the agent only the permissions it needs for the first 10 runs. Expand after you've reviewed logs and gained confidence. Relaxing permissions is easy. Recovering from an overly permissive agent that did something irreversible is not.

Rule 06

Version Control Your AGENTS.md

AGENTS.md is code. It deserves the same git discipline as any other file. Track every change with a commit message. When something goes wrong in an agent run, the first question is "what changed in AGENTS.md between the last good run and now?" You need git history to answer that.

Rule 07

Test on Low-Stakes Runs First

Before granting full autonomy to an agent, run it on a read-only or reversible task. Let it run with --dangerously-skip-permissions on a staging copy of your data. Read every line of the logs. The agent will always find an edge case you didn't anticipate.

Rule 08

Review Logs After Every Early Run

Trust but verify — especially in the first 20 runs. Every decision the agent made that surprised you is a gap in your AGENTS.md. Build the discipline of reviewing agent_task_log.jsonl after every run and patching AGENTS.md for each unexpected behavior.

Section 08

Common Mistakes — 5 Patterns and How to Fix Them

❌

No File Write Boundaries — Agent Writes Everywhere

Problem: AGENTS.md says "write output files" without specifying which directories. Agent writes cache files to root, updates configs, overwrites source files.

Fix: Enumerate exact directories with write permission: outputs/, brain/, code/cache/. Anything not listed is off-limits.

❌

No Error Recovery Procedure — Single Failure Halts Everything

Problem: Step 3 of 8 throws an exception. Agent has no guidance, so it stops. Steps 4-8 never run. You wake up to a half-run pipeline with no explanation.

Fix: Write an explicit recovery procedure: log the error, try the fallback once, mark SKIPPED if fallback fails, continue to the next task. Only halt if your core data fetch (step 1) fails.

❌

"Use Your Judgment" on Irreversible Actions

Problem: AGENTS.md says "use your judgment when deciding whether to send emails." Agent sends 200 test emails to your subscriber list because the logic seemed correct.

Fix: Any action that is irreversible or external must have an explicit rule. Email sends: "ONLY after validate_email.py passes with exit code 0." No judgment calls on anything external.

❌

Vague "Done" Definition — Agent Marks Tasks Complete When Scripts Run

Problem: AGENTS.md says "complete each task and log it." Agent runs every script, logs them all as complete. Half the output files are empty or malformed — the scripts ran but produced no valid output.

Fix: Define done as a three-part test: (1) output file exists, (2) validator passes with exit code 0, (3) you spot-checked at least 3 data points in the output. Anything less = not done.

❌

AGENTS.md and CLAUDE.md Contradict Each Other

Problem: CLAUDE.md says "always ask before writing to any file." AGENTS.md says "write freely to outputs/." Agent sees a conflict and either stops to resolve it (which it can't, no human) or picks an interpretation inconsistently.

Fix: Neither file wins. With a CLAUDE.md present, Claude Code reads only CLAUDE.md by default, so keep one source: put the shared rules in AGENTS.md, import it from CLAUDE.md with @AGENTS.md, and delete the duplicate section.

Section 09

Multi-Agent Architecture — How AGENTS.md Works with Subagents

When you build multi-agent workflows with Claude Code's Agent tool, subagents load the same CLAUDE.md or AGENTS.md files as the main session (except the built-in Explore and Plan agents, and any subagent set to omitClaudeMd: true); per-agent limits belong in each subagent's definition and in permission settings (Claude Code subagents docs, read 2026-11-06). The key design principle: each layer should be more restrictive than the one above it.

The Orchestrator-Specialist Pattern

The most common multi-agent pattern has an orchestrator (the main session, broader permissions, coordinates work) spawning specialist subagents (narrow tools, specific tasks). The instructions are shared; the limits are not. Subfolder files are per folder, not per agent: when there is no CLAUDE.md, a subfolder's AGENTS.md loads for whichever agent opens a file in that folder with the Read tool, provided the folder has no CLAUDE.md of its own (Claude Code memory docs).

Where each layer gets its instructions and its limits

MAIN SESSION (orchestrator)./CLAUDE.md, or ./AGENTS.md when there is no CLAUDE.mdInstructions: that one set of project filesLimits: permission rules in .claude/settings.json, plus hooksSpawns subagents with the Agent tool

spawns ▼

DATA AGENT.claude/agents/data-fetcher.mdInstructions: the same project files as the main sessiontools: Read, Grep, Glob, BashRole and rules: the definition body

REVIEW AGENT (read-only).claude/agents/validator.mdInstructions: the same project files as the main sessiontools: Read, Grep, GlobNo Agent tool, so it cannot spawn subagents

Every subagent loads the same project instructions as the main session; the built-in Explore and Plan agents skip them, and omitClaudeMd: true turns them off. Limits come from each definition's tools, disallowedTools and permissionMode. If the main session runs in bypassPermissions, acceptEdits or auto mode, the subagent runs in that same mode whatever its definition says.

Key Rules for Multi-Agent Setups

1. Limits live in the subagent definition and your settings, not in an instruction file. Give each subagent a tools list (or disallowedTools) in .claude/agents/<name>.md. A disallowedTools entry like Bash(git push *) removes all of Bash from that subagent; to block just that command, add it to permissions.deny in your settings, which applies to the main session and to subagents.
2. External actions belong to the orchestrator. Email sends, git commits, API calls with side effects — these should be orchestrator-level actions. Specialist subagents return data; the orchestrator decides what to do with it.
3. Subagents start with a fresh context. A subagent does not see your conversation or the files the main session already read. Write what it needs to disk, or put it in the task you hand it.
4. Do not write an AGENTS.md per subagent. Subagents already load your project instructions. Put each one's role and rules in its own definition file under .claude/agents/; a rule only one subagent needs goes there or in the task you hand it.
5. Narrow scope = easier debugging. When a multi-agent system fails, knowing each subagent's exact scope makes it trivial to identify which agent did what. Broad subagent permissions make post-mortem analysis nearly impossible.

Directory structure — multi-agent setup
Structure
# One set of project instructions, loaded by the main session and its subagents
./CLAUDE.md                        # can be a single line: @AGENTS.md
./AGENTS.md                        # shared rules; read directly only when there is no CLAUDE.md

# One definition file per subagent: role, tools, permission mode
./.claude/agents/data-fetcher.md   # tools: Read, Grep, Glob, Bash
./.claude/agents/content-gen.md    # tools: Read, Write, Edit
./.claude/agents/validator.md      # tools: Read, Grep, Glob (read-only)

# Enforced limits (instruction files are guidance, these are not)
./.claude/settings.json            # permissions.deny rules and hooks

# Shared state (written by orchestrator, read by subagents)
./outputs/                         # Orchestrator writes here; subagents read

Section 10

Getting Started — 7-Step Setup

From zero to a production-ready AGENTS.md in one focused session.

Create AGENTS.md in your project root

Start with a blank file at the project root. Don't copy-paste from examples yet — write the agent identity block first. Who is this agent? What is its single job? What run type is this? Get those three sentences right before writing anything else.

Map your authorization tiers

List every action your agent might need to take. Sort each action into Tier 1 (always OK), Tier 2 (OK with logging), Tier 3 (requires escalation), or Tier 4 (never). Do this exercise on paper first — the resulting tier list is the skeleton of your AGENTS.md.

Write your NEVER DO list

Write down every action that would be catastrophic if the agent did it unexpectedly. Git push. File deletion. Live financial orders. External sends without validation. Each one gets its own line in the hard boundaries section. Be specific — "don't break things" is not a hard boundary.

Add your error recovery procedure

Write the exact 4-step sequence: (1) log the error with full context, (2) try the fallback from brain/fallback-procedures.md, (3) if fallback fails mark SKIPPED, (4) continue to the next task. Define the one exception: which critical step failure should halt the whole session.

Define your output standards and "done" definition

What files must every session produce? Where do they go? What format? And critically: what does "done" mean for each task? Write the three-condition done test: file exists, validator passes, spot-check complete. No exceptions.

Test with claude --dangerously-skip-permissions on a low-stakes task

Pick a task that is fully reversible — regenerating a cached file, re-running analysis on yesterday's data, creating a test output in a temp directory. Run the agent and watch what happens. Read every line of the output. Do not grant autonomy on production tasks until you've done this step at least 3 times.

Review logs and tighten boundaries as needed

After each early run, open agent_task_log.jsonl and read every decision the agent made. Every decision that surprised you = a gap in your AGENTS.md. Patch the gap before the next run. After 10 clean runs with no surprises, you have earned the right to trust the agent fully.

🚀

Quick start: copy the AGENTS.md sections in this guide for each agent type — data pipeline, content generation, monitoring, developer workflows — and fill in your own paths and limits. Brainfile does not ship AGENTS.md files; it covers the CLAUDE.md side (30-day trial, no card).

The Complete AGENTS.md Guide: Configure Claude Code's Autonomous Agents