UnattendedClaude Code Guides

CLAUDE.md Best Practices: A Template for Unattended Agents

By Aoba Works · Published · Sources checked · 15 min read

How this guide was made: drafted with AI assistance from the official sources linked below, then passed an automated editorial check before publishing. Our process

CLAUDE.md best practices come down to three things. Keep the file short. Include only what Claude can't work out from the code. Write it so that a new agent with nobody around to ask can still finish the job. For unattended runs, that last point carries the most weight: the file should cover what to decide alone, what to stop on, and where to leave a note. If you only copy a style guide, the agent drifts, stalls, or keeps hitting permission denials overnight. Anthropic's own test for each line is: "Would removing this cause Claude to make mistakes?"

Which option is right for you?

Choose by how Claude will run, not by how big the project is. If you're unsure, start with the first row.

Which option is right for you?
Your situationWhat to pick firstFirst page to open
Beginner, no CLAUDE.md yetRun /init, then cut the draft down to commands, rules, and "never" linesBest practices: Write an effective CLAUDE.md
Daily interactive workA short project CLAUDE.md in git, plus skills for workflows you only need sometimesSkills docs
Nightly cron or claude -p jobThe unattended template below, plus permission rules in settingsHeadless mode
CI with --barePass the file yourself with --append-system-prompt-fileBare mode section
Tight token budgetMove rarely used content into skills or @ imports that only load when needed/claude-code-how-to-see-token-usage-and-reduce-it/
Rules that must never breakA PreToolUse hook or a deny rule instead of a CLAUDE.md lineHooks guide

Here's why, one line each. /init gives you a draft quickly, but the draft is too long. Skills keep everyday sessions lean. Unattended runs can't ask you anything. --bare doesn't load CLAUDE.md at all. Every line in CLAUDE.md costs tokens on every run. And a hook is the only kind of rule that can't be talked out of.

What should a CLAUDE.md file example look like?

A good CLAUDE.md example is short and scoped. It covers project context, commands, conventions, and explicit rules for what the agent must never do unattended. It isn't a full style guide.

Anthropic's own sample is just two headings, "Code style" and "Workflow", with two bullets each. The docs say "There's no required format for CLAUDE.md files, but keep it short and human-readable." An unattended agent needs a few extra sections that an interactive user never thinks about, because the interactive user is the one answering questions.

Here is an example for a scheduled job. It's illustrative, so replace the commands and paths with your own:

# Project
Static blog generator (Node 22). Content in /content, build output in /dist.

# Commands
- Install: npm ci
- Test: npm test -- --run
- Build: npm run build   (must exit 0 before any commit)

# Conventions
- ES modules only. No new dependencies without a note in REPORT.md.

# Autonomy: decide alone
- Fix failing tests caused by your own change.
- Retry a flaky network step once, then move on.

# Autonomy: stop and report
- Anything touching /migrations, .env, or CI config.
- A task that needs more than ~10 files changed.
- Any ambiguity you would normally ask about.

# When blocked
- Do not wait for an answer. Write the question and what you tried to BLOCKED.md, commit nothing, and end the run.

# Done means
- Tests pass, build exits 0, REPORT.md lists files changed and commands run.

# Compaction
- When compacting, always preserve the full list of modified files and any test commands.

Each section maps to a documented behavior. "Done means" comes from Anthropic's advice to give Claude a check it can run. Their wording: it's "the difference between a session you watch and one you walk away from." The compaction line is close to word for word what the best practices page suggests for keeping critical context through summarization. The "When blocked" section exists because a run started with --permission-prompts none removes tools that need a person, such as AskUserQuestion, according to the headless docs. Without that section, Claude has no planned route when it wants to ask you something.

Common pitfalls in examples:

What are the core CLAUDE.md best practices?

Keep CLAUDE.md concise, include only information that changes decisions, and write it as onboarding for an agent that can't ask questions.

The reason is the context window. Anthropic says "Claude's context window fills up fast, and performance degrades as it fills," and CLAUDE.md loads at the start of every session. The memory docs add that Claude treats these files as "context, not enforced configuration." Every line costs tokens, and none of them is guaranteed to be followed.

Anthropic's include/exclude table (source), rearranged for unattended use:

