Claude Code Routines: What the Official Docs Do Not Tell You
Anthropic just officially documented Routines in Claude Code. The HN thread hit 122 points on a docs link — unusually high signal for documentation.
Here is what the docs cover, what they skip, and what we learned running Routines in production across a 5-agent system for 30+ days.
What the Docs Say
Routines let you define reusable sequences of instructions that Claude Code executes on demand. Trigger them via slash commands, hook them into session start/stop events, or chain them together.
# .claude/commands/deploy-check.md
Run git status, check for uncommitted changes, verify tests pass, then summarize what is ready to ship.
Most teams stop there.
What the Docs Skip
1. Routines Are Stateless Between Calls
Each invocation has no memory of the previous run unless you explicitly write state to disk. Our morning briefing Routine was re-summarizing the same 3 files every day.
Fix: write a .last-run timestamp at the end of each Routine, check it at the start.
# morning-brief.md
1. Read ~/Desktop/Agents/Atlas/last-run.txt
2. If last run was today, output: "Already ran today. Skipping."
3. Otherwise: [do the actual work]
4. Write today's date to ~/Desktop/Agents/Atlas/last-run.txt
2. Hooks Fire on Events, Not Conditions
PreToolUse and PostToolUse run when a tool is called — not when a file changes or a condition is met. For condition-based triggers you need an external cron or watchdog. We use a 90-second polling loop in our orchestrator.
3. Routine Chaining Has a Depth Limit
Deep chains (A → B → C → D) hit context accumulation issues fast. Each hop adds overhead. Practical limit: 3 hops before you flatten or hand off to a subagent.
4. Permissions Are Per-Session, Not Per-Routine
If a Routine needs bash and bash is not auto-approved, the Routine silently stalls in an unattended setup. Fix: pre-approve required tools in settings.json before scheduling overnight runs.
5. Routines Are Not Versioned by Default
Your .claude/commands/ directory lives in your repo. Update a Routine and every running agent picks up the change immediately. We updated a deploy-check Routine mid-sprint and a background agent changed behavior unexpectedly mid-task.
Fix: version your Routines (deploy-check-v2.md) or stamp a last-modified date in the header.
Production Patterns We Use
Morning Orchestration: Fires at session start, reads the task queue, picks highest-priority item, hands off to the right agent.
EOD Report: Summarizes all session outputs into a single markdown file after the last wave. Writes to Atlas-Memory/Daily-Reports/.
Self-Healing: Checks for stuck workers (no output in 15+ min), kills and restarts them, logs the incident. Saved multiple overnight runs.
The Real Value
Routines are not just saved prompts. They are the skeleton of a repeatable operating system for your AI workflow. Treat .claude/commands/ like production infrastructure — versioned, tested, documented.
The docs show you the door. This is what is behind it.
Building multi-agent systems with Claude Code? The Atlas Starter Kit includes 12 production Routines, wave-based orchestration, and a self-healing worker template. $97 at whoffagents.com.
