claude-code pattern beginner 15 minutes

One Claude Code Binary, Ten Different Agents — Shell Aliases as Workflow Modes

You don't need ten different AI tools. You need one tool that knows which job it's doing right now — and which model and effort level that job deserves. Ten lines in your shell config give you that.

I don’t run claude anymore. I run claude-dev for daily coding. claude-architect when a task needs deeper design reasoning. claude-cowork to think through strategy. claude-review to audit for gaps. claude-content to draft. Same binary, completely different behavior — because each alias sets model, effort level, and system prompt in one shot.

Most people use Claude Code in one mode: general purpose, default model, default effort. It’s decent at everything and excellent at nothing. The fix is ten lines in your .zshrc.

The Setup

# ~/.zshrc — Claude Code contexts: model + effort + system prompt per workflow
alias claude-dev='claude --model sonnet --effort medium --append-system-prompt "$(cat ~/.claude/contexts/dev.md)"'
alias claude-architect='claude --model opus --effort high --append-system-prompt "$(cat ~/.claude/contexts/dev.md)"'
alias claude-cowork='claude --model opus --effort medium --append-system-prompt "$(cat ~/.claude/contexts/cowork.md)"'
alias claude-review='claude --model sonnet --effort medium --append-system-prompt "$(cat ~/.claude/contexts/review.md)"'
alias claude-research='claude --model sonnet --effort medium --append-system-prompt "$(cat ~/.claude/contexts/research.md)"'
alias claude-trade='claude --model opus --effort medium --append-system-prompt "$(cat ~/.claude/contexts/trade.md)"'
alias claude-content='claude --model sonnet --effort medium --append-system-prompt "$(cat ~/.claude/contexts/content.md)"'
alias claude-obaron-author='claude --model sonnet --effort medium --append-system-prompt "$(cat ~/.claude/contexts/obaron-author.md)"'
alias claude-obaron-author-bespoke='claude --model opus --effort medium --append-system-prompt "$(cat ~/.claude/contexts/obaron-author.md)"'
alias claude-obaron-editor='claude --model sonnet --effort medium --append-system-prompt "$(cat ~/.claude/contexts/obaron-editor.md)"'

Three decisions are baked into each alias, not left to chance:

  • Model. Sonnet for speed and cost (coding, review, research, content). Opus when the task demands sustained multi-step reasoning (architecture, trading logic, strategy, client deliverables).
  • Effort. medium covers most tasks. high buys extended thinking — worth it when shallow reasoning causes expensive rework later. claude-architect is the one alias where high effort earns its cost.
  • Context. A short system prompt — 50 to 200 lines — that defines what to prioritize, how to respond, and which patterns to follow.

One flag choice matters: --append-system-prompt, not --system-prompt. Append layers your context on top of Claude Code’s default — tool guidance, memory, CLAUDE.md auto-discovery all stay intact. The non-append form replaces the default entirely. That’s a power-user escape hatch; for everyday mode-switching, append is right.

The Modes

claude-dev / claude-architect — The Escalation Pair

These two share the same context file. The difference is model and effort.

claude-dev runs Sonnet at medium effort — fast, cheap, right for 90% of coding work. claude-architect switches to Opus at high effort — the same dev context, but with heavier reasoning and extended thinking engaged. Same domain knowledge, different depth.

The practical rule: start tasks in claude-dev. When a decision involves system design, cross-cutting changes, or choices you’ll live with for months, escalate to claude-architect. The extra cost is earned.

Key behaviors the context installs:

  • Check for a plan file before starting — ask if there isn’t one
  • Stay in the current repo — don’t wander into adjacent systems
  • Write code and tests, not proposals
  • Commit incrementally with clear messages

claude-cowork — Strategy and Planning

Opus, medium effort. The thinking mode. Reads business docs, asks questions before proposing solutions, writes plans instead of code. When you say “we need to harden security,” it doesn’t jump to settings.json — it asks what the threat model is, writes a phased plan, and connects each phase to a specific risk.

Key behaviors:

  • Read context docs (context.md, playbook.md, principles.md) before responding
  • Think in terms of plays, actions, and outcomes
  • Write plans to disk, not code
  • Ask clarifying questions — don’t assume

Opus is right here because strategy synthesis requires holding many competing considerations at once. Sonnet hedges. Opus commits.

claude-review — Adversarial Audit

Sonnet, medium effort. The skeptic. Reads whatever you point it at and looks for gaps, risks, and incorrect assumptions. Groups findings by severity. Suggests specific fixes, not just “this could be better.” Verifies claims by checking actual tool behavior instead of trusting the document’s premises.

Key behaviors:

  • Read the entire artifact before commenting
  • Group findings: critical → medium → low
  • Every finding includes what the plan claims, what’s actually true, and a specific fix
  • Independently verify technical claims — don’t trust the document

claude-research — Deep Investigation

Sonnet, medium effort. Reads docs, traces behavior, surfaces answers. Doesn’t speculate — if it can’t verify a claim, it says so and explains how to confirm it. Used when you need to understand how something actually works before making a decision.

claude-trade — Trading Logic

Opus, medium effort. Market decisions and portfolio logic need more reasoning capacity than a typical coding task. Opus handles the multi-step conditional logic (position sizing, market regime checks, risk controls) without shortcuts.

claude-content / claude-obaron-author / claude-obaron-editor — The Content Stack

Three roles for writing work, all on Sonnet at medium effort.

claude-content is the general writing mode — drafts, site copy, articles. claude-obaron-author loads the Obaron author context: client voice guidelines, offer framing, content architecture patterns. claude-obaron-editor reviews what claude-obaron-author produced — tightens, cuts, flags anything that drifts from voice.

