This doc is a starting point for engineers picking up Claude Code and AI tooling for development for the first time. It collects recommendations and patterns that, in our experience, save time and improve outcomes. Not dogma — take what fits your work, ignore the rest.

Structure: from basics to advanced. Read top-down, or jump to a tier.

• Tier 1 — First hour. Bare minimum to start working sensibly.
• Tier 2 — First week. Skills, commands, plugins, basic workflow patterns.
• Tier 3 — Power user. Sub-agents, smoke tests, mobility.
• Tier 4 — Automation. Hooks, cron, remote install, fine-grained settings.

Tier 1 — First hour

Minimum to start working with Claude Code sensibly. If you have an hour before your first task, read only this tier.

TL;DR

1. Research → gather context (sub-agents, MCP, skills are options).
2. Plan → discuss the approach, lock in the steps (Opus in Plan Mode). Big tasks are worth planning up-front for parallel sub-agents.
3. Implementation → Sonnet executes the plan, Opus jumps in at hard moments. Independent chunks can go to parallel sub-agents — noticeably faster.
4. Tests → run after every meaningful task; green tests = "done".
5. Review → self-review + cross-model review on serious changes.

Between tasks, prefer /clear over /compact — over a long stretch this measurably impacts answer quality and token cost.

Core flow

1. Research and discussion

Before writing code, give the model the inputs: what we want to do, why, what the constraints are. Ask it to gather project and task context.

What helps at this step:

• Sub-agents — parallel search across the codebase.
• MCP servers — e.g. serena for semantic code navigation, context7 for up-to-date library docs.
• Skills and Commands — ready-made recipes for common tasks (see Tier 2).

Good rule: the more precisely you front-load the first prompt (intent, constraints, acceptance criteria, file paths), the less garbage piles up in the conversation later.

2. Plan composition

Commands:

• /model opusplan — Opus in Plan Mode, Sonnet for implementation (recommended default).
• Shift+Tab — toggle modes, including Plan Mode for the current message.
• /advisor — assign an "advisor" to the active model. For example, Sonnet does the work but pages Opus on hard calls.

Multi-agent planning. If the task is large or splits into independent parts, bake the parallel-sub-agent breakdown into the plan up front. The main agent holds the global plan and context; sub-agents research/design their slice in parallel. Big speedup on large features at the start.

When a plan usually isn't needed: small tweaks, renames, adding a log line, fixing a regex. Planning is overkill here.

When a plan usually pays off: multi-file refactors, new features, architectural changes, anything touching auth/payments/data. Your call — common sense beats rules.

3. Implementation

Once the plan is approved, the model starts executing. Key things:

• The model gives a short status between steps.
• If something breaks — stop, diagnose, don't keep going "per plan" on a broken base.
• Tests — separate task, parallel with the code, or right after. Strict TDD (test → code → refactor) is hard to hold and often unnecessary; write tests the way your team writes them.

Multi-agent implementation. If the plan steps are independent (different modules, different features, different layers), ask Claude to run sub-agents in parallel. Plain prose: "split this plan into independent chunks and dispatch parallel sub-agents on each". Claude wires up the right tool itself — you don't invoke anything manually. Each sub-agent works in an isolated context; the main agent aggregates the result. Solid time savings on large tasks. If the superpowers:dispatching-parallel-agents skill is installed, Claude picks it up on its own; or call it explicitly: /superpowers:dispatching-parallel-agents. For physical isolation of the work — pair with worktrees (Tier 2).

4. Tests

Ask the model to run tests after the task. Green = "done". Red = fix to green, not "I'll deal with it tomorrow".

You can automate this in the project CLAUDE.md: "after any changes in src/, run npm test".

5. Review

Two layers:

1. Self-review — ask the model to walk over its own diff for edge cases, security issues, weak decisions.
2. Cross-model review — a different model catches different blind spots. For example, the main flow on Sonnet → final review on Opus (/model opus). For critical code (auth, payments, data handling), stack both reviews.

Model strategy

Planning — Opus. Implementation — Sonnet. Opus is smarter at abstractions but slower and more expensive. Sonnet executes mechanical work fast and cheap.

Cheat sheet:

Effort levels:

• xhigh — Opus 4.7 on hard tasks (planning, architecture, debugging gnarly bugs).
• high — standard mode, balance of quality and speed.
• medium — routine, fast iteration, small fixes. Enough for most implementation work.
• "Answer directly, don't overthink" — when the model spirals into overthinking on a simple task.

Tip: keeping Opus on for the whole session usually doesn't pay off — Sonnet handles mechanical work just as well, faster and cheaper. Page Opus in selectively, on hard moments.

Limits: 5-hour windows and weekly quota

