Claude Code Agents Ship Faster — Workflow Guide That Wins

Engineers drown in toil: exploring unfamiliar code, writing boilerplate, running the same checks. Autocomplete helps with lines, but features and migrations span dozens of files. That gap eats sprints.

Claude Code closes it. It's an agentic CLI that reads your repo, plans the work, edits files, runs tests, and iterates — supervised by you. You'll feel the shift the first time a migration finishes before lunch.

Subagents, plan mode, and project memory turn one-off prompts into repeatable workflow. The agent remembers conventions, researches safely, and delegates side quests.

But agents with file access need discipline. Skipped planning, mega-sessions, and blanket permissions cause real damage. This guide builds the workflow that ships.

Why Agents Beat Autocomplete for Real Tasks

Autocomplete predicts the next lines from nearby code. It cannot explore a repo, run tests, or hold a multi-step plan — every architectural decision stays yours, every file navigation manual. Fine for boilerplate, useless for migrations.

Claude Code inverts the relationship: you state the outcome, it handles the steps. It searches codebases, drafts plans, edits files, executes commands, reads failures, and retries. Supervision moves up a level — from keystrokes to intent and review.

The economics follow: an engineer's leverage shifts from typing speed to judgment quality. Teams that adapt spend review time where it matters (architecture, edge cases) and let agents absorb the mechanical middle.

Custom Subagents — Specialists You Commit

Custom subagents are Markdown files with YAML frontmatter: name, description (the trigger Claude matches), tools (scoped access), and a prompt body (the specialist's instructions). The example above is a read-only security reviewer — powerful because it cannot edit, only advise.

Descriptions are the API: crisp trigger phrases ('use when touching login, session, OAuth') get matched; vague ones ('helps with code') never fire. Scope tools ruthlessly — a reviewer needs Read and Grep, never Write.

Commit project subagents (.claude/agents/) to version control; keep personal ones in ~/.claude/agents/. Team-reviewed specialists improve like code; hallway-prompted ones evaporate.

# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Reviews auth and payment modules for security issues. Use when touching login, session, OAuth, or billing files.
tools: Read, Grep, Glob
model: inherit
---

You review auth and payment code. For each finding report:
1. File and line, with the vulnerable pattern quoted
2. Exploit scenario in one sentence
3. Minimal fix with a code sketch

Rules: read-only — never edit. Cite OWASP where relevant.
Focus on injection, auth bypass, and secret leakage.

Plan Mode — Research First, Edits After Approval

Plan mode separates research from action: Claude explores via the Plan subagent, presents the approach, and waits. The main session stays read-only; exploration output never floods your context. Approve, and execution starts from understanding instead of guessing.

Use it for anything beyond three files, any unfamiliar module, and every migration. The five minutes of review prevent the half-day revert in the incident above.

Explicit invocation guarantees routing: 'Use the code-reviewer agent to check the auth module.' Automatic matching handles the rest once descriptions are sharp. Both beat hoping.

CLAUDE.md — Conventions Once, Inherited Everywhere

CLAUDE.md is project memory loaded automatically into every session: commands, boundaries, style. The hierarchy (user, project, directory, local) layers conventions without repetition. Subagents inherit it (except built-in Explore/Plan), so rules propagate to delegated work.

Write boundaries as hard rules ('ask before touching outside src/auth/'), not suggestions. Agents obey explicit scope; they improvise around vibes.

Maintain it like a README: update when conventions change, prune when rules rot. A stale CLAUDE.md teaches every session the wrong lesson simultaneously.

# CLAUDE.md — project memory, loaded every session
# Auth Service Conventions

## Commands
- Test: `pytest tests/ -x -q`
- Lint: `ruff check . && ruff format --check .`
- Migrate: `alembic upgrade head` (never downgrade in dev)

## Boundaries
- Never edit `migrations/` by hand; generate via alembic.
- Payments code needs the code-reviewer agent before PR.
- Ask before touching anything outside `src/auth/`.

## Style
- Type hints required; no `Any` in new code.

Workflows and Teams — Scale Past One Conversation

Dynamic workflows tackle jobs too big for one conversation: repo-wide audits, 500-file migrations, cross-checked research. Claude writes an orchestration script; the runtime fans out dozens of agents in the background while your session stays responsive.

The trade is tokens and interaction: single runs cost meaningfully more than conversations, with intermediate state in script variables instead of chat. Monitor /workflows totals and reserve workflows for scale that justifies the spend.

Agent teams and background sessions cover the middle: supervised worker groups for collaborative jobs, agent view (claude agents) for independent tasks you check between other work. Match the coordination tool to the job size.

---
description: Migrate review — plan, delegate review, test, report
---

1. Enter plan mode and draft the migration plan for $ARGUMENTS.
2. Ask for approval before editing any file.
3. Delegate security review to the code-reviewer agent.
4. Run the test suite and report file list plus results.

The Production Workflow — Compose It All

The production workflow composes everything: CLAUDE.md briefs, plan mode approves, subagents specialize, permissions bound, workflows scale. Review agent diffs like human PRs — architecture judgment stays human, mechanical execution delegates.

Cost control is explicit: route review passes to cheaper models, track workflow tokens, and prefer single sessions with subagents over workflows for routine work. Token budgets are engineering budgets.

Start small: one custom reviewer, one CLAUDE.md, plan mode always. Add workflows when a job outgrows conversation — not before. Discipline compounds faster than autonomy.