claude-obaron-author-bespoke — The Bespoke Variant

Same context as claude-obaron-author, but on Opus at medium effort. One alias, one decision: is this a draft or a deliverable?

For internal drafts and exploratory content, Sonnet is fast and good enough. For client deliverables where the output goes directly to a paying customer, the model upgrade is worth it. Same context file — you’re not changing what Claude knows about the work, just how hard it thinks.

This pattern (two aliases, same context, different model) is the most useful thing in this whole setup. It lets you scale compute to stakes without changing your workflow.

The Real Power: Handoffs

Any single mode is useful. The handoffs between them are where it gets interesting.

claude-cowork: "We need to harden Claude Code security on the Mac Mini"
  → writes plans/cc-security-hardening.md

claude-review: "Review plans/cc-security-hardening.md"
  → finds 3 critical gaps, suggests restructuring around sandbox-first

claude-cowork: "Update the plan to address the review findings"
  → rewrites the plan with sandbox as Phase 1

claude-architect: "Review the implementation approach in plans/cc-security-hardening.md before we build"
  → surfaces a cross-cutting concern the planning pass missed

claude-dev: "Implement the settings.json from plans/cc-security-hardening.md"
  → applies the config, runs verification

Each mode reads the artifacts the previous mode created. The plan file is the handoff contract. No mode needs to know what the other modes did — it reads the file and does its job.

Notice where claude-architect slots in: after planning, before implementation. It’s not the default coding mode — it’s the quality gate you run when the stakes of getting the design wrong are high. Most tasks skip it entirely. That’s fine. The alias exists for when you need it.

Writing Your Own Contexts

Start with one mode that addresses your biggest pain point. If you keep getting into strategy discussions when you want to code, write a dev context. If your plans keep shipping with gaps, write a review context.

A context file has three sections:

## Role
You are [role description]. Your job is [primary objective].

## Priorities
1. [Most important behavior]
2. [Second most important]
3. [Third]

## Patterns
- [Specific instruction for common situation]
- [Specific instruction for common situation]
- [What NOT to do]

Keep it under 200 lines. A focused 80-line prompt beats a comprehensive 400-line one.

When you wire up the alias, make three decisions:

  1. Model. Default to Sonnet. Upgrade to Opus when the task requires deep multi-step reasoning or when the output goes to a client.
  2. Effort. Default to medium. Use high for architecture and design sessions — high engages extended thinking. Skip it for execution tasks where you want speed.
  3. Shared context or separate? If two aliases cover the same domain at different quality levels (drafts vs. deliverables, dev vs. architect), point them at the same context file and vary the model. One file to maintain, two aliases that scale to the task.

Version-control your context files. They evolve as your workflow matures. The review context I use today is the third iteration — each round of use revealed behaviors I wanted to add or remove.

Why This Works

General-purpose Claude Code is trying to be good at everything simultaneously. It hedges. It asks if you want a plan or code. It offers alternatives when you want execution. It’s playing defense because it doesn’t know what game you’re playing — and it doesn’t know how hard to think or how much reasoning to spend.

A mode alias removes all three unknowns at once. “You are reviewing this plan for gaps, on Sonnet, at medium effort” is a clear job with a clear budget. Claude stops hedging and starts doing. The quality of output in each mode is noticeably higher than general-purpose because Claude isn’t spending reasoning tokens figuring out what you want and how hard to try — you already answered both.

The other thing: you stop making micro-decisions during work. You don’t ask yourself “should I use Opus for this?” — you just type claude-architect when the task looks like architecture, and claude-dev for everything else. The decision is already made, sitting in your shell config.

Ten lines in .zshrc. Fifteen minutes to write your first context file. Permanently better workflow.

FAQ

Do mode aliases replace CLAUDE.md project instructions?

No — if you use `--append-system-prompt`. That flag layers your mode on top of Claude Code's default system prompt, so CLAUDE.md auto-discovery, tool guidance, and the memory system all keep working. Your project CLAUDE.md still loads. The mode just changes Claude's operating posture.

How long should a mode system prompt be?

50-200 lines. Claude's context window is precious — a focused 100-line prompt that defines priorities, response style, and key patterns beats a 500-line comprehensive document. Keep it short enough that Claude actually follows all of it.

Should I use --system-prompt or --append-system-prompt?

Append. It adds your mode on top of Claude Code's default system prompt, which carries tool guidance, memory, and CLAUDE.md auto-discovery — the scaffolding that makes Claude Code useful. `--system-prompt` (no append) replaces the default entirely. That's a power-user escape hatch for when you want full control of the prompt from scratch. For everyday mode-switching, append is the right answer.

Do the aliases work across different repos?

Yes. The alias is global (defined in ~/.zshrc or ~/.bashrc), but the behavior adapts to whatever repo you run it in. Claude still reads the local CLAUDE.md and project context. The alias just changes how Claude approaches the work.

When should I pick Opus over Sonnet in a mode alias?

Reach for Opus when the task requires sustained multi-step reasoning — architecture decisions, strategy synthesis, trading logic, high-value client work. Sonnet handles most coding, review, research, and content work well at lower cost and latency. The dev→architect escalation pattern makes this concrete: same context file, but claude-architect adds Opus + high effort when you need deeper design reasoning.

What does --effort control?

`--effort` sets how much extended thinking Claude does before responding. `medium` is the default and covers most tasks. `high` tells Claude to spend more tokens on reasoning — worth it for architecture sessions where a shallow plan costs you days later. Most aliases default to medium; claude-architect uses high because shallow architecture thinking is exactly the failure mode it's meant to prevent.