Claude Code runs on two overlapping limits — worth knowing up front, otherwise you can hit a ceiling mid-task without warning.

5-hour session windows

• A window starts on your first request and lasts exactly 5 hours.
• Within the window, message/token quota is consumed — per model (Opus burns it faster than Sonnet).
• When the window expires, its internal counter resets and a new window starts on the next request.
• Windows can overlap: while one is still active, another can start. The limit counts across all active windows.

In practice: heavy Opus work for 4-5 hours straight → sudden ceiling. On Sonnet the windows drain noticeably slower.

Weekly quota

• On top of session windows, there's an overall weekly limit.
• Counted as a rolling 7-day window — usage "drains" as old requests fall off the 7-day tail.
• If you hit the weekly cap, no model works until usage drains as old requests age out.
• Opus 4.7 burns the weekly quota multiple times faster than Sonnet — that's the main argument for /model opusplan over /model opus.

How to monitor — a status line under the input

You can configure a status line under the input field to always show remaining limits, the active model, and context. Convenient for monitoring without /cost every time.

Basic setup:

• /statusline — configures the built-in status line through an interactive flow.
• Custom — a script in settings.json under the statusLine key. Receives a JSON session-state on stdin, prints a line.

What people usually display:

• Remaining session window (% / time to reset).
• Remaining weekly quota.
• Active model and effort level.
• Current context (tokens in the conversation).
• Current project / directory / git branch.

Example ~/.claude/statusline.sh:

#!/bin/bash
read -r INPUT
MODEL=$(echo "$INPUT" | jq -r '.model.display_name')
DIR=$(echo "$INPUT" | jq -r '.workspace.current_dir | split("/") | last')
echo "[$MODEL] $DIR"

Wire it up in ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  }
}

For quotas there are ready-made community scripts (search claude-code statusline limits) — they pull remaining usage from the API or local state.

Bottom line: having a limits indicator in front of you is useful. Without it, it's easy to discover mid-day that your weekly quota is gone.

Context hygiene

• /clear between tasks, not /compact. The most underrated lever.
• /compact — only when the task isn't done yet but context is filling up.
• Reference files by path (src/auth.ts); don't paste contents.
• @file — only when you genuinely need the full file with its CLAUDE.md chain injected.

Project CLAUDE.md — foundation of project work

One of the most useful files in a project for AI flow. Without it, the model writes "industry-average" code, not your team's style. If model output drifts in style from the existing code, this is usually the cause: missing or thin CLAUDE.md.

CLAUDE.md hierarchy

Claude Code reads CLAUDE.md in a cascade:

• ~/.claude/CLAUDE.md — global rules (model strategy, general flow).
• <project-root>/CLAUDE.md — project rules (style, commands, architecture).
• <subdir>/CLAUDE.md — local rules for a subproject/module (monorepo, or front+back in one repo).

Deeper = higher priority. A submodule's local CLAUDE.md overrides the project one.

What to do at the start of a project

1. Let Claude study the project. The /init command does an initial overview and generates a baseline CLAUDE.md. Convenient on first connection to a repo.
2. Feed in style guides. If the team has docs on code style, naming conventions, error-handling patterns, architectural principles, ask the model to read them and integrate into CLAUDE.md.
3. Show example files. Point at 2-3 reference files ("this is how we write services", "this is how we write tests", "this is how we structure components"). The model copies the style from there.
4. Lock in the conventions. Tabs vs spaces, quotes, semicolons, naming (camelCase/snake_case), import order, line length, JSDoc/docstring format — anything that distinguishes your team's code from someone else's.

Without this the model guesses, and guesses worse than it gets right. Time spent on CLAUDE.md usually pays off within the first week.

What to put in CLAUDE.md

• Code style and lint rules (or a pointer to the linter config plus "follow it").
• Error-handling template (custom Error classes? Result type? throw?).
• Commands for tests, build, lint, dev server.
• Architectural invariants ("the service layer doesn't know about HTTP", "domain entities have no infra dependencies").
• Environment specifics (which env vars are needed, where to get secrets).
• Commit and branch conventions.
• Stack: Node/Python/etc versions, main libraries, what we explicitly don't use.
• Reference files with paths.

What NOT to put

