Julián Úsuga
Index

How to Use Claude Code

The compact October 2026 edition — setup once, CLAUDE.md vs AGENTS.md, the commands that earn their keep, subagents and mixing models, hooks, and a sane default workflow.

Julian Úsuga Posted Updated howto · claude · tools

The 5-Minute Setup

  1. /init once per repo. Generates CLAUDE.md so every session starts with project context (or reuse an existing AGENTS.md — see below).
  2. Plan mode for anything non-trivial (Shift+Tab). Claude reads and proposes; nothing gets touched until you approve the plan.
  3. One hook for the thing you’d otherwise repeat every session — a formatter, a linter. See below.
  4. /doctor if anything feels off. It diagnoses installs, PATH problems, settings, and slow hooks.

Project Instructions: CLAUDE.md or AGENTS.md

Every session starts from zero. The instruction file is how it starts from your project instead.

Which file. AGENTS.md is the cross-tool standard (Codex, Cursor, Gemini), and Claude Code reads it natively since v2.1.277. CLAUDE.md still works and wins by default:

Your repo hasClaude reads
Only AGENTS.mdAGENTS.md
AGENTS.md and CLAUDE.mdCLAUDE.md only
CLAUDE.md containing @AGENTS.mdBoth, through the import

If you use several agents, keep everything in AGENTS.md and add a CLAUDE.md only for Claude-specific lines, starting with @AGENTS.md. If you only use Claude Code, CLAUDE.md is fine. One trap: a personal CLAUDE.local.md also counts, so adding one silently stops AGENTS.md from loading. Change the default in /config → Project instructions.

What goes in. What Claude can’t cheaply figure out by reading the code:

  • The commands: build, test, lint, and the flags that matter.
  • Non-obvious architecture: where things live, what’s generated, what not to touch.
  • Conventions the linter doesn’t enforce, and the gotchas that already cost you an afternoon.

What stays out. Anything a linter or formatter already enforces, anything obvious from the code, and long docs — link them instead. The file loads into every session and every turn pays for it.

Keep it alive. Short and specific beats long and complete. When you correct Claude twice on the same thing, add a line. When a rule applies only to some files, move it to .claude/rules/ with a path scope. Claude also keeps its own auto memory of your corrections, and /doctor prompt-audit reviews all of these files for bloat and contradictions.

Instructions are context, not enforcement. If something must never happen, make it a hook.

Commands That Earn Their Keep

Grouped by job, not alphabetically. /help lists everything; most of the rest you won’t miss.

Before you ship — /diff shows what changed. /code-review checks the diff (pass a PR number to review that instead, --fix to apply findings, ultra for a deep multi-agent cloud pass). /security-review for auth, input handling, and secrets.

Between sessions — /clear starts fresh while keeping project memory. /compact summarizes instead of dropping. /resume returns to an earlier conversation, /branch tries a different direction, /fork copies it into a background session.

Parallel work — /tasks lists background work. /background detaches the session so it keeps running. /batch splits a large change into independent units, each in its own worktree.

When stuck — /rewind rolls code and conversation back to a checkpoint. /debug diagnoses runtime issues. /feedback reports a bug with session context attached.

Housekeeping — /model switches models (Fable 5.1 is the current default). /usage shows spend, including per-loop breakdowns. /permissions, /hooks, /agents, and /mcp manage their respective config.

Scheduling — /loop <interval> <prompt> reruns a prompt (“check the deploy every 5 minutes”). /schedule manages remote cron agents.

The ! prefix — type ! before a shell command to run it inline. The output lands in the conversation, which makes it the right way to hand over interactive auth flows:

! git log --oneline -20

Subagents: Spend Tokens on Context

Agent launches a separate Claude with its own context window. Two flavors:

  • Fork (no subagent_type): a copy of you — full context, shared prompt cache, cheap. Best when the agent needs everything you know.
  • Typed (Explore, Plan, custom agents in ~/.claude/agents/): clean context for specialized work like codebase discovery or architectural plans.

Brief them like a colleague who just walked in: goal in one sentence, what you already ruled out, what’s out of scope, the exact deliverable back. Terse prompts produce shallow work.

When to parallelize: independent reads across the codebase — yes. Dependent steps (“write the schema, then the migration”) — no, the second starts stale. If you can’t write prompts that don’t reference each other, it’s one sequential task, not three parallel ones.

Mixing Models: Opus Orchestrates, Others Work

A common setup: the expensive model plans and decides, cheaper models do the legwork. By default subagents inherit your main model, so this only happens if you ask for it.

First, a misreading to avoid: if /cost shows a few cents of Haiku you never requested, that’s Claude Code’s own housekeeping (session titles, summarizing web search results), not subagents doing work.

Other Claude models as workers. Pin a model in the agent’s frontmatter, in .claude/agents/ (project) or ~/.claude/agents/ (user):

---
name: explorer
description: Searches the codebase and reports conclusions. Use for broad discovery.
model: haiku
tools: Read, Grep, Glob
---
Find what was asked for. Return conclusions and file paths, not file dumps.

model takes haiku, sonnet, opus, fable, a full ID like claude-opus-5-5, or inherit. You can also just say it in the prompt (“spin up three Sonnet subagents for X, Y, Z”). For a blanket default, set CLAUDE_CODE_SUBAGENT_MODEL in settings; it skips the built-in Explore and Plan agents unless you also set CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1. A split that works: Opus plans and reviews, Sonnet implements, Haiku searches.

Non-Claude models as workers. Not native, but three routes work:

  1. Shell out. Most model CLIs have a headless mode (codex exec "...", gemini -p "..."). Opus runs it through Bash and reads the output. Wrap it in a skill so it’s repeatable.
  2. MCP. Register another model as a tool (claude mcp add codex -- codex mcp-server), and Opus calls it like any other tool.
  3. A router. Proxies like claude-code-router or LiteLLM sit behind ANTHROPIC_BASE_URL and send some requests to other providers. The most flexible and the most fragile: tool-calling quirks surface as odd failures.

Start with 1 or 2. Keep the orchestrator responsible for reviewing what comes back — a cheap worker’s output is a draft, not a decision.

Hooks: Making Behavior Stick

“Always run the linter before committing” lasts two messages as a prompt. As a hook, it lasts forever. Hooks live in ~/.claude/settings.json (user) or .claude/settings.json (project), and the harness runs them — they can’t be forgotten.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "prettier --write \"$CLAUDE_FILE\"" }]
      }
    ]
  }
}

Key events: UserPromptSubmit (inject context), PreToolUse / PostToolUse (block or annotate), SessionStart, Stop (notifications). Start with one hook. Add more as the friction tells you to.

Skills

Bundled skills worth knowing: /verify, /simplify, /dataviz, /design, /deep-research — and /skill-doctor, which shows which loaded skills go unused and what they cost in context. Prune aggressively. Custom skills are a SKILL.md in ~/.claude/skills/<name>/, invocable as /<name>.

For UI work, pair skills with a DESIGN.md spec so the output stops looking generic — see Designs That Don’t Look AI-Made.

A Sane Default Workflow

  1. /init once per repo.
  2. Plan mode for anything non-trivial.
  3. Research goes to subagents (on cheaper models); the main thread stays for decisions.
  4. /code-review before every PR, /security-review when it matters.
  5. Hooks for anything repeated; /skill-doctor when sessions feel bloated.
  6. /usage and /compact to stay cheap on long sessions.

Resources

Conclusion

Claude Code rewards investment, but less of it than it used to: /init, plan mode, one hook, and the dozen commands above cover ~90% of daily work. Add the rest as the friction tells you to.

All posts