The architect’s playbook

Design the whole system.

Connect people, agents and decisions through clear responsibilities, boundaries and evidence.

"The goal isn't a powerful tool. The goal is a system that teaches itself."

The difference between using Claude Code and building with Claude Code is the OS mindset. When you think of CLAUDE.md, Skills, Agents, and Memory as an operating layer - not just a chatbot - the whole game changes.

Every instruction you encode reduces friction forever. Every routing rule you write gets smarter with each session. Every memory entry means you never repeat that context again. The system compounds. Your leverage grows.

Organization

Agent subgroups

As your agent roster grows, organize agents into functional subgroups. A subgroup is a named domain with a shared memory space and a shared learning channel. It keeps agent knowledge scoped and prevents cross-domain drift.

Example: registry.yaml subgroup entry

# registry.yaml

subgroups:
  - name: publishing
    purpose: Book production, editorial gates, KDP metadata
    memory: memory/publishing/MEMORY.md
    retrospectives: memory/publishing/retros.md
    agents:
      - doc-writer
      - doc-editor
      - safety-reviewer

  - name: session-management
    purpose: Session state, continuity, work items
    memory: memory/session-mgmt/MEMORY.md

Why subgroup memory matters

Without subgroups, every agent draws from one global memory pool. As the roster grows, agents get noise from domains they don't need. Subgroups scope the signal. A publishing agent only reads publishing memory. A session agent only reads session memory.

The knowledge steward routes learning to the right subgroup automatically when you use learning handoffs.

Subgroup design principles

Group by functional domain, not by project
Each subgroup should have at least 2 agents before creating it
Subgroup memory files stay small - summaries only, not raw logs
Agents can belong to only one subgroup in registry.yaml
Cross-subgroup coordination goes through the main orchestrator

Precision work

Routing rules

A routing rule tells the system when to use a specific agent and when to avoid it. Triggers say what should fire. Anti-triggers prevent misrouting - the most common source of wasted cycles.

Routing rule format (agent-routing.md)

### my-specialist-agent *
**Triggers:** "research X", "analyze Y", "review Z for W", "find patterns in",
            "what does the data say about", "run analysis on"
**Anti-triggers:** Does not write code (use my-code-agent); does not send messages
               (use email-dispatch-coordinator); does not touch production
**When to prefer over general-purpose:** Any task requiring domain-specific
  structured analysis with PASS/FAIL verdicts. Distinct from general-purpose
  which produces free-form responses without a verdict gate.

The anti-trigger is the key

Most routing failures happen when an agent is invoked for something it shouldn't do - not because the trigger was wrong, but because the boundaries weren't clear. Anti-triggers are the explicit "not this" that prevents your research agent from trying to push code.

Write anti-triggers from real misrouting events. After you catch a wrong agent invocation, ask: "what anti-trigger would have prevented this?" Add it.

Pattern	Good routing	Why
Domain + action word	Strong trigger	Specific enough to prevent false positives
Generic verb alone	Weak trigger	"analyze" alone matches too many agents
Explicit "does not" boundaries	Required for every agent	Prevents cross-domain misrouting
Model tier specified	Best practice	Controls cost; Haiku for lookups, Opus for decisions

Persistent learning

The knowledge store

The knowledge store is where validated learning lives across sessions. When an agent produces a notable finding - a routing fix, an architecture decision, a pattern that works - it routes there. Future sessions query it before substantial tasks.

Agent registry entry with learning routes

# registry.yaml - agent entry

agents:
  - name: my-specialist-agent
    subgroup: publishing
    purpose: Editorial gate for children's books - developmental safety
    model_tier: opus
    learning_routes:
      - gate_verdicts: memory/publishing/MEMORY.md
      - revision_patterns: memory/publishing/retros.md
      - global_findings: memory/knowledge-store.json

Query before substantial tasks

Before any complex analysis or architectural work, run the knowledge query to surface relevant past findings. You don't want your routing agent solving a problem that was already solved last month.

The pattern: python scripts/knowledge-query.py "your topic" - searches global memory, subgroup memories, and recent digests in one pass.

Autonomous execution

Overnight and autonomous patterns

Long-running autonomous sessions need structured discipline. Without it, they stall, loop, or produce output that can't be verified. These four patterns prevent the most common failure modes.

1. The STEP ZERO requirement

Every autonomous session must write a session start file as its very first action - before reading anything, before planning anything. This single write proves the session is running and sets the expected output list.

If STEP ZERO is missing after 5-10 minutes, the session is stalled. Kill it and relaunch.