• Change history (that's git).
• Secrets, keys, passwords.
• Things obvious from the code itself.
• Ephemeral state (current task, in-progress work) — that's what TodoWrite is for.

Basic CLI tricks

Minimum worth knowing about the CLI itself from day one.

Sessions: --resume, --continue, /rename

Claude Code stores session history. Each session = a separate conversation with its own context.

• claude --resume — opens the list of past sessions and lets you continue any of them. Useful when a task spans multiple days or you need to revisit an old conversation.
• claude --continue — picks up the most recent session immediately, no chooser.
• /rename <name> — rename the current session. Worth naming after a task code (PROJ-1234, auth-refactor, bug-login-redirect) — otherwise the list turns into a soup of default names that's hard to navigate.

Pattern:

1. Created a branch for a task → straight into Claude Code → /rename PROJ-1234.
2. Next day → claude --resume → find by task code instantly.

Screenshots into the input

Images don't need to be saved to a file with a path. Drop them in directly:

• Drag & drop — drag the file/screenshot into the terminal window.
• Ctrl+V (or Cmd+V on Mac) — paste a screenshot from the clipboard.

Works for UI bugs, design mocks, error screenshots, diagrams. The model sees the image and comments on it directly.

If Claude hangs

It happens: the model just goes silent, doesn't do anything, doesn't reply. Network error, runtime bug, stream hiccup — reasons vary.

What to do:

1. Escape — interrupts the current response.
2. Type "continue" / "go on" / "keep going".
3. If it hangs again — Escape again, ask to continue again.
4. Sometimes you need 2-3 cycles before it gets moving.

If it's truly stuck, /clear and rebuild the prompt. You lose context, but this is a rare scenario.

Tier 2 — First week

Skills, commands, plugins, MCP, useful patterns. This is where a Tier 1 reader unfolds into a full-fledged user.

Skills, Commands, MCP — three extension mechanisms

Before getting to plugins, it's worth understanding the three ways Claude Code extends.

Skills

Skills are reusable recipes for specific tasks. Effectively, instructions for Claude that it picks up at the right moment.

Three ways to use them:

1. Slash command — type /<skill-name> into the input, e.g. /dev:code-review. Direct invocation of a specific skill.
2. Plain prose — write "run a code review on this diff" / "do a security audit" / "refactor function X". Claude picks a matching skill from the installed set and applies it.
3. Automatically — some skills are tagged "always use when" and Claude wires them in itself in the right context, no explicit ask.

Useful categories:

• dev:* — code-review, debug-error, refactor-code, explain-code.
• test:* — write-tests, test-coverage, e2e-setup.
• security:* — security-audit, dependency-audit.
• docs:* — generate-api-documentation, create-architecture-documentation.
• setup:* — setup-linting, setup-formatting, migrate-to-typescript.

The full list of installed skills shows up in the system prompts at session start. If you want a specific one, check it's in the list first — the names aren't guessable.

Commands

Custom slash commands live in ~/.claude/commands/ (global) or .claude/commands/ (project-scoped). They're just markdown files with prompts for common tasks.

Built-in examples:

• /init — initializes CLAUDE.md for a project.
• /review — PR review.
• /security-review — security pass over the current diff.

MCP Servers

MCP (Model Context Protocol) is the standard for plugging external tools into the model. Servers give access to data and actions outside of code.

Baseline set:

• serena — semantic code navigation.
• context7 — library documentation.
• chrome-devtools / playwright — browser control for tests and scraping.

Management:

• /mcp — list connected servers and their status.
• Config — ~/.claude/mcp.json or .claude/mcp.json in the project.

Useful plugins

These tools are built on top of the skills/commands/MCP described above.

Caveman

Compresses model output by ~65% on mechanical prose. Good for long implementation sessions.

• Use for: status updates during implementation, commit messages (/caveman-commit), quick lookups.
• Don't use for: brainstorming, plan-writing, review, debugging — those need completeness, not brevity.
• Enable: /caveman. Levels: lite, full, ultra.
• Disable: stop caveman or normal mode.

Plannotator

Interactive UI for annotating plans and reviewing code. Commands:

• /plannotator-review — review of current changes or a PR.
• /plannotator-annotate — annotate a markdown plan.

Superpowers

A set of skills for a structured flow. If you want discipline in working with the model, worth a try:

• superpowers:brainstorming — structured requirements pass before code.
• superpowers:writing-plans — plan-writing format.
• superpowers:test-driven-development — TDD template.
• superpowers:verification-before-completion — verification before "done".

Serena

LSP backend for semantic code navigation. The authors claim measurable token savings on large projects (up to 70%) — real-world gain depends on the project and your workflow. Worth testing on your case and comparing.

Good fit for:

• Find a function/class → find_symbol (instead of reading the whole file).
• Find where it's called → find_referencing_symbols (instead of grep + read).
• Editing a specific method → insert_after_symbol / replace_symbol_body.
• Surveying an unfamiliar codebase → get_symbols_overview.

Not very useful for: configs, markdown, YAML, JSON — there are no symbols to navigate, regular tools are faster.

On a new project, Serena can run onboarding — its own procedure: walks the codebase, builds a semantic symbol index, drops architecture notes into .serena/memories/. Triggered with plain prose: "run Serena onboarding on this project" (Claude calls mcp__serena__onboarding itself). Costs tokens up front, but afterward Serena works noticeably faster and more accurately — pays back within a few sessions.

Context7

Library/framework/SDK documentation injected directly into the model's context. Solves a real problem: training data goes stale, and a guessed API breaks code.

Why use it:

• Structured response targeted at a specific question — no need to feed entire doc pages.
• Faster than WebSearch + WebFetch + parsing — one call instead of three.
• Covers most popular libraries (React, Next.js, Prisma, Tailwind, Django, etc.).
• Returns a correct, current answer in ~90% of cases.

Where it falls short:

• Fresh release/beta — the index can lag.
• A narrow niche library — may not be in the index.
• A specific edge case or bug — go to GitHub issues instead.
• Differences across major versions — specify the version in the query.

In practice:

• Default — Context7 for any library question. Cheap, fast, usually right.
• In doubt — ask the model to cross-check the source via WebFetch (official site, GitHub, changelog).
• Critical code — don't blindly trust any single source; verify with a minimal reproducer.

Bottom line: Context7 = a convenient fast layer. WebSearch/WebFetch = a backup layer when Context7 falls short or you need to cross-check.

/add-dir — multiple folders in one session

By default Claude Code only sees the directory it was launched from. If you need to work across several (frontend + backend, lib + consumer, monorepo without a shared root), add them via /add-dir:

/add-dir ../backend
/add-dir ../shared-lib

You can also pass at startup: claude --add-dir ../backend ../shared-lib.

Convenient pattern — a workspace folder with several repos:

~/projects/myapp/
├── frontend/        ← repo 1
├── backend/         ← repo 2
├── shared-lib/      ← repo 3
└── infra/           ← repo 4

Run claude from ~/projects/myapp/ (or from any subproject + /add-dir for the rest). Claude sees all repos at once — no need to switch sessions or rebuild context when a task touches frontend and backend together.

Useful scenarios:

• A feature that needs an API change in the backend + a call from the frontend — one session sees both sides.
• A cross-cutting refactor of a type in a shared library with updates to all consumers.
• E2E tests that need both UI and server context.

Codebase audits — recommended first exercise

A good way to ramp up on Claude Code on a real project is to run an audit on existing code. Low risk, high payoff, immediately produces concrete findings. If you're just starting out, try this.

What audits look for:

• Security — SQL injections, XSS, CSRF, secret leaks, unsafe eval, missing input validation. Skills: security:security-audit, security:dependency-audit, security-review.
• Dead code — unused functions/classes/files, unused imports, commented-out code. Skill: dev:remove-dead-code.
• Architecture violations — layer A knowing about layer B when it shouldn't, circular dependencies, fuzzy module boundaries. Skills: team:architecture-review, rust:audit-clean-arch (Rust), rust:audit-layer-boundaries.
• Tech debt — TODO/FIXME without an owner, antipatterns, duplication, magic numbers, long functions, low cohesion. Skill: dev:code-review.
• Tests — what's not covered, flakes, mocks that shouldn't be there, missing edge cases. Skill: test:test-coverage.
• Performance — N+1 queries, missing indexes, sync ops on the hot path, unnecessary re-renders. Skill: performance:performance-audit.
• Dependencies — outdated packages, known CVEs, duplicate libraries, unnecessary transitives. Skill: security:dependency-audit.
• Documentation — README diverging from reality, missing onboarding, dead links.

Practice for newcomers. Take a project (yours or a work one) and run 1-2 audits. For example:

1. claude → "Run a security audit on this project. Find real issues, not theoretical ones. Prioritize by severity."
2. Get a list of findings → triage each: real, or false positive?
3. Fix 1-2 real ones → open a PR.

Couple of hours and you have an understanding of the tool plus a project improvement. Good pattern for getting acquainted with Claude Code on real material.

Useful commands and skills:

• /security-review — security pass on the current diff.
• /review — general PR review.
• dev:code-review — comprehensive quality review.
• dev:directory-deep-dive — deep dive into a directory.
• team:architecture-review — architecture review.

⚠️ Audits produce a list of hypotheses, not diagnoses. Verify every finding by hand before fixing. Especially security — false positives are routine.

Worktrees — parallel branches without conflicts

Git worktree = several working copies of one repository, each on its own branch. Ideal for parallel Claude Code work across multiple tasks without flipping branches in the main copy.

Why

• Run two Claude sessions in parallel on different features.
• Avoid disturbing IDE state, dev server, or build cache when switching tasks.
• Isolate risky experiments from the main copy.

Where to put them

Recommendation: keep worktrees as sibling directories next to the main copy. Nesting a worktree inside the repo usually breaks IDE watchers, recursive tooling, and build contexts. Easier to keep them adjacent.

~/projects/foo/
├── bar.dev/                    ← main copy, branch main
└── bar.dev-worktrees/
    ├── feat-x/                 ← worktree, branch feat/x
    ├── PROJ-1234/              ← worktree, branch PROJ-1234
    └── hotfix-login/           ← worktree, branch hotfix/login

Path pattern: <repo>-worktrees/<branch> (replace slashes in the branch name with dashes).

Commands

git worktree add ../bar.dev-worktrees/feat-x feat/x       # create
git worktree list                                          # list all worktrees
git worktree remove ../bar.dev-worktrees/feat-x            # remove (after merge)

Flow with Claude Code

Main point: you don't have to type the commands by hand. Just tell Claude in the current session: "create a worktree for branch PROJ-1234 next to the project" — it runs git worktree add on the right path (sibling, not nested). After merge — "remove the worktree for PROJ-1234".

If you want to do it manually:

1. git worktree add ../<repo>-worktrees/<branch> <branch> → create a worktree.
2. cd ../<repo>-worktrees/<branch> → switch into it.
3. claude → start a session.
4. /rename <task-code> → name the session.
5. After merge → git worktree remove ../<repo>-worktrees/<branch> → clean up.

If the superpowers:using-git-worktrees skill is installed, Claude picks it up when you ask about worktrees, or call it explicitly: /superpowers:using-git-worktrees.

When worktrees aren't needed

• One person, one task at a time — overkill, a regular branch is enough.
• Small fixes in the same area of code — switching branches is faster.

Tier 3 — Power user

Parallelization, hands-on end-to-end testing through Claude, docs in the repo, mobile work.

Sub-agents

Sub-agents give parallelism and protect the main context from clutter.

How to launch. There's no direct command for sub-agents — you ask in plain prose: "run two Explore agents in parallel to find X and Y", "delegate the docs research to a sub-agent", "delegate implementation of module A to a sub-agent while you do module B". Claude wires up the right mechanism with the right agent type and prompt — from your side it looks like an ordinary request.

When to use:

• Parallel search/research across multiple directions.
• Long tasks with big output you don't want dragged into the main context.
• An independent line of work while you're doing something else.

Available types:

• Explore — fast read-only code search.
• general-purpose — open-ended questions and multi-step tasks.
• Plan — building architectural plans.
• claude-code-guide — questions about Claude Code itself and the Anthropic SDK.

What to give Claude so the delegation is good:

The sub-agent prompt is composed by Claude — you don't talk to the agent directly. But the sub-agent doesn't see your conversation history, so Claude needs to pack context into it. The more precise your original ask, the better the prompt it composes. Worth stating explicitly:

• Goal and why — the agent should understand what it's digging for.
• What's already known — so it doesn't redo work.
• Task type — "research only" or "write code too".
• Report format — e.g. "short report, under 200 words" (otherwise the sub-agent may produce a wall of text that floods your context).

You can say it just like that: "delegate to a sub-agent: goal X, we already know Y, research only, report under 200 words".

Background processes — dev servers, builds, watch mode

Claude can run commands in the background and continue working in parallel. Useful when you need a process to stay alive — dev server, watch build, docker-compose, tests in watch mode.

Why:

• Run npm run dev → Claude returns control immediately, doesn't wait for Ctrl+C. The app is running — go poke it in the browser.
• In parallel: while you click the UI, Claude keeps writing code per the plan. Dev server reloads on changes itself.
• Run a long build/test → Claude isn't blocked, does other things in the meantime → checks the result when the command finishes.

How to use:

• Just prose: "run npm run dev in the background", "bring up docker-compose in the background and continue the task".
• Claude can read stdout/stderr of the running process at any time — sees errors, progress, logs.
• Stop: "kill the background dev server" or Claude stops it itself when the task ends.

Typical scenarios:

• Manual smoke test. Claude brings backend + frontend up in the background → you click the new feature in the browser → Claude monitors logs in parallel and fixes bugs as it goes.
• TDD cycle. npm test --watch in the background → Claude edits the code → tests rerun on save → Claude reads the result.
• Long build/deploy. Kicked off → went off to write something else → came back to the result when ready.

Pitfalls:

• Background processes are tied to Claude's session — close the CLI and the processes die. For long-lived services, use tmux / systemd.
• If a process logs heavily, Claude burns tokens reading them. For noisy processes, redirect output to a file (>> dev.log) and read selectively.

Smoke testing through Claude

After implementation, it's worth letting Claude verify the whole thing works end-to-end, not just that unit tests are green. Especially for features with both UI and backend.

Baseline pattern:

1. Wire up the repos via /add-dir (or work in a workspace folder with frontend and backend together).
2. Bring up the stack: ask Claude to run docker-compose up, npm run dev, migrations, etc.
3. Give the task: "open the UI, click through the new feature, verify flow X works, watch the backend logs for errors".
4. Claude opens the browser via chrome-devtools / playwright MCP, clicks, reads the console and network requests, watches the server logs.
5. If it finds a bug — fixes it, restarts, checks again.

What Claude can actually do:

• Click buttons, fill forms, walk through pages.
• Take screenshots at each step → you see exactly what the model saw.
• Read console.error, network errors, stack traces.
• Monitor backend logs in parallel for errors / slow queries.
• Reproduce a bug step by step and fix it on the spot.

Especially useful when:

• A new feature spans frontend + backend — few unit tests, you need to see it in motion.
• A regression after a refactor — walk through main user flows.
• A bug that automated tests don't reproduce — Claude clicks around and hunts.

Pitfalls:

• Slow (minutes per scenario) and token-hungry.
• Doesn't replace proper E2E tests — this is an ad-hoc check.
• Sometimes the model sees a "fine" UI where the bug is obvious to a human. Screenshots help cross-check.

Docs and session summaries in the repo

Claude Code is good at generating but bad at remembering between sessions (context starts from zero on /clear or a fresh launch). The fix: leave traces in the repo.

Worth committing:

• Architecture decision records (ADRs) — docs/adr/0001-why-postgres.md. Why we picked X, what we considered, what we rejected.
• Big-task summaries — after a large feature, ask Claude to write docs/decisions/2026-05-feature-x.md: what's done, what's left, why this way. Then commit.
• Project guides — docs/onboarding.md, docs/runbook.md, docs/troubleshooting.md. Generate via Claude, edit by hand.
• Logs of debugging gnarly bugs — what we tried, what didn't work, what helped in the end.
• API descriptions via docs:doc-api, architecture diagrams via docs:create-architecture-documentation.

Why:

• A future Claude session reads these docs and grasps the project faster → fewer tokens on research, better decisions.
• A new team member — same.
• Six months later you don't remember why we did it that way — open the ADR, you do.

"Closing the task" pattern:

1. Implementation is ready, tests are green.
2. "Claude, write a short summary of what we did this session: problem, solution, key decisions, what's left." Drop in docs/sessions/<task-code>.md.
3. Commit alongside the feature. Can be automated via a Stop hook or git pre-commit.

Risk: if you generate this for every tiny change, docs/ turns into a dump. Only write summaries for substantive work; the rest belongs in commit messages and PR descriptions.

Bonus pattern: Claude as a secretary. A nice trick is to put task think-throughs into docs/tasks/<task-code>.md even before you start implementing. For example:

1. A task lands — sit with Claude and brainstorm: what to do, which approaches, risks, open questions. Answers go into docs/tasks/PROJ-1234.md.
2. A day or week later you come back — open the file, pick up where you left off. The session context is gone, but the thinking is on the page.
3. You can rethink, extend, change approach. The file lives as long as the task is active.
4. After implementation — either delete it, or convert to an ADR/summary.

Effect: Claude works as a secretary — packaging your thinking into a structured document that's pleasant to read later. Especially useful when you're juggling several tasks at once.

/remote-control — vibecoding on the move

Remote control of a local Claude Code session from a phone/tablet/any browser. The session runs on your work machine (with all project files, git, MCP, tools), and you send prompts from the phone.

Why:

• Morning at a café → kicked off a long task from the phone → got home, all done.
• Remembered a bug on the subway → opened the session → asked Claude to fix → PR is ready by the time you're at work.
• Lying on the couch — feature is wanted, getting up to the laptop is not. That's vibecoding on the move.
• Long build/test on a remote machine → ran the command → walked away → checked from the phone how it ended.

How to enable:

1. In a Claude Code session → /remote-control → follow the instructions (it generates a link/code for the paired device).
2. Open the link from the phone → the session is reachable through the browser.
3. Type prompts — they execute on your machine in the real project.

Pitfalls:

• The machine has to be on and online.
• If --dangerously-skip-permissions is on, you're driving full machine access from a phone. Think twice.
• Network lag happens. Not for real-time debugging.
• Config and paired-device tokens live in ~/.claude/ — exact filename depends on the CLI version, better to edit through /remote-control itself than by hand.

Tier 4 — Automation and fine-grained settings

Headless mode, hooks, notifications, channels, remote install, permissions. This part is about embedding Claude Code into your infra and automating the routine.

Headless / inline mode — cron, CI, scripts

Claude can be run with a single prompt without an interactive session. Convenient for automation.

Basic format:

claude -p "prompt as text"

Starts the model, executes the prompt, prints the result, exits.

Useful options:

• -p / --print — non-interactive mode, output to stdout.
• --output-format json — structured output for scripts.
• --dangerously-skip-permissions — without interactivity, prompts won't run, so you need this flag or a pre-configured allow-list.

Automation scenarios:

• Cron tasks on the machine: daily security audit, outdated-deps check, changelog generation.

  0 9 * * 1 cd ~/projects/foo && claude -p "Run /security-review on the last week of changes and create a report in audit.md" --dangerously-skip-permissions

• CI/CD: auto-generation of PR descriptions, auto-review of the diff, generating tests for new code.
• Watch mode: react to file changes via fswatch / entr + claude -p.
• Pre-commit / pre-push hooks: automatic review or commit-message generation.

Built-in scheduler:

• /schedule — create/manage Claude Code cron tasks through an interactive flow (or just ask Claude: "set up a weekly security-review cron").
• /loop — repeat a prompt at an interval, e.g. /loop 5m /security-review.

Caution:

• Headless with --dangerously-skip-permissions = full unsupervised machine access. deny rules in settings.json are mandatory (see permissions below).
• Log the output (>> claude.log) — otherwise you don't know what happened.
• Don't put prompts with secrets into shell history or cron config.

Hooks and notifications

Hooks = shell commands Claude Code runs in response to events. Configured in ~/.claude/settings.json (global) or <project>/.claude/settings.json (project-scoped). The foundation for automation on top of Claude Code.

Available events

• SessionStart — session start (load context, env vars).
• UserPromptSubmit — after the user submits a prompt (append extra context).
• PreToolUse / PostToolUse — before/after a tool call (validation, logging, auto-formatting after Edit).
• Stop — the model finished its response (notifications, sound).
• Notification — the model is asking for permission or input.

What people use them for

• Automatic prettier / eslint --fix after every Edit/Write.
• Logging commands to a file for audit.
• Blocking dangerous commands via PreToolUse.
• Notifications when the model finishes a long task.
• Loading project context at session start.

If you don't want to edit JSON by hand, ask Claude to set up the hook in prose ("set up a Stop hook that plays Glass.aiff"). Or call /update-config if the skill is installed — it walks through interactive settings.json setup.

Sound and system notifications

Long task → went for coffee → how do you know Claude is done? Via a Stop hook + system notification or sound.

macOS — sound:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff" }
        ]
      }
    ]
  }
}