What are the core CLAUDE.md best practices?
IncludeExclude
Bash commands Claude can't guessAnything Claude can figure out by reading code
Code style rules that differ from defaultsStandard language conventions
Test instructions and preferred runnerDetailed API docs (link instead)
Branch naming and PR conventionsInformation that changes frequently
Project-specific architecture decisionsLong explanations or tutorials
Required env vars and environment quirksFile-by-file descriptions
Non-obvious gotchas"Write clean code"

Steps to write or rewrite yours:

  1. In the project folder, run claude, then type /init to generate a starter file (best practices).
  2. Delete every line that fails the test "Would removing this cause Claude to make mistakes?"
  3. Add the autonomy, "when blocked", and "done means" sections from the example above.
  4. Run /context to confirm the file loaded (best practices).
  5. For a checked-in file, run /doctor, and Claude proposes cuts for content it can work out from the codebase (best practices).
  6. Commit it to git.

Two failure signals tell you which way to fix the file. Anthropic puts it this way: "If Claude keeps doing something you don't want despite having a rule against it, the file is probably too long." If Claude asks about something the file already answers, the wording is probably ambiguous (best practices). Use emphasis sparingly. Mark only the one rule Claude keeps skipping with "IMPORTANT", because "If you emphasize many lines, none of them stands out."

What CLAUDE.md patterns do top GitHub repos use?

Popular GitHub repos usually use three CLAUDE.md patterns: a command-and-convention sheet, a behavior-principles file, or a shared team file updated after every mistake.

What CLAUDE.md patterns do top GitHub repos use?
PatternPublic exampleWhat it containsGood for unattended runs?
Command and convention sheetEDSL file in awesome-claude-codeBuild/test commands, strict style (Black, mypy), testing requirementsYes, if you add stop rules
Behavior principlesmultica-ai/andrej-karpathy-skillsFour principles about assumptions, simplicity, edit scope, goalsPartly; it has no project commands
Living team fileClaude Code team's own file (Boris Cherny on X)Corrections added whenever Claude gets something wrongYes; it grows from real failures

A few structural habits show up again and again. One is splitting rules by directory or file type: Anthropic documents nested CLAUDE.md files and a .claude/rules/ folder for rules scoped to specific files (memory docs). Another is pointing to longer docs with @path/to/import instead of pasting them in (best practices). Imports help with organization. They don't make the file cheaper if the imported file loads every session anyway. If your repo already has an AGENTS.md, the memory docs say Claude "can also read a repository's AGENTS.md files in place of CLAUDE.md," so you don't need two copies.

Limitation: most public examples are written for someone sitting at the terminal. Hardly any say what the agent should do when it's stuck at 3 a.m., and that's the section you'll need to write yourself.

What does Anthropic's official guidance say about CLAUDE.md?

Anthropic's official guidance treats CLAUDE.md as a short, advisory memory file that loads every session. It covers commands, conventions, and gotchas, and you refine it like code.

The points that matter most for automation, all from Anthropic's docs as of October 2026:

The headless page is where unattended setups most often go wrong. Adding --bare skips auto-discovery of "hooks, skills, custom commands, subagents, installed plugins, MCP servers, auto memory, and CLAUDE.md" (headless docs). The same page warns that "--bare is the recommended mode for scripted and SDK calls, and will become the default for -p in a future release." So a cron job that depends on CLAUDE.md being picked up automatically may stop following it after an update, with no error to tell you.

To make the file load whatever the default turns out to be:

  1. Keep the unattended rules in a file, for example CLAUDE.md or a separate AGENT_RULES.md.
  2. Pass it explicitly. The headless docs list --append-system-prompt-file for adding to the system prompt in bare mode:

``bash claude --bare -p "Run the nightly content check" \ --append-system-prompt-file ./CLAUDE.md \ --allowedTools "Read,Edit,Bash(npm test *)" \ --permission-prompts none ``

  1. Remember that bare mode doesn't use your subscription login. Set ANTHROPIC_API_KEY first (headless docs).

Two more defaults matter. With Claude Code v2.1.302 or later, claude -p starts in Manual mode when nothing sets a permission mode, and a call that needs approval is denied unless something approves it. --permission-prompts requires v2.1.259 or later (headless docs). This is why CLAUDE.md has to tell the agent what to do after a denial. The full flag set is covered in /claude-code-headless-mode-flags-auth-and-cost-2026/.