Overnight monitor loop pattern

# Overnight session monitor - correct cadence
# Run in a separate terminal to watch progress

while true; do
  echo "=== $(date -u +%Y-%m-%dT%H:%M:%SZ) ==="
  # Check for checkpoint files
  ls /path/to/runs/*checkpoint*.md 2>/dev/null
  # Check session is still writing (file modified in last 30 min)
  find /path/to/runs/ -name "*.md" -newer /tmp/.heartbeat 2>/dev/null
  sleep 900  # 15 minutes - correct interval
  # Never use 60s (noisy) or 300s (prompt cache dead zone)
done

Long-running session launch (nohup pattern)

# Launch a long-running autonomous session
# Replace paths and prompt file with your own

nohup bash -c "cd '/your/project/root' && \
  claude.exe < 'docs/overnight-ops/prompts/your-prompt.md'" \
  > '/tmp/session-output-$(date +%Y%m%d).log' 2>&1 &

disown
echo "Session launched. PID: $!"

# IMPORTANT: Always use absolute CWD path
# Never bare nohup claude.exe - inherits wrong CWD

Checkpoint cadence

A healthy 8-hour session should write 4-6 checkpoint files. Each checkpoint proves progress, lists what was completed, and sets up recovery if the session stalls. A session that runs 4 hours with no checkpoints has either completed all work (unlikely) or is silently looping (common).

Write checkpoints after major milestones - not on a timer. "After the gate passes" is better than "every 90 minutes."

The 300s sleep dead zone - why it matters

The Anthropic prompt cache has a 5-minute TTL. Sleeping exactly 300 seconds in a monitor loop means each wake-up pays for a full cache miss without getting any amortization benefit. The right choices are under 270s (stay in cache) or 900s+ (amortize the cold start). 300s buys neither. Always use 900s for overnight monitoring.

Non-negotiables

Production safety

Hard constraints aren't style preferences. They're the guardrails that make autonomous work safe. The approval gate pattern is how you stay in control without being present.

1
Hard constraints in CLAUDE.md are governance, not suggestions. If "never send emails without approval" is a hard constraint, an agent that sends email without that approval phrase has violated a governance rule - not just a preference. Write hard constraints as if they were audit-trail items.
2
Production-touching actions require explicit approval phrases. An agent proposes. A human approves with a specific phrase. The agent executes only after the phrase is present. This pattern prevents autonomous agents from taking irreversible actions while still allowing them to prepare everything.
3
Reversibility audit before any multi-step task. Before starting, identify which steps are irreversible. For each irreversible step, add a checkpoint and a human review gate. If it's all reversible, let it run. If any step is permanent, it needs eyes on it first.
4
No secrets in prompts, files, or agent outputs. API keys, credentials, tokens - none of it goes in files that agents read or write. Use environment variables and reference them by name. Agents confirm the secret exists; they never read or copy the value.

Approval gate pattern

# Approval gate pattern
# Agent prepares everything. Human provides the phrase. Agent executes.

# In your CLAUDE.md:
## Hard constraints
- Never deploy to production without the phrase:
  APPROVE_DEPLOY:{service}:{description}
- Never send external communications without the phrase:
  APPROVE_SEND:{channel}:{draft-id}

# Agent output will say:
# "Ready to deploy. Provide approval phrase to proceed:"
# "APPROVE_DEPLOY:my-service:v2.1.0-hotfix"

# You paste the phrase. The agent acts.
# No phrase = no action. Simple. Reliable.

The long game

The system that teaches itself

Every routing fix, every memory entry, every approval gate refinement makes the next session slightly better. The compounding effect isn't obvious at first. At month three, it becomes unmistakable.

What compounding actually looks like

Month 1: You're correcting the same things repeatedly. You're building CLAUDE.md in real time. Every session has friction.

Month 2: You notice patterns. You encode them. You write routing rules from real misrouting events. Memory entries mean you stop repeating context.

Month 3: Sessions start with full context. Agents route correctly on the first try most of the time. Your skills handle the repetitive work. You're spending your time on things only you can decide.

The system didn't get smarter. You trained it. That's the whole game.

The pattern that built this resource

Everything in this guide was learned from real production use - real routing failures, real overnight sessions, real approval gate violations. The principles aren't theoretical. They come from the hard lessons of building exactly this kind of system.

More patterns, architecture notes, and open knowledge at rafikiaos.com. The Explorer and Builder guides are good starting points if you want to share this with a colleague who's newer to the practice.