macOS — system notification:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "osascript -e 'display notification \"Done\" with title \"Claude Code\" sound name \"Glass\"'" }
        ]
      }
    ]
  }
}

Linux — notify-send:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "notify-send 'Claude Code' 'Task done' && paplay /usr/share/sounds/freedesktop/stereo/complete.oga" }
        ]
      }
    ]
  }
}

Useful patterns:

• Different sounds for different events: Stop = success, Notification = "input needed".
• On Notification (model is awaiting permission) — louder sound, so you don't miss it.
• Network notification via webhook (Telegram, Slack, Discord) — you write a prompt from the phone via /remote-control, get pinged in the messenger when it's done.

Channels — external comms with Claude

Official Claude Code feature (research preview from v2.1.80+). Hooks external messengers/channels straight into the session — external events and prompts fly into Claude, replies come back through the same channel.

Officially supported channels:

• Telegram — via a bot.
• Discord — via a bot.
• iMessage — native integration on macOS.
• Fakechat — a local demo channel for developing your own.
• Custom — built via MCP.

Basic setup (exact command syntax may shift, the feature is in research preview):

1. Install the channel plugin from the official registry (telegram / discord / imessage).
2. Configure tokens/allowlist.
3. Run Claude Code with the channel attached.

For the current commands and flags, take the syntax from the docs below, not from memory.