What do Reddit discussions say works (and fails) in CLAUDE.md?

The usual complaint on Reddit and developer forums is that long CLAUDE.md files get ignored. The fix people recommend is to trim the file to essentials and prune it regularly.

Plenty of community posts carry titles like "Why your long CLAUDE.md gets ignored, and how to fix it", and forum threads ask whether popular rule files actually help (Devtalk). Treat these as anecdotes, not measurements. The pattern does line up with Anthropic's own failure list, which names "The over-specified CLAUDE.md" and says important rules "get lost in the noise".

What community advice tends to get right:

What it tends to get wrong for unattended work:

For example, say your overnight agent keeps editing CI config even though a rule forbids it. Community advice would tell you to move the rule higher in the file. The more reliable fix is a deny rule or a PreToolUse hook on that path, with one line left in CLAUDE.md explaining why. Copy-paste hook scripts for this are in /claude-code-hooks-examples-7-copy-paste-scripts/.

What does Andrej Karpathy say about CLAUDE.md style files?

Karpathy didn't write a CLAUDE.md himself. The popular "Karpathy CLAUDE.md" is a community file built from his posts on how LLMs fail at coding, and it focuses on behavior rather than style.

The repo multica-ai/andrej-karpathy-skills showed about 223.8k stars when checked in October 2026. It turns his observations into four principles: Think Before Coding, Simplicity First, Surgical Changes, and Goal-Driven Execution. The line that matters most for unattended runs is the one the repo quotes from Karpathy: "Don't tell it what to do, give it success criteria and watch it go."

How to use it in a scheduled setup:

  1. Keep "Surgical Changes" and "Goal-Driven Execution". They limit drift and define when the agent is finished.
  2. Rewrite "Think Before Coding" for unattended runs. The original tells the agent to ask for clarification when a request is ambiguous. Overnight, nobody is there to answer, so change that to "write the question to BLOCKED.md and stop."
  3. Add your own commands. The file has no project-specific build or test lines.

Who it's not for: if your CLAUDE.md is already near the size where rules get lost, pasting in a generic principles file makes that worse. Take the two principles you need and leave the rest.

How is CLAUDE.md best practice evolving for 2026 (skills, headless agents)?

In 2026, CLAUDE.md is shrinking. Workflows are moving into skills, hard rules into hooks and permission settings, and the core file is turning into a statement of autonomy boundaries.

The split, according to Anthropic's docs as of October 2026:

How is CLAUDE.md best practice evolving for 2026 (skills, headless agents)?
ContentPut it inWhy
Always-true commands, conventions, stop rulesCLAUDE.md"CLAUDE.md is loaded every session, so only include things that apply broadly"
Occasional domain knowledge or workflows.claude/skills/<name>/SKILL.mdClaude loads skills on demand (best practices)
Workflows with side effectsSkill with disable-model-invocation: trueOnly runs when you trigger it (best practices)
Must-never-happen actionsHooks, deny rulesDeterministic (hooks guide)
"Keep going until tests pass"/goal condition or a Stop hookLets "an unattended run finish correctly without you"

Skills also work headless. User-invoked skills run in -p mode if you include /skill-name in the prompt string (headless docs). A clean nightly setup looks like this:

  1. CLAUDE.md, about a screen long: commands, autonomy rules, "when blocked", "done means".
  2. A skill such as /nightly-report that holds the step-by-step procedure.
  3. Cron calls claude -p "/nightly-report" --permission-mode dontAsk --allowedTools "...". Under dontAsk, Claude Code "denies every call that would otherwise prompt" (headless docs).
  4. A Stop hook runs your test command, so the run can't end while tests are red.

Auto mode is the other 2026 change. From v2.1.283 it's the starting permission mode for interactive terminal and VS Code sessions, with a classifier that blocks actions like scope escalation (best practices). It reduces prompts, but it doesn't replace stop rules. The classifier judges risk. It doesn't know your business rules, such as "never publish on Sundays". Scheduling details are in /claude-code-cron-job-setup-run-automations-overnight/.

What do practitioner write-ups (Medium, Boris Cherny) add to best practices?

