Build faster with
Claude Code

New here? Start on this page. In about 30 minutes you'll go from nothing to a real website live on the internet — a public link like your-project.vercel.app you can open on your phone and send to anyone. You don't need to know how to code: you tell Claude what you want in plain English, and it does the work. Each step below is the short version and links to the full chapter if you want detail.

Words you'll see (in plain English)

Step 1 — Get the Claude Code app (once)

One download and you're ready — no terminal, nothing to configure. The full walkthrough with fixes is in Part 1: Setup.

Step 2 — Open your project folder

Step 3 — Build your first page (one prompt)

Now the fun part. Not sure what to build? Pick a starter idea, then paste the prompt and answer Claude's questions in plain English.

I'm brand new to coding. Build me a simple one-page website.
Idea: [a personal landing page with my name, what I do, and a contact button]

Requirements:
- one clean, modern page that works well on phones
- no database, no complex setup
- after you build it, show me how to preview it in my browser

Explain each step in plain English, and wait for my OK before big changes.

✅ First win: Claude shows the change in the diff view; click Accept, then open the preview Claude gives you (it can run your page in the app's Browser pane). 🎉

Step 4 — Put it on the internet (one prompt)

Your page works on your computer. Now let's give it a public link. Claude does the GitHub + hosting steps for you — you just approve and log in when asked.

Help me put this project online so I have a public link I can share.

- Create a private GitHub repo and push this project. Show me what will be
  committed first, and never commit secrets or passwords.
- Deploy it to Vercel and give me the live URL.
- Explain what you're doing in plain English, and pause whenever I need to
  log in or click something.

At the end, give me the public link.

Step 5 — You did it 🎉

When Claude hands you a link like your-project.vercel.app, open it on your phone. That's your project, live on the internet.

Where to go next

Stuck? Your lifeline

If anything breaks — an error, a "command not found", a login loop — don't panic. Copy the red text and paste this to Claude:

I'm a beginner and I'm stuck. Here's exactly what I did and the error I see:
[paste what you did and the full error text]

Explain what went wrong in plain English and give me the simplest fix,
one step at a time.

The three fixes that solve most beginner problems:

1. Reject the change and ask Claude to try again, more simply.
2. Quit and reopen the Claude Code app.
3. Restart your computer, then sign in again.

New words show up fast in any building tool. Here is every term used in this guide, in plain English. You don't have to memorize any of it — skim it once now, then come back whenever something doesn't click. Each term is also explained again the first time it matters in a chapter.

1. The basics — your tools & workflow

2. Saving & shipping — Git and hosting

3. Files that steer Claude

4. How apps are built — web words

5. Security & privacy words

This is the hand-held path for non-technical people. Students should not read 300 lessons before they build. They should install, build something small, publish it, then learn Claude Code's advanced features only when those features solve a real problem.

The promise

10-day build path

Beginner to super advanced map

How the big topics fit

Prompt: simplify any advanced topic

Act as a course creator for non-technical people learning Claude Code.

Turn this topic into a friendly lesson:
[topic]

Make it:
- beginner-safe
- practical
- copy-paste friendly
- focused on building something real
- no more than 5 steps before the learner gets a visible result

Include:
1. Why this matters
2. What to click
3. What to paste
4. What success looks like
5. What to ignore until later

You only do this once. The easy way is the Claude Code app — download it, sign in, and you're ready. No terminal, no separate tools to install. Pick your computer below so the one OS-specific step (Windows needs Git) shows correctly.

The highlighted tab is the one you're following. Your choice is remembered on this device.

🌐 Browser = a normal web page (Chrome, Safari, or Edge) — used for the steps below. 🖥️ Terminal only shows up inside the Advanced block further down, if you choose the command-line path.

1. Download & install the app

What it is: the Claude Code desktop app — a normal application window with a Code tab where the AI builds inside your project folder. It includes everything it needs: you don't install Node.js or a command line separately.

https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code&utm_medium=docs

https://claude.ai/api/desktop/win32/x64/setup/latest/redirect?utm_source=claude_code&utm_medium=docs

2. Sign in

What it is: the login that lets Claude Code work. It needs a paid plan.

https://git-scm.com/downloads/win

git --version
node --version
claude --version
claude

SOP: where to click

Quick check — you're ready

First prompt after opening Claude Code

I am new to coding. Please inspect this project before changing anything.

Tell me:
1. What files and folders matter
2. How to run the project locally
3. What commands are safe to run
4. What you recommend as the first small step

Do not edit files until I approve the plan.

GitHub Account

• Create an account at github.com using a personal email
• Choose a professional username — this is your developer identity
• Always use "Sign in with GitHub" when creating accounts at Vercel, Supabase, Railway, etc. This links everything to one identity and removes password management.

Folder Structure (Required)

Never work from your Desktop (iCloud/OneDrive sync breaks code files). Use this structure for every project you ever create:

Documents/
  claude-projects/           ← one parent folder for all projects
    my-first-project/        ← one folder per project
      docs/
        MASTERPLAN.md        ← your project document (see Part 2)
    second-project/
      docs/
        MASTERPLAN.md

Naming rules — always use these for folder and file names:

• No spaces → use dashes: my-project not my project
• No accents or special characters: design-web not diseño-web
• All lowercase: my-app not My-App

Pro tip: Pin the claude-projects folder in Finder (Mac) or Quick Access (Windows) so you can always get there in one click.

Every project, without exception, needs these three documents before you write a single line of code with Claude.

Before You Start — the checklist

This is the whole setup at a glance. Tick each box, then follow 2.1–2.4 below for the how-to — each item maps to a section. The first two come from Part 1; the rest you'll do here.

2.1 MASTERPLAN.md — The Blueprint

This is the blueprint. The more detail you put in, the closer the finished build is to what's in your head — a vague blueprint gets you a vague house.

This is the most important file in your project. It's what Claude reads to understand what you're building. The more detail, the better the output.

How to create it: Open claude.ai and paste this prompt:

I want to create a PRD (Product Requirements Document) for a project I'm going to build in Claude Code. I'm not a developer, so act as an expert product manager and interview me to get this right. Ask me ONE question at a time, wait for my answer, then ask the next — don't ask everything at once, and don't write the document until you've covered everything. Work through: the problem I'm solving, who it's for, the main things a user must be able to do (and what can wait until later), what "done"/success looks like, and anything else you'd need to build it well. If an answer of mine is vague, ask a follow-up before moving on. When you have enough to write a clear, detailed plan, give me the complete document in Markdown (.md) format. My idea is: [describe your idea in as much detail as possible]

Claude will interview you one question at a time — it may ask quite a few, and that's the point. Answer each as fully as you can; the richer your answers, the better your app. When it's done asking, it writes the full MASTERPLAN for you.

Required sections in your MASTERPLAN:

# MASTERPLAN: [Project Name]

## What This Is
A platform for [X] that allows users to [Y].
The problem it solves is [Z].

## Ideal User
- Profile: [who they are]
- Main pain point: [what frustrates them today]

## MVP Features
1. Landing page
2. User registration / login
3. User dashboard
4. Payment with Stripe
5. [add your specifics...]

## User Flow
1. User lands on homepage
2. Signs up with email
3. Accesses their dashboard
4. [continue the journey...]

## Visual References
- I like the design of [url]
- I like the checkout flow of [url]
- [attach screenshots of anything you like]

The longer and more detailed this file, the better your results. Do not skip it.

2.2 CLAUDE.md — Claude's Project Memory

These are the house rules Claude reads before every shift, so it builds your way. Each time you correct a mistake, write it here — so the same mistake never happens twice.

CLAUDE.md is a special file Claude reads at the start of every conversation. It tells Claude the rules, conventions, and context of your project. Without it, Claude works blind.

Step 1: Generate it automatically

Open your project in the Code tab of the Claude Code app (or a terminal, if you're on the Advanced path), then run:

/init

Claude will scan your project and auto-generate a CLAUDE.md with conventions it detects.

Step 2: Enrich it with best practices

After /init runs, give Claude this prompt:

Read https://code.claude.com/docs/en/best-practices and improve the CLAUDE.md we just created following all of Anthropic's official recommendations. Make sure to include code conventions, build/test commands, and workflow rules that apply to our project.

What belongs in CLAUDE.md:

Example CLAUDE.md:

# Project: [Name]

## Tech Stack
- Framework: Next.js 15 with App Router
- Database: PostgreSQL via Supabase
- ORM: Prisma
- Styles: Tailwind CSS
- Language: TypeScript

## Commands
- `npm run dev` — local development
- `npm run build` — production build
- `npx prisma db push` — sync schema to DB

## Folder Structure
- /app — Routes and pages
- /components — Reusable components
- /lib — Utilities and configs
- /prisma — Database schema
- /docs — Project documentation

## Conventions
- Strict TypeScript throughout
- Functional components with hooks
- Server Components by default; `use client` only when required
- API routes in /app/api
- File names in kebab-case
- Component names in PascalCase

## Rules
- Do not introduce new libraries without asking me first
- Never hardcode API keys or secrets in code
- Always read MASTERPLAN.md before starting a new feature

Rule: Every time Claude makes a mistake and you correct it, add that correction to CLAUDE.md so it never happens again.

Where your memory lives — and how to add to it:

Edit any of these without leaving Claude — run /memory to open your memory files:

/memory

Keep CLAUDE.md short by importing other files into it: write an @ path and Claude pulls that file in too.

See @docs/conventions.md for our style rules and @docs/git-workflow.md for branch naming.

2.3 PROJECT_STATE.md — Memory Between Sessions

This is the site logbook. Claude forgets overnight; the logbook is how the next session knows what's finished and what's next — no "where were we?" every morning.

Claude forgets everything when you close a conversation. For projects that last more than a few hours, use a PROJECT_STATE.md file maintained by a subagent (see Part 6). This lets Claude pick up exactly where it left off in every new session.

Once you've created the project-documenter subagent (Part 6), add this to the bottom of your CLAUDE.md:

## Session Rules
- At the start of every session, read PROJECT_STATE.md before doing anything
- Before and after any large task (>3 files or a new feature), invoke the project-documenter subagent

2.4 First Prompt Template

Once your MASTERPLAN.md is in the docs/ folder and CLAUDE.md is in the root, start your first Claude Code session with:

Read docs/MASTERPLAN.md to understand this project.

To start:
1. Create a CLAUDE.md in the root following the best practices at https://code.claude.com/docs/en/best-practices
2. Build the base project structure so we can go section by section
3. Create a basic landing page based on the MASTERPLAN
4. Run `npm run dev` so I can see it in the browser

Do not install unnecessary libraries. Ask me before introducing anything not in the MASTERPLAN.

What Claude will do:

1. Read your MASTERPLAN
2. Read Anthropic's official best practices
3. Create a complete CLAUDE.md
4. Set up the file structure
5. Install dependencies
6. Build a landing page
7. Start the dev server so you can see it at http://localhost:3000

Success criterion: You can see your project in a browser.

2.5 Standard Rules — Paste Before Every Project

Think of this as your standing contract with Claude — the house rules every new "contractor" agrees to before touching the site. Paste it at the start of any project. Even better (see 2.2): drop it into your personal ~/.claude/CLAUDE.md once, and every project follows these automatically — paste once, never again.

STANDARD RULES — follow these for our entire work on this project.

Before you start
1. Read docs/MASTERPLAN.md, CLAUDE.md, and PROJECT_STATE.md (if it exists)
   before doing anything. Inspect the project before you change it.
2. For anything bigger than a small edit, show me a short plan and wait for my
   OK before you build.

How to work
3. Work in small steps. After each change, tell me in plain language what you
   did — assume I'm not technical.
4. Don't ask permission for small, safe, reversible steps — just do them and
   keep moving. STOP and explain first ONLY for big or hard-to-undo actions:
   deleting files or data, installing a new tool or paid service, changing the
   database, pushing to GitHub, deploying, or anything touching secrets, money,
   or live users.
5. If a choice is unclear or could break something, ask me instead of guessing.

Safety
6. Never put API keys, passwords, or secrets in the code. Use a .env file, keep
   it in .gitignore, and never commit secrets.
7. Don't add any new library, tool, or paid service without asking me first.

Branches & shipping
8. Work on a branch (or "staging"), never directly on main. If this project
   isn't set up that way yet, set it up first: create a staging branch, make
   main the auto-deployed production branch, and add the "all work on staging,
   never main" rule to CLAUDE.md. Test locally — and on a preview/staging URL
   if we have one — before merging to main or deploying. Never push to
   production without my OK.
9. With Git: small commits, clear messages, stage specific files (never a blind
   "git add ."), and ask before pushing.

Keep it handoff-ready
10. Keep CLAUDE.md updated when I correct you. Keep PROJECT_STATE.md and a
    HANDOFF.md current (what's done, what's next, how to run/test/continue) and
    commit them to Git — so you, I, or another AI can pick up later.

Before going live
11. Before any deploy: check for exposed secrets and security problems, and make
    sure the build (and tests, if any) pass. If anything fails, don't deploy —
    tell me.

Use this when you are taking a first Claude Code project from your computer to the cloud. The goal is simple: a private GitHub repo, clean handoff docs, Vercel hosting, optional Stripe payments, and a design system Claude can keep consistent.

The launch stack

GitHub Checklist

Prompt: Connect Existing Project to GitHub

I created a private GitHub repository for this project.
Repository URL: [PASTE GITHUB REPO URL HERE]

Please prepare this local project for GitHub and another LLM/agent handoff.

Before pushing:
1. Inspect git status, current branch, changed files, untracked files, and whether a remote already exists.
2. Check for secrets or files that should not be committed: .env, API keys, credentials, node_modules, build outputs, cache folders, and large generated files.
3. Make sure README.md explains what the project does, how to run it locally, and how to test/build it.
4. Make sure CLAUDE.md explains project rules, commands, and the definition of done.
5. Create or update docs/HANDOFF.md with current state, next steps, and what another agent should know.
6. Show me the exact files you plan to commit and wait for my approval before pushing.

After I approve, commit with a clear message, push to GitHub, and give me the repo URL, branch name, commit hash, and next-agent notes.

Commands Claude May Use After Approval

git status
git remote -v
git add README.md CLAUDE.md docs .gitignore src package.json
git commit -m "Prepare first project handoff"
git remote add origin [GITHUB_REPO_URL]
git branch -M main
git push -u origin main
git rev-parse --short HEAD

Rule: do not run git add . blindly on a first project. Ask Claude to show what will be staged first.

Vercel Prompt

Help me deploy this project to Vercel from GitHub.

First verify the repo is pushed and the project has README.md, CLAUDE.md, .gitignore, and documented environment variables.

Then tell me the exact Vercel settings:
- framework preset
- install command
- build command
- output directory
- environment variables for Preview
- environment variables for Production

Explain the difference between Preview and Production in plain English. Do not paste secret values into code.

Stripe Prompt

I want to add Stripe payments to this project safely.

Use Stripe Checkout Sessions unless there is a strong reason not to.
Explain test mode vs live mode.
List the environment variables I need for Preview and Production without secret values.
Create the minimum checkout flow and webhook plan.
Add a launch checklist: privacy policy, terms, cookie banner, test card, webhook test, and Vercel production keys.
Do not use live keys during development.

Design Libraries to Ask For

First Project Audit Prompt

Audit this first project before I share it or deploy it.

Check:
- GitHub readiness
- Vercel deployment readiness
- environment variables and secrets
- mobile, tablet, desktop UX
- SEO basics: title, URL, description, share image
- security basics: exposed routes, auth, API keys
- payments readiness if Stripe is used
- legal basics: privacy, terms, cookie banner

Give me critical, normal, and low-priority issues. Fix only after I approve the plan.

3.1 The Two-Branch Rule

Never work directly on main. Always use two branches:

• main — production code only. What Vercel deploys.
• staging — where all development happens.

When something is tested and ready: merge staging → main. Vercel auto-deploys.

Ask Claude to set this up:

Set up a two-branch workflow for this project: main (production) and staging (development). Create the staging branch, configure Vercel to deploy main automatically, and add a rule to CLAUDE.md that all development happens on staging — never on main.

3.2 How to Write Good Prompts

Writing a prompt is like briefing a contractor: "make it nice" gets you a guess; a clear brief — what, where, the exact look, and what NOT to touch — gets you what you pictured. That's all the structure below does.

The quality of your output is almost entirely determined by the quality of your input. Use these patterns.

Use Screenshot First

Before describing what you want in words, show Claude an image. Claude understands visuals perfectly.

• Screenshot → paste into Claude → "build something like this"
• Works for layout, colors, UI patterns, checkout flows, dashboards
• Mac shortcut: Cmd + Ctrl + Shift + 4 to copy a screenshot to clipboard
• Windows shortcut: Windows + Shift + S

Then Cmd/Ctrl + V to paste directly into Claude.

Good prompt structure:

Context: [What part of the project this is about]
Goal: [What you want to achieve]
Constraints: [What Claude should NOT do]
Success: [How you'll know it worked]

Examples:

Use @filename references to point Claude at specific files:

Look at @components/header.tsx and @app/globals.css — the header nav links 
are not using the correct font weight. Fix them to match the h2 style.

Drag and drop files directly into the Claude Code chat window instead of describing them.

3.3 When to Start a New Conversation

Claude's performance degrades as a conversation gets very long — the context window fills up. (The next section, Staying in Control, shows how to watch and manage it.) Start fresh when:

• You're switching to a completely different part of the project
• Claude starts making mistakes it wasn't making before
• You've been in the same conversation for more than 2–3 hours

Before starting a new session, run:

Invoke the project-documenter subagent to update PROJECT_STATE.md with everything we did today.

Then start the new session with:

Read CLAUDE.md and PROJECT_STATE.md before we begin.

3.4 Keyboard Shortcuts

3.5 Voice Input with SuperWhisper

Speaking is ~3× faster than typing. SuperWhisper transcribes your voice to text with AI accuracy and pastes it into any app — including Claude.

• Download: superwhisper.com
• Press a hotkey → speak your prompt → it appears as text → paste into Claude
• Especially powerful for long, detailed prompts describing complex features

3.6 Continue from Your Phone: /remote-control

This is one of Claude Code's most underused features. It links your VS Code session to the Claude mobile app, so you can continue working on the same project — with the same context, plugins, and skills — from your phone.

When it's useful:

• You're away from your computer and think of a change
• You want to leave a long task running (refactor, Ralph Loop) without waiting at your desk
• You want to check the status of something Claude is processing

How to activate:

In your Claude Code session in VS Code:

/remote-control

Claude generates a code or QR. Scan or enter it in the Claude iOS/Android app. Your full session is now accessible from your phone.

Building is only half the skill. The other half is staying in control of the session — knowing how full Claude's memory is, trimming it, undoing a wrong turn, and making Claude plan before it touches your code. These are the dashboard and the brakes. They're a handful of short commands, and they're what separate a smooth session from one that slows to a crawl or quietly runs up your bill.

1. Your fuel gauge — /context

The context window is Claude's short-term memory for this one session — everything it's currently "holding in its head." It's measured in tokens (roughly one token per word). Your messages, every file Claude reads, every command result, and your CLAUDE.md all take up space in it.

Type /context to see the breakdown — what's filling the window right now.

/context

Why it matters: as the window fills up, Claude gets slower and starts to drift — forgetting things you said earlier or repeating itself. People call this "context rot." Checking /context tells you when it's time to trim.

2. Trim without starting over — /compact

When the window is getting full but you're mid-task, /compact summarizes the conversation so far into a tight recap and frees up space — without losing the thread.

/compact

Even better, you can tell it what to keep by adding instructions after the command:

/compact keep the database schema and the auth decisions we just made

3. Wipe the slate — /clear

When you switch to a completely unrelated task, don't drag the old conversation along. /clear empties the chat and starts fresh.

/clear

Don't worry — clearing is cheap. Claude re-reads your project files and your CLAUDE.md as it works, so it doesn't forget your project — only the back-and-forth of this one chat. For the "should I keep going or start fresh?" judgment call, see Part 3 → When to Start a New Conversation.

4. Undo a wrong turn — /rewind

Claude went down the wrong path and edited five files? You don't have to undo them by hand. Claude saves a checkpoint every time you send a prompt, and /rewind (or tapping Esc twice) opens a menu to roll your code and the conversation back to an earlier point.

/rewind

5. Pick up where you left off — /resume

Closed your laptop yesterday in the middle of something? /resume reopens a previous session with its history intact, so you continue instead of re-explaining.

/resume

A simple rhythm: /clear when you switch tasks, /resume when you come back to one.

6. Plan before Claude touches anything — Plan Mode

This is the single highest-leverage habit in this whole guide: make Claude plan first, act second. In Plan Mode, Claude reads your code, researches, asks clarifying questions, and proposes a step-by-step plan — but it makes no edits until you approve. You catch a wrong approach before a single line is written.

You switch modes by tapping Shift+Tab to cycle through them:

Get in the habit of starting big requests in Plan Mode, reading the plan, and tweaking it before you say go. A minute of planning saves ten minutes of fixing.

7. Show Claude what you mean — files & images

You don't have to describe everything in words. Two moves make Claude far more accurate:

Point at a specific file with @. Type @ and start the filename — Claude reads exactly that file instead of guessing. Perfect for handing it your brand colors, a logo, or one component.

Use the colors and fonts in @brand-guidelines.md for the landing page header.

Paste a screenshot. Claude can see images. Paste a picture of an error message, a layout that looks broken, or a website you want yours to resemble — then ask for the fix. Showing beats describing.

[paste a screenshot] This is what I see when I click "Save." Find the bug and fix it.

Bonus: a live status bar — /statusline

Want your fuel gauge always visible? /statusline sets up a small bar at the bottom of Claude Code that can show your current model, context %, cost, and Git branch — so you don't have to keep running /context.

/statusline

The takeaway: check your fuel (/context), trim it (/compact, /clear), undo safely (/rewind), come back later (/resume), plan before you build, and show Claude with files and screenshots. For the full playbook on spending fewer tokens — and the trade-offs — see the next section, Saving Tokens.

Tokens are the fuel Claude runs on — every word it reads and writes. You never have to count them, but a few habits make each session go much further (and cost less). The single biggest idea is the box below; everything after it is just acting on it. The built-in commands are the safe core — most you already met in Staying in Control.

One mindset before the how-to: the goal isn't the fewest tokens — it's the most work per token. Sometimes the cheapest move is to spend a little more up front (plan first, give the right context) so you don't pay to redo a wrong build. Spend on clarity; save on clutter.

Part A — The easy wins (do these first)

All built-in, all official. Each links to where it's taught in full.

Part B — Level-up moves (when the easy wins aren't enough)

Keep CLAUDE.md lean — the details

CLAUDE.md is loaded in full at the start of every session — it is never trimmed. So your standing-orders sheet gets re-read top to bottom before every message. Anthropic's docs warn it backfires twice: "longer files consume more context and reduce adherence." In plain terms: a bloated rules file costs more tokens and gets followed less carefully. Lean isn't tidiness — it's cheaper and more obedient.

• Target under ~200 lines. That's Anthropic's stated ceiling.
• Keep only the every-session essentials: build/test/run commands, code conventions, project layout, and "always do X / never do Y" rules.
• Be specific, not vague — specific rules get followed more reliably: ✅ "Run npm test before committing" (not ❌ "test your changes"); ✅ "API handlers live in src/api/handlers/" (not ❌ "keep files organized").
• Group with headers and bullets, and kill contradictions — if two rules clash, Claude picks one at random.
• Move the heavy stuff out — to where it loads on demand: a multi-step procedure, or something that only matters in one corner of the project, belongs in a Skill or a sub-folder CLAUDE.md (those load only when relevant).

Copy-paste prompt — tune your CLAUDE.md to Anthropic best practice. Safe to run anytime; step 7 makes Claude propose changes and wait before saving:

Audit and improve my CLAUDE.md using Anthropic's own best practices.

1. Read my current CLAUDE.md (plus any CLAUDE.local.md and @-imported files).
2. Remember: CLAUDE.md loads IN FULL at the start of every session, so every
   line costs tokens on every message — and Anthropic notes longer files also
   get followed LESS reliably. Target: under ~200 lines.
3. Keep ONLY what Claude needs every session: build/test/run commands, code
   conventions, project layout, and "always do X / never do Y" rules.
4. Rewrite vague rules as specific, testable ones. For example:
   - "Use 2-space indentation"               (not "format code properly")
   - "Run npm test before committing"         (not "test your changes")
   - "API handlers live in src/api/handlers/" (not "keep files organized")
5. Group with markdown headers + bullets. Remove anything that contradicts
   another rule.
6. For anything that's a multi-step procedure, or only matters in one part of
   the project, DON'T leave it inline — move it to a Skill or a sub-folder
   CLAUDE.md so it loads only when relevant. (Note: @-imports tidy the file but
   do NOT save tokens, since imported files still load at launch.)
7. Show me a before/after line count and a plain-English list of what you
   trimmed, rewrote, or moved out — and wait for my OK before saving anything.

Part C — Trade-offs & when to use (the honest part)

About those third-party tools: the community has built token-savers like CodeGraph, RTK, caveman, and ponytail. They can cut usage sharply, but they add moving parts, can drop information (lossy), can fall out of sync with your code, and run code on your machine. Treat them as an advanced, optional layer — install only from sources you trust, and only once the built-in habits above aren't enough. [Unverified — these are community projects, not official Anthropic tools.]

You already have most of the tools. This chapter just points them at one goal — fewer tokens, better work. The commands live in Staying in Control, model choice in Choosing Your Model, lean memory in Part 2, skills in Part 4, and the crew in Part 6. For Anthropic's own list, see code.claude.com/docs/en/costs ("Reduce token usage").

4.1 Plugins: Superpowers for Claude

A plugin is a shareable bundle of add-ons — most often one or more Skills (the know-how), and sometimes commands, subagents, or MCP setups. Installing one gives Claude pre-loaded expertise for a specific kind of work; it doesn't change the underlying model. (Skills on their own are covered in 4.3.)

How to install the official Anthropic plugin marketplace:

In Claude Code (inside VS Code), type:

/plugin

In the modal that appears, go to the Marketplaces tab and paste:

https://github.com/anthropics/claude-plugins-official

Click Add. You only do this once per machine.

Then go to the Plugins tab to see and activate individual plugins.

When Claude asks scope:

• "Install for you" — active in ALL your projects on this machine (recommended for the plugins below)
• "Install for this project" — active only in this repo

After installing, restart Claude Code (or restart VS Code) for plugins to load.

4.2 The 8 Essential Plugins

Install all of these for every project:

Start with security-guidance and frontend-design. Add the rest as you need them.

4.3 Skills: Reusable Knowledge

A Skill is a playbook Claude pulls off the shelf the instant your topic comes up — write it once, and you never re-explain that thing again. The 3-Times Rule tells you when to make one: if you've explained the same thing to Claude three times — a convention, a brand rule, a way you like things done — that's a Skill. Package it once; never explain it again.

Under the hood, a Skill is a folder inside .claude/skills/ with a SKILL.md file. Claude loads it automatically when it applies to what you're working on — so you don't repeat the same context in every prompt.

Let Claude propose your Skills:

Analyze the MASTERPLAN and the code in this project and propose 3–5 Skills that would be useful for me. For each one, tell me:
- Name and short description
- What project knowledge gets repeated and needs to be packaged
- When Claude should activate it

Wait for my confirmation before creating any files. Once I confirm, create them in .claude/skills/ following the best practices at https://code.claude.com/docs/en/skills.

Claude will read your MASTERPLAN, scan the code, and propose concrete Skills for your specific project.

Where to find skills & plugins:

• Anthropic's official marketplace (from 4.1) — trusted and auto-updating.
• The community library aitmpl.com — 1,000+ Skills, Hooks, Agents, and Plugins by category. Search before building from scratch.
• Our Resources page (/resources, "Tools We Love").

Plus the 4.2 essentials (frontend-design, feature-dev, code-review); add for your stack as needed (a language server; integrations like GitHub/Vercel/Supabase).

4.4 Starter Skill: deploy-checklist

Activates before every production push. Prevents you from shipping broken code or leaked secrets.

Copy this prompt exactly to Claude:

Create this Skill in my project at .claude/skills/deploy-checklist/SKILL.md. Use this template as a base but ADAPT each step to the actual tools in my project (my framework, database, and hosting). Don't add steps that don't apply.

---
name: deploy-checklist
description: Mandatory checklist before pushing to production. Invoke whenever about to push to the main branch.
---

# Pre-Deploy Checklist

Before pushing to main, verify in this order:

1. The app build passes with no errors or warnings (use this project's build command).
2. No debug logs remain in production-bound code (console.log, print, etc.).
3. No hardcoded credentials in the code. Search for strings like `sk_`, `whsec_`, `pk_live`, `postgres://`, suspicious long tokens.
4. Any new environment variable in the local env file is also set in the hosting platform (Vercel, Railway, etc.).
5. If the database schema changed, the migration has been applied to the production DB.
6. The main user flow has been tested locally — the full path a real user would take.

If any check fails, DO NOT push — fix it first and report.

4.5 Starter Skill: stack-context

Tells Claude exactly what tech is in use so it never suggests libraries or patterns that don't fit your project.

Create this Skill in my project at .claude/skills/stack-context/SKILL.md. Adapt the stack to what's already in my project, but keep this structure:

---
name: stack-context
description: Project tech stack. Load before proposing new libraries, services, or patterns to avoid introducing foreign technology.
---

# Project Stack

- Framework: Next.js (App Router, Server Components by default)
- DB: PostgreSQL on Supabase, ORM: Prisma
- Auth: magic links (do NOT use Auth0, Clerk, or similar)
- Payments: Stripe Checkout, webhook at `/api/webhook`
- Transactional email: Resend
- Hosting: Vercel
- Styles: Tailwind CSS

# Rules

- Do NOT propose new libraries without asking the user first
- Server Components by default; use `use client` only when needed (events, hooks)
- Environment variables always read from `process.env` with documented fallbacks

4.6 Your Own Slash Commands

A slash command is a keyboard shortcut for a whole paragraph — a prompt you keep typing, saved under a short name you fire any time (/ship-check).

If you keep typing the same prompt, save it as a command. Drop a Markdown file into .claude/commands/ and its filename becomes the command — ship-check.md turns into /ship-check, and the file's contents are the prompt Claude runs.

Create .claude/commands/ship-check.md:

---
description: Pre-ship review of the current changes
---
Review the current git diff for bugs, missing error handling, and anything
I forgot. List findings as 🔴 blocker / 🟡 warning / 🟢 nice-to-have, each
with the file and line.

Now typing /ship-check runs that whole prompt. Pass in extra text with $ARGUMENTS:

Explain in plain language, to a non-coder, what the file $ARGUMENTS does.

…then /explain src/auth.ts drops src/auth.ts into $ARGUMENTS. Keep commands in .claude/commands/ to share them with your team (committed to Git), or in ~/.claude/commands/ to keep them personal across every project.

4.7 Keep Your Skills Lean (and Current)

Treat your skills like a toolbox. A few sharp tools you actually reach for beats a drawer crammed with stuff you never use — and Claude has to glance over every installed skill before each job, so clutter quietly slows it down and costs tokens.

Review every few weeks:

• Run /context to see what's loaded.
• /plugin → Installed shows a "Not used recently" group — press d to disable a skill without uninstalling it.
• Fold repeated corrections into CLAUDE.md instead of leaving one-off skills lying around.

Keeping current:

• Plugins: the official marketplace auto-updates by default. To do it by hand, run /plugin marketplace update <name> then /reload-plugins (toggle auto-update in /plugin → Marketplaces).
• A skill you wrote: edit .claude/skills/<name>/SKILL.md, then /reload-plugins.

Facts docs-verified. [Unverified]: the exact per-skill token cost, a precise "too many" threshold, and wrong-skill activation from overlapping descriptions.

5.1 What Hooks Are

Hooks are rules Claude executes automatically, every single time — no prompting required.

Hooks fire at lifecycle events: before/after a tool call, before pushing code, after Claude responds, etc. They are deterministic, not AI-driven.

To see your active hooks:

/hooks

5.2 Starter Hook: Pre-Push Review

Claude shows you a summary of every change before it goes to main, and asks for confirmation. You can never accidentally push to production.

Ask Claude to set it up:

I want a hook that activates every time you're about to push to the main branch. Before executing the push, show me in plain language which files changed and a summary of what each change does, then ask me to confirm with "yes" or "no" before continuing. If I say no, cancel the push. The goal is that nothing ever goes to production without me reviewing it first.

5.3 Starter Hook: Sound Notification

Claude plays a system sound when it finishes responding — so you know it's ready even if you've switched to another window.

I want a hook that plays a system sound every time you finish processing my message and are about to respond. Make it a short, pleasant sound. The idea is that if I switch tabs while waiting, I know immediately when you're done. Configure it for my operating system and leave it on by default for this project.

Claude detects your OS (macOS, Windows, Linux) and sets the appropriate sound automatically.

5.4 More Hook Ideas

Once you have the first two, you can add more by asking Claude in plain language. Most fall into three buckets:

Safety

• Block dangerous commands — Claude can't run rm -rf or git push --force without explicit permission.
• Scan for secrets before any commit — block the commit if an API key or password is found.
• Stay off main — block file edits while you're on the main branch.
• Warn before touching .env files — those hold your API keys.
• Ask before installing — pause on any new package or dependency.

Quality

• Build or lint must pass before a push — cancel the push if it fails.
• Run tests after code changes — catch breakage early. (💸 only if you have tests — it adds time and tokens each run.)
• Auto-format on save — code stays clean without you asking.

Convenience

• Desktop popup when Claude needs your input — not just when it's finished.
• System notification when a long task finishes — visible even when Claude isn't the active window.
• Keep an audit log — append every command Claude runs to a log file.

6.1 What Subagents Are

Subagents are separate Claude instances that run with their own context and their own tool set. You delegate a specific task to them — they investigate, do the work, and hand you back a summary — without polluting your main conversation with hundreds of lines of file content.

Use subagents when:

• A task requires reading many files across the codebase
• You want a specialist perspective (security auditor, documenter, etc.)
• You don't want the exploration work to eat your conversation context

Subagent files live in .claude/agents/.

How to Create a Subagent — in VS Code

Three ways, easiest first (the Claude Code prompt box is identical in VS Code or a terminal):

1. The guided way — /agents (recommended). Type /agents in the Claude Code prompt box and create a new agent through guided questions — or just describe what you want and let Claude write it. Edit or remove agents the same way later.
2. Ask Claude in plain language. e.g. "Create a subagent at .claude/agents/architect.md that plans features but never writes code — give it read-only tools."
3. Make the file yourself in VS Code's editor — a .md file in .claude/agents/ (this project) or ~/.claude/agents/ (every project), with a name, a description (what Claude reads to know when to call it), its tools, and an optional model:.

Claude auto-delegates based on each agent's description, or you can call one by name. Set model: per agent (haiku / sonnet / opus / fable or inherit) to control cost.

6.2 Subagent: security-reviewer

Audits your code for vulnerabilities without contaminating your main conversation.

Create it with this prompt:

Create this subagent in my project at .claude/agents/security-reviewer.md. Use the exact content below:

---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
---

You are a senior security engineer. Review the code looking for:
- Injection vulnerabilities (SQL, XSS, CSRF)
- Authentication and authorization failures
- Hardcoded secrets or credentials in the code
- Insecure data handling (sensitive info in logs, missing sanitization)

Return a summary with severity (high / medium / low) and the exact line number of each finding.

To use it:

Use the security-reviewer subagent to review the authentication module (the /app/api/auth/ folder and /lib/auth.ts). I want a report with high/medium/low severity and exact line references.

6.3 Subagent: project-documenter

Maintains your project's memory between sessions. This is one of the highest-leverage tools in this entire guide.

Every time you open a new Claude conversation, Claude has zero memory of what happened before. This subagent maintains PROJECT_STATE.md — a running log of what's been built, what decisions were made, and what's next.

Create it:

Create this subagent in my project at .claude/agents/project-documenter.md. Use the exact content below:

---
name: project-documenter
description: Keeps PROJECT_STATE.md updated between sessions. Invoke before and after every large task.
tools: Read, Write, Edit, Glob, Grep
---

You are the project documentarian. You NEVER write feature code — you only document.

You are invoked in three cases:
1. Before a large task (>3 files or a new feature): write a clear TODO list of the steps.
2. After completing it: update PROJECT_STATE.md with what was done, what's pending, decisions made, and known issues.
3. When a non-obvious detail appears (workaround, gotcha, convention): add it.

Structure of PROJECT_STATE.md:
# Project State

**Last updated:** [date]

## What this project is
[1–2 paragraphs]

## Current status
- ✅ [completed]
- 🚧 [in progress — what's left]
- 📋 [planned — why it matters]

## Decisions made
- [decision] — [why, alternatives discarded]

## Gotchas / non-obvious things
- [detail that would surprise someone new]

## Immediate next steps
- [what to tackle next time]

Rules:
- English, concise, short bullets
- Do not duplicate information from the code (paths, function names)
- If a decision changes, UPDATE the line — don't add a new one
- If a feature completes, move from 🚧 to ✅ and remove the "what's left" detail
- If PROJECT_STATE.md exceeds 150 lines, compress old entries or archive them in docs/HISTORY.md

After creating the subagent, run this second prompt to wire it into your project:

Add these two rules to the end of my CLAUDE.md, in a section called "Session Rules":
- At the start of every session, read PROJECT_STATE.md for context
- Before and after large tasks, invoke the project-documenter subagent

First use:

Invoke the project-documenter subagent to create an initial PROJECT_STATE.md based on the current state of the project.

Every new session:

Read CLAUDE.md and PROJECT_STATE.md before we start.

If Claude forgets to update it:

Invoke the project-documenter subagent to update PROJECT_STATE.md with what we just did.

6.4 Which Do I Reach For?

Seven tools, seven jobs. Here's the whole toolkit in one glance (for what each one is, see Part 4):

6.5 Agent Teams (experimental)

A subagent is one contractor you send off alone. An agent team is a whole crew with a foreman — they share a task list and hand work back and forth.

Subagents work alone and report back to you. Agent Teams go a step further: several Claude sessions work together — they share one task list and can message each other, with a lead agent coordinating. Reach for a team when the steps depend on each other and the agents need to hand work back and forth, not just run in isolation.

It's an experimental feature, off by default. Turn it on in your settings, then ask Claude to "create an agent team" for the job:

{
  "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" }
}

Claude comes in several models. Early on you don't need to think about this — Claude Code ships with a strong default and you just build. But as your projects grow, picking the right model for each task becomes the biggest single lever on speed and cost. The rule is short: use the most capable model for the hard thinking, and send the simple, high-volume work to a cheaper, faster one.

Two places you pick a model

• Inside Claude Code. Your main session runs a model (switch it with the model picker, /model), and every subagent names its own. You already saw this in Part 6: Subagents — a security reviewer can declare model: opus right in its file.
• In AI features you build. When your own app calls the Claude API, you pass a model ID (like claude-opus-4-8) on every request. That is billed per token, separate from your Claude Code subscription — so here, model choice is a real cost decision.

The lineup

The scaling rule

1. Build with the most capable model first (Opus). Get it working — don't optimize cost before the thing works at all.
2. Then route the easy, repetitive parts down. Once a task is well-defined and runs at volume — tagging records, sorting messages, short replies — move it to Sonnet or Haiku.
3. Keep Opus (and Fable) for the hard parts — the planning, the architecture, the gnarly bug. The goal is "right model per task," not one model for everything.

Need more thinking power? ultrathink

Sometimes the model is capable enough, but the problem is hard — a subtle bug, a thorny architecture decision. You can ask Claude to reason harder before it answers: just include the word ultrathink anywhere in your prompt, and it spends extra effort thinking on that turn.

There's a race condition somewhere in the checkout flow. ultrathink about what could cause it before you change any code.

It's a one-off nudge for a single message, not a setting. (Only ultrathink is a real keyword — phrases like "think hard" or "think harder" aren't special.)

7.1 What MCPs Are

MCP = Model Context Protocol. Think of an MCP as a live connection that gives Claude direct access to an external service.

Without an MCP, Claude can only write code that talks to Stripe — it can't actually reach into your Stripe account. With an MCP installed, Claude acts directly on the service: creates products in Stripe, deploys to Vercel, queries your database, opens a PR on GitHub.

7.2 How to Install Any MCP

You never need to figure out the install command. Just ask Claude:

Install the MCP for [service] in Claude Code and get it ready to use. If it needs an API key or authentication, explain step by step where to get it and where to put it.

Replace [service] with the name (Stripe, GitHub, Vercel, Supabase, etc.).

To see your active MCPs:

claude mcp list

To get details on one:

claude mcp get github

To remove one:

claude mcp remove github

Find more MCPs at: aitmpl.com/mcps — filtered by category (databases, APIs, productivity, etc.)

⚠️ Don't install too many MCPs at once. Each one loads context at session start and can slow things down. Install what you need, when you need it — same principle as keeping your skills lean (4.7).

7.3 The Essential MCPs

Ordered by how often you'll use them during development:

1. GitHub — Most Universal

Claude creates issues, opens PRs, reads comments, merges branches, all from the conversation.

Install the GitHub MCP in Claude Code and connect it to my account. Explain what permissions it needs and how to authorize access.

2. Vercel — Deploy Control

Once installed, Claude can deploy, view live logs, check build status, and manage environment variables without you opening the dashboard.

Install the Vercel MCP in Claude Code and authorize it against my account. When done, verify it works by telling me the status of my project's last deploy.

3. Supabase — Direct Database Access

Claude can query tables, run migrations, check rows, and debug issues without you opening the Supabase dashboard.

Install the Supabase MCP in Claude Code connected to my project. Tell me exactly where to find my project URL and service role key, and where to put those values. When ready, list my tables.

4. Stripe — Payment Operations

Claude creates products, views charges, manages subscriptions, processes refunds — all through conversation.

Install the Stripe MCP in Claude Code. It will open an authentication flow with my Stripe account — guide me step by step. When done, list my active products.

5. Resend — Send Test Emails

Claude sends emails directly without you writing a curl command. Useful for testing transactional email templates.

Install the Resend MCP in Claude Code and connect it with my RESEND_API_KEY (it's in .env.local). When done, send me a test email to [your@email.com] with subject "MCP working".

6. Playwright — Claude Sees Your App

Claude opens a real browser, navigates your site, clicks buttons, fills forms, and takes screenshots — all autonomously.

Install the Playwright MCP in Claude Code. When done, open my site at localhost:3000 and take a screenshot of the hero section to confirm it's working.

7. Firebase — Hosting & More (Google)

If your project runs on Firebase (like aicontodo.com does), the official Firebase MCP lets Claude manage Hosting, check deploy status, and work with Firebase services without leaving the chat.

Install the official Firebase MCP (firebase@claude-plugins-official) in Claude Code and connect it to my Firebase project. When done, tell me my Hosting site's current deploy status.

7.4 Two More Worth Adding

Once you're comfortable, two more MCPs pull a lot of weight:

Context7 — current, correct docs

Claude's training has a cutoff date, so for fast-moving libraries it can suggest an old or removed function. Context7 fetches the current, version-specific documentation for what you're using, on demand — far fewer "that doesn't exist anymore" moments.

Install the Context7 MCP in Claude Code so it can pull up-to-date documentation for the libraries in my project.

Chrome DevTools — Claude inspects a real browser

Like Playwright, but deeper: Claude can open Chrome and read the console errors, network requests, and performance — so it debugs a live page the way you would with the browser's developer tools open.

Install the Chrome DevTools MCP in Claude Code, then open my site, check the console for errors, and tell me what's failing.

8.1 If You're on Vercel

Vercel's web dashboard is good, but the CLI is faster. Set it up by asking Claude directly — don't go command by command:

Set up the Vercel CLI for this project, step by step:

1. Check if I have Node.js installed. If not, tell me how and stop.
2. Install the Vercel CLI globally with npm.
3. Run `vercel login` and guide me through authentication (it will open a browser).
4. Run `vercel link` and guide me to connect this local project to its Vercel project.
5. At the end, run `vercel --version` and `vercel env ls` to confirm everything works and that I have project variables available.

If You're on Firebase

Firebase Hosting is great for static sites and single-page apps — it's what aicontodo.com itself runs on. Three commands:

firebase login         # sign in (opens a browser)
firebase init hosting  # one-time: pick your project + the folder to deploy
firebase deploy        # push your site live

8.2 The 4 Vercel Commands You'll Use Every Day

vercel env pull — Downloads your Vercel environment variables to your local .env.local. Run this whenever you add a new key to the Vercel dashboard.

vercel env pull .env.local

vercel env add — Adds a new environment variable from the terminal (no dashboard needed).

vercel env add STRIPE_SECRET_KEY production

vercel logs — Live logs from your deployed app. Essential for debugging production errors.

vercel logs

vercel deploy — Deploy to production directly, bypassing GitHub. Use for a quick preview before committing.

vercel deploy --prod

The golden workflow for env variables:

1. Add a key in Vercel dashboard
2. Run vercel env pull .env.local locally
3. You now have it in both places — no manual copy-paste, ever

8.3 Pre-Deploy Checklist

Before every push to main, Claude should run through this (see Part 4 for the deploy-checklist Skill that automates it):

8.4 Other CLIs Worth Knowing

The same "manage from the terminal" logic applies to other services:

Rule: If a service takes you more than 3 repetitive clicks per day, look for its CLI. If you don't know the commands, ask Claude — it knows the documentation for all of them.

9.1 The 3 Things You Need from the Dashboard

You never need to write Stripe code yourself. Claude writes it. But you do need to get 3 values from the Stripe dashboard and put them in the right places.

Where to find them: Stripe Dashboard → Developers → API keys

1. Publishable key (pk_test_... or pk_live_...)

• Goes in your frontend code (safe for users to see)
• Opens the Stripe checkout form

2. Secret key (sk_test_... or sk_live_...)

• Goes only in your backend / environment variables — NEVER in the frontend
• Creates payment sessions, processes charges
• If this leaks: rotate it immediately from the dashboard

3. Webhook secret (whsec_...)

• Verifies that payment notifications actually came from Stripe
• Create it: Stripe Dashboard → Developers → Webhooks → Add endpoint

• Endpoint URL: https://your-app.vercel.app/api/webhook
• Listen to: checkout.session.completed (minimum)
• Copy the Signing secret Stripe shows you

9.2 Environment Variable Naming

In your .env.local (and mirrored in Vercel dashboard):

STRIPE_PUBLISHABLE_KEY=pk_test_xxxxx
STRIPE_SECRET_KEY=sk_test_xxxxx
STRIPE_WEBHOOK_SECRET=whsec_xxxxx

9.3 The One-Prompt Stripe Implementation

Once keys are in .env.local, give Claude this prompt:

Implement the full Stripe checkout flow in this Next.js app:
- An API route that creates a payment session
- A button on the frontend that triggers it
- A webhook that updates the database when payment is confirmed
The keys are already in .env.local.

Claude builds all of it in a few minutes. Your job is to understand what you're asking for and where the keys go.

9.4 Test Mode Rules

• Always develop in test mode first. Test mode keys start with pk_test_ and sk_test_. No real money moves.
• Test card: 4242 4242 4242 4242 — any future expiry, any CVC
• Switch to live mode when you're ready to charge real money. Replace test keys with pk_live_ and sk_live_ keys from the Stripe dashboard.

These are non-negotiable. Violating them can expose customer data or result in financial loss.

10.1 The Hardcoded Secrets Rule

Never, under any circumstances, paste an API key directly into code.

All secrets belong in environment variables:

• Local dev: .env.local (never committed to GitHub)
• Production: Vercel dashboard → Environment Variables

If a secret is ever committed to GitHub: rotate it immediately from the service's dashboard.

10.2 What Goes Where

10.3 Control What Claude Can Do — Permissions

Secrets are about what lives in your code. Permissions are about what Claude is allowed to do on your computer — which commands it can run and which files it can touch. Claude Code is safe by default: it pauses and asks before anything that could change your system. You decide how much it asks.

How much it asks (modes). You met these in Staying in Control → Plan Mode: tap Shift+Tab to cycle between ask-first (the default), auto-accept edits, and plan (read-only). There's also a bypass mode that asks for nothing — see the warning below.

Decide in advance (rules). Instead of approving the same things over and over, set standing rules in three lists:

• allow — runs without asking (e.g. Bash(npm run build), or reading your own source files).
• ask — always confirm first (e.g. Bash(git push *)).
• deny — never allowed, period (e.g. Bash(rm *), or Read(./.env) to keep Claude away from your secrets).

The golden rule: deny beats ask beats allow. So you can allow things broadly but carve out hard "never" zones that always win.

Open the rules panel — it lists every rule and which file it came from — with:

/permissions

The rules are stored as plain JSON in your settings file — a small example:

{
  "permissions": {
    "allow": ["Bash(npm run build)", "Read(./src/**)"],
    "ask":   ["Bash(git push *)"],
    "deny":  ["Bash(rm *)", "Read(./.env)"]
  }
}

Those settings live in three places, broad to specific:

• ~/.claude/settings.json — your defaults across every project.
• .claude/settings.json — project rules shared with your team (committed to Git).
• .claude/settings.local.json — your personal rules for this project (Git-ignored).

Recipe: fewer prompts, but still stop on the big stuff

If approving every little edit is slowing you down, here's how to cut the routine prompts without letting Claude run wild — so it stops nagging about safe edits but still pauses for anything that matters:

1. Switch to acceptEdits mode — tap Shift+Tab once. Claude now applies file edits and safe file commands without asking, but still stops to ask before running other shell commands, making network requests, or touching protected files like .git.
2. Put your "never" commands in deny (e.g. Bash(git push *), Bash(rm -rf *)). Deny rules always win — they hold even in the most permissive modes — so this is your safety net.
3. Start big tasks in Plan Mode: Claude lays out a plan and waits for your approval before acting. That's how you make it stop and check with you on the decisions that actually matter.

The blunt version (sandbox only): claude --dangerously-skip-permissions (also written --permission-mode bypassPermissions) skips routine prompts entirely. Even then it still honors your ask and deny rules, still hard-stops on dangerous deletions like rm -rf /, and still asks a clarifying question when one is truly needed — but it strips away nearly all the other guardrails, so only run it in a throwaway container or VM where nothing important can be lost.

The full rule syntax and the complete list of modes are on the official docs: code.claude.com/docs/en/permission-modes.

10.4 The Security Audit Prompt

Run this before every major release using the security-guidance plugin:

Run a full security audit on this project. Check for:
1. Hardcoded secrets or API keys anywhere in the code
2. SQL injection vulnerabilities
3. XSS and CSRF exposure
4. Authentication bypass risks
5. Sensitive data being logged

Give me a report with severity (high / medium / low) and exact file + line number for each finding.

10.5 Pre-Launch Security Checklist

11.1 What It Is

Ralph Loop is a plugin that makes Claude repeat a prompt iteratively until a task is complete. You define the task, set a completion signal, and let it run — while you do something else.

Philosophy: Iteration > Perfection. Don't aim for perfect on the first try. Let Ralph refine incrementally.

Install it from the plugin marketplace (/plugin) if you haven't already.

11.2 The Two Required Parameters

--completion-promise "WORD"

The exact string Claude must output to stop the loop. It's a literal text match — not semantic. If you set "DONE" and Claude writes "Done!", the loop does NOT stop.

Use clear, unambiguous strings: "DONE", "COMPLETE", "FIXED", "VERIFIED", "READY_FOR_REVIEW"

--max-iterations N

The hard cap on how many cycles run before the loop stops regardless of completion. This is your safety net against infinite loops.

Guidance:

• 5–10 — short, well-scoped tasks
• 15–30 — complete features or medium refactors
• 50+ — overnight runs where you're away

Rule: If the loop hits max iterations before completion, your prompt or success criteria weren't clear enough. Fix the prompt, don't just raise the number.

11.3 Basic Usage

/ralph-loop:ralph-loop "Your prompt here" --completion-promise "DONE" --max-iterations 10

Stop a running loop:

/ralph-loop:cancel-ralph

11.4 Ready-to-Use Templates

Build a feature:

/ralph-loop:ralph-loop "Implement [FEATURE].
Requirements: [list them]
Success: All requirements met, no linter errors, tests passing.
Output COMPLETE when done." --max-iterations 30 --completion-promise "COMPLETE"

Fix a bug:

/ralph-loop:ralph-loop "Fix this bug: [DESCRIPTION].
Steps: Reproduce → identify root cause → fix → write regression test → verify.
Output FIXED when done." --max-iterations 20 --completion-promise "FIXED"

Verify with Playwright (when you don't have written tests):

/ralph-loop:ralph-loop "Implement [FEATURE].
Verification: Use the Playwright MCP to open the app at localhost:3000, run the user flow manually, and confirm it works as expected (fill the form, click buttons, wait for result).
If something fails, read the browser console error, fix the code, and verify again.
Output VERIFIED when done." --max-iterations 30 --completion-promise "VERIFIED"

More examples — adapt these to your project

⚠️ These are examples, not magic spells. Adapt each to your own project and tools. Every loop needs a clear stop-word and a max-iterations cap, and check your token usage before leaving one running unattended. (Plugin commands change over time — confirm the current Ralph Loop command and flags on the plugin's page.)

1. Bilingual completeness — make sure every page has both languages:

/ralph-loop:ralph-loop "Check every page. Every visible piece of text must have both an English and a Spanish version. Add accurate translations where one is missing. Output BILINGUAL_DONE when no text is left untranslated." --completion-promise "BILINGUAL_DONE" --max-iterations 15

2. SEO pass — every page gets the basics:

/ralph-loop:ralph-loop "For each page, make sure it has a meta description, social-share (Open Graph) tags, a clean title, and one structured-data block — matching that page's real content. Add what's missing. Output SEO_COMPLETE when every page passes." --completion-promise "SEO_COMPLETE" --max-iterations 20

3. Fix until clean — no console errors, no broken links:

/ralph-loop:ralph-loop "Load each page and check for JavaScript console errors and broken internal links. Fix what you find. Output CLEAN when every page loads with zero console errors and no broken links." --completion-promise "CLEAN" --max-iterations 15

4. Brand-voice polish — consistent, accurate copy:

/ralph-loop:ralph-loop "Review each page's copy. Make it match our brand voice (clear, friendly, no hype) and confirm every claim is accurate — fix page by page. Output POLISHED when all pages pass." --completion-promise "POLISHED" --max-iterations 16

Notice the pattern: a clear "go through everything until each item passes" task + an unmistakable stop-word + a cap. That's the sweet spot for a loop.

11.5 When to Use (and Not Use) Ralph Loop

Good for:

• Well-defined tasks with measurable success (build this form, fix this bug)
• New project development you can leave running overnight
• Tasks with automatic verification (tests, linters, Playwright)
• Iterative refinement of something that's mostly working

Not for:

• Tasks that require your judgment or approval at multiple steps
• Vague or subjective goals ("make it better")
• Debugging production issues
• Anything involving real financial transactions or data deletion

11.6 Built-in Loops: /goal and /loop

Ralph Loop is a plugin. Claude Code also has two built-in ways to keep working on their own.

/goal — work until a finish line is met

Give Claude a checkable finish line and it keeps going, turn after turn, until that condition is true. After each turn a lightweight checker (a fast model) decides whether the goal is met — so the finish line has to be something it can actually verify.

/goal Every image in /public is under 200 KB and the build passes with no errors.

A vague goal ("make it good") can never be verified, so the loop never ends — be specific, and add a limit like "stop after 20 turns."

/loop — repeat on a schedule

Runs a prompt again and again on an interval (or lets Claude pace itself) — handy for checking on something periodically while you work.

/loop every 5 minutes, check if the deploy finished and tell me the moment it does

Recurring loops expire automatically after 7 days.

12.1 The 3 Required Legal Pages

Every product that collects user data or processes payments needs these three pages before launch. Create them before your cookie banner — the banner links to them.

Generate all three in one prompt:

Create the 3 legal pages for my project: Privacy Policy, Terms & Conditions, and Legal Notice. Each as its own route (/privacy, /terms, /legal).

You already know the MASTERPLAN and what data the app collects. These are the values you should NOT guess:
- Country where my business operates: [your country]
- Business name and contact email: [your name/company, contact@yourdomain.com]

If there's an important third-party service not already in the code (analytics, email, hosting), ask me before inventing it.

Write in plain, accessible English — not heavy legal jargon. Each page should link to the other two in the footer.

Disclaimer: Claude's draft is a solid starting point, but have a human review it before you rely on it — and a lawyer for anything sensitive (health data, kids' data, or operating across multiple countries).

12.2 Cookie Banner

All websites must inform users about cookies. Create the legal pages first, then the banner.

Create a cookie banner component for my site that:
- Appears the first time a user visits
- Allows accepting all cookies, rejecting all, or customizing (analytics, marketing)
- Saves the preference so it doesn't show again
- Complies with basic GDPR (explicit consent, reject button as prominent as accept)
- Links to /privacy and /cookies (also create /cookies if it doesn't exist)
- Matches the visual style of the rest of the site

12.3 Auth Patterns

Magic link = a one-time pass emailed to you (no password to remember). Password = your own key you keep.

Depending on your use case, implement one of these:

• Magic Link — User enters email → receives a link → clicks to log in. No password to remember. Best for B2B or low-friction products.
• Password — User enters email + password. More familiar for consumers.

Ask Claude which fits your MASTERPLAN and to implement it fully.

A. Glossary

The full glossary now lives up front so it is easy to reach any time: see Glossary — Words to Know (second item in the sidebar). It defines every term in this guide — grouped by topic and written in plain English.

B. Common Errors & Fixes

C. Cost & Token Management

• Claude Pro: Fine for getting started, but you'll hit usage limits on intensive build days.
• Claude Max (5×): Recommended for active development — enough capacity for full-day work sessions.
• Claude Max (20×): For daily power users who run long sessions and many agents.

Plans, tiers, and prices change — always check the current options at claude.com/pricing. Claude Code runs on your Claude subscription (not billed per token like the API). When you start building AI features that call the API directly, see Choosing Your Model for picking the right model per task.

To reduce token waste:

• Start new conversations when switching to a different part of the project
• Use @filename references instead of pasting large files
• Use the project-documenter subagent to maintain PROJECT_STATE.md so you don't have to re-explain context
• Subagents isolate expensive file exploration from your main context

D. Resource Directory

Subagents are separate Claude instances with their own instructions and allowed tools. They keep your main conversation clean, prevent one agent from doing a job it shouldn't do (e.g., a builder reviewing its own code), and make it easy to call a specialist on demand.

These 7 agents should exist in every project. They live in .claude/agents/ and are project-scoped — you need to install them in each new repo.

13.1 The Core 7

Read the "Can write?" column. Planners, reviewers, the debugger, and the security auditor are deliberately read-only; only the builder, QA, and documenter can change files. That's a safety control, not just tidiness: a reviewer that can edit will quietly "fix" the very bug it should flag, and a read-only auditor has a far smaller blast radius if it's ever fed something malicious. The separation is the point — if one agent builds and reviews its own work, the review is worthless.

13.2 The One-Shot Deploy Prompt

Paste this into Claude Code at the start of any new project. It creates all 7 agents in one shot.

Create the following 7 subagents in .claude/agents/. Create each as a separate .md file with the exact content below.

---
FILE: .claude/agents/architect.md
---
name: architect
description: Invoked before building any new feature or making a major technical decision. Plans the approach, reviews the MASTERPLAN, proposes file structure, identifies risks, and defines success criteria. Does NOT write feature code.
tools: Read, Glob, Grep
---

You are a senior software architect. You plan before anything is built.

When invoked, you:
1. Read MASTERPLAN.md and CLAUDE.md to understand the project
2. Read PROJECT_STATE.md to know what's already built
3. Propose a clear implementation plan: which files to create/modify, what functions/routes are needed, what dependencies are required
4. Identify risks, edge cases, and dependencies that could block progress
5. Define measurable success criteria for the task

Rules:
- Never write production code. Your output is a plan, not an implementation.
- If the MASTERPLAN is unclear on something, list your assumptions explicitly.
- Flag any decision that would conflict with the existing stack (CLAUDE.md stack-context).
- Recommend breaking large features into phases if scope is large.

---
FILE: .claude/agents/builder.md
---
name: builder
description: Implements features and fixes based on a plan from the architect. Used for all development work. Invoked after the architect has defined the approach.
tools: Read, Write, Edit, Bash, Glob, Grep
---

You are a senior full-stack engineer. You build exactly what was planned.

When invoked, you:
1. Read the architect's plan (or ask for one if none exists)
2. Read relevant existing files before modifying anything
3. Implement the feature following CLAUDE.md conventions strictly
4. Run build and tests after each significant change to catch errors early
5. Report what you built and any deviations from the plan

Rules:
- Never introduce libraries or patterns not already in the stack without asking first.
- Never hardcode secrets, API keys, or environment-specific values.
- Always read a file before editing it.
- If you discover a risk or ambiguity mid-build, stop and report — don't guess.
- Write code that a new team member could understand without explanation.

---
FILE: .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Reviews code changes before merging to main or staging. Invoked after builder finishes, before any git push. Looks for bugs, anti-patterns, style violations, and missing edge cases.
tools: Read, Glob, Grep, Bash
---

You are a senior code reviewer. You catch what the builder missed.

When invoked with a set of files or a feature to review:
1. Read every changed file in full
2. Check for logic errors, off-by-one errors, unhandled edge cases
3. Check for violations of the conventions in CLAUDE.md
4. Check for security issues (hardcoded secrets, missing input validation, exposed data)
5. Check for performance issues (N+1 queries, unnecessary re-renders, missing indexes)
6. Output a structured report:
   - 🔴 Blockers (must fix before merging)
   - 🟡 Warnings (should fix soon)
   - 🟢 Suggestions (optional improvements)

Rules:
- Never edit code directly. You report only.
- Be specific: include the file path and line number for every finding.
- If the code is clean, say so explicitly — don't manufacture feedback.

---
FILE: .claude/agents/qa-tester.md
---
name: qa-tester
description: Writes tests, runs them, and verifies user flows. Invoked after builder finishes a feature or before deploying to production.
tools: Read, Write, Edit, Bash, Glob, Grep
---

You are a QA engineer. You verify that what was built actually works.

When invoked:
1. Read the feature spec or the architect's plan to understand expected behavior
2. Write or update tests covering: happy path, edge cases, error states
3. Run the test suite and report results
4. If Playwright MCP is available, verify the user flow in a real browser
5. Output a test report: what was tested, what passed, what failed

Rules:
- Tests must be runnable, not pseudocode.
- Prioritize integration tests over unit tests for user-facing features.
- If a test fails, investigate the root cause — don't just report the failure.
- Never modify production code. If you find a bug, document it and hand back to the builder.

---
FILE: .claude/agents/debugger.md
---
name: debugger
description: Invoked when something is broken and the cause is unknown — a failing test, a runtime error, wrong output, or a bug a user reported. Investigates and finds the root cause. Does NOT fix code; hands the diagnosis to the builder.
tools: Read, Glob, Grep, Bash
---

You are a debugging specialist. You find the true root cause before anyone changes code.

When invoked:
1. Reproduce the problem first — confirm you can see the failure before theorizing.
2. Read the relevant code and trace the ACTUAL execution path, not the assumed one.
3. Form one hypothesis at a time and test it (a log line, a minimal check, the failing input).
4. Identify the single root cause — not just the symptom or the line that threw the error.
5. Output a diagnosis: what's happening, why, the exact file/line, and a recommended fix for the builder.

Rules:
- Never edit production code. You diagnose and hand off; the builder fixes.
- Don't guess. If you can't reproduce it, say exactly what you'd need to.
- Distinguish the root cause from the symptom — explain the chain between them.
- One root cause, clearly explained, beats five vague maybes.

---
FILE: .claude/agents/security-auditor.md
---
name: security-auditor
description: Security-focused code review. Invoked before any production release or when adding authentication, payments, or data handling. Reports vulnerabilities by severity.
tools: Read, Glob, Grep, Bash
---

You are a senior security engineer. You find vulnerabilities before they reach production.

When invoked:
1. Scan all code for hardcoded secrets (API keys, tokens, passwords, connection strings)
2. Check for injection vulnerabilities: SQL injection, XSS, CSRF
3. Audit authentication and authorization logic — who can access what
4. Check that sensitive data is not logged or exposed in error messages
5. Verify that all user inputs are validated and sanitized before use
6. Output a report with:
   - 🔴 High (exploitable, fix immediately)
   - 🟡 Medium (fix before launch)
   - 🟢 Low (good practice to fix)
   - ✅ Clean (explicitly confirm what was checked and found clean)

Rules:
- Never edit code. You report only.
- Include exact file path and line number for every finding.
- If a secret is found in the code, flag it as a blocker — do not continue until it is removed.

---
FILE: .claude/agents/project-documenter.md
---
name: project-documenter
description: Maintains PROJECT_STATE.md between sessions. Invoke before and after any large task (new feature, major refactor, significant bug fix).
tools: Read, Write, Edit, Glob, Grep
---

You are the project documentarian. You never write feature code — only documentation.

You are invoked in three cases:
1. Before a large task: write a clear TODO list of the steps.
2. After completing it: update PROJECT_STATE.md with what was done, what's pending, decisions made, and known issues.
3. When a non-obvious detail appears (workaround, gotcha, convention): add it.

Structure of PROJECT_STATE.md:
# Project State

**Last updated:** [date]

## What this project is
[1–2 paragraphs]

## Current status
- ✅ [completed]
- 🚧 [in progress — what's left]
- 📋 [planned — why it matters]

## Decisions made
- [decision] — [why, alternatives discarded]

## Gotchas / non-obvious things
- [detail that would surprise someone new]

## Immediate next steps
- [what to tackle next time]

Rules:
- English, concise, short bullets.
- Do not duplicate information already in the code.
- If a decision changes, UPDATE the existing line — don't add a new one.
- If PROJECT_STATE.md exceeds 150 lines, compress old entries or archive to docs/HISTORY.md.

13.3 How to Invoke Agents

Manually (most common):

Use the architect agent to plan how to implement [feature].

Use the builder agent to implement the plan above.

Use the code-reviewer agent to review everything in /app/api/payments/.

Use the security-auditor agent before I push to main.

The standard feature workflow:

You don't run the whole crew every time. For a small UI fix: builder + code-reviewer. For a new payment flow: all of them.

13.4 Deploy Them Well

A crew is only worth it if you run it well. Three habits keep it cheap and sharp:

1. Match the model to the agent — your biggest cost lever. Each agent file can name its own model: (see Choosing Your Model). Put your best on the thinking, routine work on something faster and cheaper:

• Opus (your best) → architect, debugger, security-auditor — the jobs that must be right.
• Sonnet (the all-rounder) → builder, code-reviewer, qa-tester — steady, high-volume work.
• Haiku (fast & cheap) → project-documenter and quick read-only lookups.

A sensible default, not a rule — adjust per project.

2. Let Claude call them for you — or summon one by name. Each agent's description tells Claude when it's relevant, so Claude auto-delegates ("this touches payments → security-auditor"). When you want a specific one, just name it: "Use the debugger agent to find why checkout fails."

Put together, the rhythm is: architect plans → you approve → builder builds → qa-tester + code-reviewer check → debugger only if it breaks → security-auditor before launch → project-documenter logs it. No agent grades its own homework, and you spend your priciest model only where it counts.

13.5 Add This to Your CLAUDE.md

After installing the agents, add this block to your project's CLAUDE.md so Claude knows the workflow:

## Agent Workflow

For any new feature:
1. Run architect agent to plan
2. Get approval before building
3. Run builder agent to implement
4. Run qa-tester to verify
5. Run code-reviewer before any push to staging/main
6. If something breaks, run debugger to find the root cause, then hand the fix to builder
7. Run security-auditor if the feature touches auth, payments, or user data
8. Run project-documenter after completing the task

Agents live in .claude/agents/. Invoke them by name: "Use the [name] agent to..."

Last updated: June 2026 — Based on Rupo Claude Code Workshop (5-day intensive) + Anthropic official documentation