Docs:

• https://code.claude.com/docs/en/channels.md
• https://code.claude.com/docs/en/channels-reference.md

Limitations:

• Research preview — API may still change.
• Requires Bun.
• Doesn't work on Bedrock / Vertex AI / Foundry.
• In Team/Enterprise — admin must enable it.

A solid option if you need a bridge to a messenger — no need to roll your own bot, it's all in the box.

Claude Code anywhere — VPS, servers, remote machines

Claude Code = a regular Node.js CLI. Installs on any Linux/macOS/Windows that has node. Not tied to your local machine.

Where you can install it:

• Company VPS / dev server — vibecode straight there, nothing pulled locally.
• Remote GPU machine for ML — Claude Code right where the data and models live.
• Raspberry Pi / home server — for automation scripts, scraping, backups.
• Container / dev-container / Codespaces — an isolated sandbox per project.
• Production server (carefully — read-only audit, not write) — diagnose prod issues without copying data to yourself.

How:

1. SSH into the machine.
2. Install Node + Claude Code (npm install -g @anthropic-ai/claude-code or follow the official guide).
3. Log in: claude → complete authorization.
4. Work as usual. Via tmux / screen, the session survives an SSH disconnect.

Why this is useful:

• Big repo that's awkward to clone locally — leave it on the server, connect, work.
• Team works in a shared environment (dev server) — no "works on my machine" issues.
• Heavy operations (builds, tests, migrations) don't tax the local machine.
• Pair with /remote-control — Claude lives on the server, you send prompts from a phone. Full mobility.