Practitioners, including Claude Code creator Boris Cherny, add one habit: update CLAUDE.md after every mistake you catch. Keep the file small enough that the new rule doesn't get lost.

Cherny described the Claude Code team's setup on X in January 2026. They share one CLAUDE.md for the repo, check it into git, and "the whole team contributes multiple times a week". Whenever Claude gets something wrong, they add it to the file. In a follow-up post, he said he tags @.claude on coworkers' PRs to add CLAUDE.md lines through the Claude Code GitHub Action. For very long tasks, he mentioned having Claude verify its work or using a Stop hook (thread).

Adapted for unattended runs:

  1. Each morning, read the run's REPORT.md and BLOCKED.md.
  2. For each real mistake, decide on the fix. A one-line CLAUDE.md rule works if the mistake was a judgment call. A hook or deny rule is better if it must never happen again.
  3. Add the line in the same commit as the fix.
  4. Once a month, delete rules the agent now follows without being told.

Pitfall: a file that only grows. Adding a line after every mistake without ever pruning produces exactly the bloated file Anthropic warns about. A related mistake is reacting to a stalled run by adding more instructions. Stalls usually come from permissions or context, not missing rules. Check /why-claude-code-stops-mid-automation-and-how-to-fix-it/ before you edit the file.

Next steps

Do today (DIY):

  1. Open your project, run /init (or open your existing file with /memory), and cut every line that fails "Would removing this cause Claude to make mistakes?"
  2. Add four sections from the example: "Autonomy: decide alone", "Autonomy: stop and report", "When blocked", and "Done means".
  3. If your cron job uses -p, add --append-system-prompt-file ./CLAUDE.md now, so the coming --bare default doesn't silently drop the file.

If you'd rather not do it yourself: Anthropic's paid plans include Claude Code. Pro is $20/month ($17/month billed annually), and Max starts at $100/month (as of October 2026; check the official pricing page). Pro suits one person running light scheduled jobs. It's not a good fit if you need many long runs per night, because Claude Code "shares the same usage limits as the rest of your plan." Bare-mode runs bill through an API key instead, so they don't draw on a subscription. Anthropic also publishes a Claude Code 101 course on CLAUDE.md; check the page for current access terms. It suits beginners, but it won't write your stop rules for you.

Related guides on this site:

FAQ

Where can I find CLAUDE.md best practices examples?

Anthropic's best practices page has a short official sample and an include/exclude table. Community examples are collected in awesome-claude-code. The template in this guide adds the unattended sections most public examples leave out.

What are Anthropic's CLAUDE.md best practices?

Keep it short. Include only commands, rules that differ from defaults, and gotchas. Check it into git and prune it regularly. Anthropic also says CLAUDE.md is advisory, so anything that must always happen belongs in a hook (best practices).

Are there good CLAUDE.md best practices on GitHub?

Yes. The most-starred example is multica-ai/andrej-karpathy-skills, a behavior-principles file. Language-specific files such as the EDSL example in awesome-claude-code show the command-sheet pattern. Either way, add your own commands and stop rules.

What are the Karpathy CLAUDE.md best practices?

They're four principles taken from Karpathy's posts: Think Before Coding, Simplicity First, Surgical Changes, and Goal-Driven Execution. Karpathy didn't publish the file himself; the multica-ai repo did. For unattended runs, change "ask for clarification" to "log the question and stop".

Sources

Spotted something out of date or wrong? Tell us at shigoto.ai.note@gmail.com. Guides are re-checked against official sources on a rolling schedule.

Read next

  1. · 10 min read

    Claude Code Cron Job Setup: Run Automations Overnight

    Claude Code cron job setup: auth tokens, PATH, working directory, permissions, locks and log rotation, so overnight claude -p runs don't fail silently.

  2. · 10 min read

    Claude Code Rate Limit Reached: Retry Setup for Cron Jobs

    Claude Code rate limit reached? Tell a 429 throttle from a plan or spend cap, read the retry-after headers, and set safe auto-retries for headless cron jobs.

  3. · 16 min read

    Claude Code Permissions Best Practices: Headless Template

    Claude Code permissions best practices for unattended runs: a settings.json allow/deny template, mode picks, and pre-flight checks so overnight jobs finish.