Atlas
kb://agents/claude-code-best-practicesstable2026-05-21

Claude Code — what works, what doesn't

agentsclaude-codesub-agentsopussonnetdispatch

Practical learnings from running Claude Code as the lab's primary implementation agent across multiple sessions in 2026.

Model selection by task shape

  • Opus — design, architecture, multi-file refactors, anything that needs to hold the whole graph in working memory at once.
  • Sonnet — fanout sub-agents (well-defined work, short context, fast turnaround). Cheaper, faster, identical quality for scoped tasks.
  • Haiku — log-analysis-style tasks where pattern matching is the whole job.

The lab default is Opus for the main session and Sonnet for dispatched sub-agents.

When to dispatch a sub-agent

Heavy tasks (> 2 min) must go to a background sub-agent so the main session stays responsive to TG (rule: feedback-parallel-only-2026-05-02). Concrete triggers:

  • Building a Rust workspace crate end-to-end
  • Running a full feature scan with openalice-inspector
  • Writing 4+ files in parallel where the writes are independent
  • Any task with a clear acceptance gate (tests pass / SHA matches)

Sub-agent prompt discipline

A good sub-agent prompt has four blocks:

  1. Goal — the single sentence outcome
  2. Constraints — disk / parallelism / scope (see kb://infrastructure/cargo-j4-discipline for the Rust template)
  3. Acceptance — what success looks like (test command, hash, etc.)
  4. Hand-off — what to report back (commit SHA, line counts, blockers)

Dispatching without an acceptance gate is the leading cause of agents that "succeed" but leave the repo in a broken state.

Anti-patterns

  • ❌ Dispatching > 3 cargo-heavy sub-agents at once on blal.de
  • ❌ Running cargo test --workspace from a sub-agent (60 GB target incident, kb://incidents/2026-05-21-target-disk-95-percent)
  • ❌ Letting a sub-agent edit Cat-A personality blocks (see kb://agents/alice-soul-preservation)
  • ❌ Asking Opus to do mechanical fanout work — Sonnet is faster and identical quality at that shape

Time-boxing investigations

Deep investigation in Opus is valuable, but unbounded investigation burns tokens with no acceptance gate. The lab rule of thumb: budget the investigation, declare the budget out loud, and write down what was found even if the budget runs out. A note in kb://learnings/ is better than an unwritten realisation.

Hand-off discipline across sessions

Session memory at /home/blal/.claude/projects/-home-blal-projects-org-openalicelabs-openalice/memory/ survives compaction. The KB at openalice-atlas/knowledge/ survives session deletion. Both are valuable; both have rules:

  • Memory = personal-to-this-agent notes, append-only by archive
  • KB = org-wide knowledge, cross-link by kb://
  • Charter / docs = canonical decisions, supersede with dated revision

When in doubt: log it in both.