Pitfalls:

• Auth is per-account — each machine = a separate login.
• Limits are counted per account, not per machine.
• ~/.claude/ is per-machine — settings, skills, MCP don't sync automatically. Keep them in a dotfiles repo and symlink.

Permissions and --dangerously-skip-permissions

The flag disables all permission prompts for tool execution. Run as:

claude --dangerously-skip-permissions

⚠️ What it does. The model executes any bash commands, writes any files, calls any MCP without confirmation. The guardrail is fully off.

✅ Good fit:

• Isolated environments (Docker container, devcontainer, VM, sandbox) — even if something breaks, nothing valuable is lost.
• Long autonomous runs where constant prompts kill the flow.
• CI/scripts where interaction is impossible.

⚠️ Not recommended (your call):

• A work machine with access to prod keys, secrets, repositories — the model can accidentally run a destructive command or leak a secret to a log.
• A system with data that can't be restored.
• "Just because the prompts are annoying" — better to set up an allow-list via /permissions, same effect without losing protection on actually dangerous operations.

Alternative — allow-list. Run /permissions (interactive setup) or ask Claude: "add npm test, git status, ls to the allow-list". If the fewer-permission-prompts skill is installed, call /fewer-permission-prompts — it analyzes history itself and proposes additions. Fewer prompts, the dangerous-action guard stays on.

Important about deny in settings.json. Rules in the deny section apply even with --dangerously-skip-permissions. The skip disables interactive prompts but doesn't bypass explicit denies in the config. Good pattern:

{
  "permissions": {
    "deny": [
      "Bash(rm -rf*)",
      "Bash(git push --force*)",
      "Bash(*--no-verify*)",
      "Write(.env*)"
    ]
  }
}

So you can run --dangerously-skip-permissions for convenience and still keep critical operations blocked. A reasonable compromise on a work machine: fewer prompts on the routine, hard floor against destruction.

Team-mates

Ability to attach other AI agents as "teammates" via TeamCreate. Used for specialized roles (reviewer, tester, architect) that retain their own context across calls.

Recommended starting point: the standard flow without team-mates. Add them only when there's a clear, repeating role.

Tail

Checklist (optional)

Useful items to self-check before/during a task. Follow whole or pick & choose:

• The project has an up-to-date CLAUDE.md (style, commands, architecture).
• Context is loaded (project CLAUDE.md read, relevant files mentioned).
• Decided: plan or no plan.
• If planning — Plan Mode + Opus.
• After the plan — straight to execution; don't loop on discussion.
• After implementation — tests.
• After tests — self-review / cross-review when needed.
• Before the next task — /clear.

Things to watch for

Common rakes newcomers step on. Not rules — just observations:

1. Writing code immediately, no context — the model guesses, the result is usually weak.
2. One long conversation across ten tasks — context fills up, quality drops. /clear between tasks helps.
3. Opus on everything — slow and expensive, while Sonnet handles mechanics just as well.
4. Ignoring tests — "I'll check later" = "I'll never check".
5. Accepting the first answer as final — especially on hard tasks. Worth asking for alternatives, edge cases, what could go wrong.
6. Not using Serena/Context7 — on big projects this is noticeable token overpayment and work against stale docs.
7. Working without a project CLAUDE.md — the model writes "industry-average" instead of your team's style. Style, naming, patterns don't match the codebase.
8. Nesting worktrees inside the repo — usually breaks IDEs and tooling; easier to keep them adjacent.

Ways to work with Claude — beyond CLI

CLI is the primary surface, but there are others. Briefly, what exists:

• IDE extensions (VS Code, JetBrains, Cursor) — Claude Code right inside the IDE. Same CLI under the hood.
• Claude Code Web (claude.ai/code) — web interface, attaches to a local session or spins up cloud sandboxes.
• Claude for Chrome — browser extension with access to the current tab (UI tests, parsing, web consoles).
• Mobile App (iOS / Android) — light on-the-go work, paired with /remote-control or Channels to drive a live session.

One account, shared limits. Details and install — in the official docs.

Further reading

• Claude Code docs: https://docs.claude.com/claude-code
• List of installed skills: check the system prompts at session start.
• Config: ~/.claude/CLAUDE.md (global) and <project>/CLAUDE.md (project-scoped).