Claude Code Mastery

Step 1: Node.js. Open your terminal, type node --version. If it says v22 or higher, move on. If not: Mac brew install node, or download from nodejs.org. Verify: node --version should say v22.x.x.

Step 2: VS Code or Cursor. Download from code.visualstudio.com (free) or cursor.com. Install. Open. Done.

Step 3: Claude Code CLI. In your terminal: npm install -g @anthropic-ai/claude-code. Verify: claude --version. First run: type claude, sign in when prompted.

Step 4: Docker Desktop. Download from docker.com/products/docker-desktop. Install. Open. It runs in the background. Verify: docker --version.

Step 5: GitHub. Sign up at github.com. In terminal: git config --global user.name "Your Name" and git config --global user.email "your@email.com". Verify: git --version.

Step 6: Supabase. Go to supabase.com, sign up free, create a project. Go to Settings then API. Copy the project URL and anon key somewhere safe.

Step 7: Vercel. Go to vercel.com, sign up with GitHub. That's it for now.

Verify everything by running: node --version, npm --version, git --version, docker --version, claude --version. All should return version numbers.

Create a file called CLAUDE.md in your project root. This is the operating system for Claude Code.

Section 1: Current Status. What phase you're in, what's done, what's next. Update this after every commit. Not every session. Every commit. Claude reads this first and it determines what Claude prioritizes.

Section 2: Critical Rules. Non-negotiable constraints. "Database First: run migrations before code." "No Hardcoded Colors: use CSS custom properties." "i18n Always: all text through next-intl." Without these, Claude makes reasonable but wrong choices.

Section 3: Source of Truth. Which documents are authoritative. This prevents Claude from inventing content when it should reference an existing brief.

Section 4: Critical Files. Files that should not be modified without care. Middleware, migrations, design tokens. Claude warns before touching these.

Section 5: AI Agent Rules. What Claude does automatically. "After every commit: update the Current Status section." These turn Claude from a passive tool into an active project member.

Test it: open Claude Code from your project folder. Ask: "What project are we working on?" Claude should answer from your CLAUDE.md. If it does, the file works.

MCP 1: Supabase (most impactful). Claude can query your database, inspect tables, check RLS policies, run migrations. You stop writing SQL by hand. Setup: npx supabase mcp setup. It asks for your project URL and service role key. Test: ask Claude "What tables exist in my database?" It should list them.

The difference: before MCP, you tell Claude your schema. After MCP, Claude inspects the actual schema. Migrations are accurate because Claude sees reality, not your description.

MCP 2: Context7 (documentation). Claude looks up current docs for any library. Not training data from months ago. Today's docs. Verify: ask Claude to look up a specific API from Next.js or Supabase.

MCP 3: Vercel. Claude checks deployment status, sets environment variables, manages projects. Real use: "Set up the Supabase URL and anon key as Vercel environment variables" and Claude does it. No dashboard clicking.

MCP 4: Figma (if you use Figma). Claude reads design specs from Figma files. Component sizes, colors, spacing, typography. Exact values instead of eyeballing screenshots.

After setup, verify: ask Claude "What MCPs do you have access to?" It should list them and confirm connectivity.

Create the skills folder: mkdir -p .claude/skills. Skills are markdown files Claude reads when relevant. Auto skills trigger on keyword detection. Manual skills are invoked with /skill-name.

Skill 1: critical. Create .claude/skills/critical/SKILL.md. Write your non-negotiable rules: Database first, run migrations before code. No hardcoded colors, use CSS variables. Validate all input on POST/PUT/PATCH. Never commit secrets. Run build before committing. Add a Lessons Learned section. Every production mistake becomes a new rule here.

Skill 2: page-build. Create .claude/skills/page-build/SKILL.md. Your build conventions: the file structure pattern for new pages, spacing standards, typography rules, testing requirements, the commit checklist.

Skill 3: eod (end of day). Create .claude/skills/eod/SKILL.md. The wrap-up routine: update CLAUDE.md status, stage changed files, commit with descriptive message, push, output summary for tomorrow.

Verify: ask Claude "What skills do you have access to?" Then test: "I want to build a new page." Claude should follow your page-build patterns automatically.

The key insight: skills are instructions, not documentation. Write them as commands: "Use CSS custom properties" not "The project uses CSS custom properties."

Step 0: Check your environment. If you switch between projects, run your check script to confirm Supabase, Vercel, and Git point to the right project. Takes 3 seconds. Prevents the "I ran a migration on the wrong database" disaster.

Step 1: Open your project in VS Code. Open the terminal. Type claude. Claude Code starts and reads your CLAUDE.md automatically. It also reads your skills, so it knows your patterns and rules.

Step 2: Check the status. Ask Claude: "What's our current status?" It reads CLAUDE.md and tells you. If the status is wrong, fix it now.

Step 3: Check what's next. "What are the next deliverables?" Claude reads your roadmap or CLAUDE.md and lists them. Now you both know what you're working on.

Three steps. Two minutes. Claude has full context.

Coming back after a long break? Claude still picks up perfectly. CLAUDE.md has the status. The restart file has the last session's notes. The setup-info skill has the environment config. Claude reads all three automatically. Nothing is lost.

Step 1: Plan before building. Don't type "build a contact form." Type: "I need a contact form. Before writing code, plan the approach. What components? What API route? What validation? What tests?" Claude proposes. You adjust. First-attempt quality goes from 80% to 95%.

Step 2: Build in small pieces. Not the entire feature at once. "Build the form component." Then "Add validation." Then "Create the API route." Then "Add email sending." Each piece is small enough to review, test, and revert.

Step 3: Test as you go. After building the form: "Write a Playwright test that verifies the form renders on all locales and validates required fields." Run it immediately. Fix what fails before moving on.

Step 4: Second pass. After the feature is complete: "Review everything you just built. Check for missing error handling, inconsistent naming, hardcoded strings, accessibility issues, mobile layout problems." Claude always finds things. Fix them now.

Step 5: Commit. Stage specific files, not git add -A. Descriptive message. Update CLAUDE.md status.

A contact form takes 45-60 minutes this way. Without the process it takes the same time but with more bugs, no tests, and hardcoded strings to extract later.

The quick check (2 minutes, before every commit): npm run build. Zero errors means the code compiles. Then: npx playwright test. All tests pass. If anything fails, fix it before committing. Never commit with known failures.

The thorough check (10 minutes, at phase end):

1. Hardcoded values. Search src/ for hex colors, hardcoded strings, pixel values that should be tokens.

2. TypeScript quality. Search for: any type (should be a real type), console.log (remove before commit), TODO comments (track them).

3. Security basics. Does every API route validate input? Are there secrets in committed files? Does every new table have RLS?

4. i18n completeness. Are there raw English strings in components? Do all three locale files have the same keys?

5. Build and test. npm run build zero errors. npx playwright test all pass. Open localhost and visually check.

Automate this: create a phase-check skill that runs all five. Or ask Claude: "Run a quality check on the codebase." Claude does all five checks.

Step 1: Update CLAUDE.md status. "Update the current status: contact page is complete, insights page is next."

Step 2: Update restart notes. "What did we work on today? What decisions did we make? What should we start with tomorrow?" Save this in CLAUDE.md or a restart.md file.

Step 3: Commit everything. Stage changed files, descriptive message, push.

Step 4: Verify the push. Check that it succeeded. If using Vercel, check deployment started.

What this prevents: tomorrow morning confusion ("What was I working on?"), lost context ("Why did we use Zod instead of yup?"), uncommitted work sitting overnight, stale CLAUDE.md that misleads tomorrow's Claude.

The compound effect: after a week, your restart notes become a project journal. After a month, you can trace every decision. After three months, a new team member reads the history and understands not just what was built but why.

Skills grow from mistakes. You deploy a page with missing German translations. New rule in critical: "Never commit i18n changes without verifying all three locale files." That mistake never happens again.

Skills grow from patterns. You've built five pages with the same structure. The page-build skill gets refined: better spacing values, a testing checklist that catches what you've actually missed.

Skills grow from research. You discover getSession() trusts the client JWT without verification. New rule in security: "Always use getUser() for auth checks." Include the why so you remember the reason.

Building a new skill step by step: mkdir -p .claude/skills/i18n. Start with what you know: all text through useTranslations, add keys to all three locale files, Dutch informal (je/jij), keep technical terms English, namespace per page. Start with 3 rules. Add more as you learn.

Monthly review: read through your skills. Remove outdated rules. Merge duplicates. Update what evolved. Maintained skills are a living knowledge base. Forgotten ones become misleading.

The compound effect: after three months your critical skill has 20+ rules. That's 20 mistakes that never happen again. Every new team member inherits all your hard-won knowledge on day one.

One file per page: e2e/about.spec.ts, e2e/contact.spec.ts. Each tests four things.

1. It loads. All three locales return 200. Loop through en, nl, de and verify each.

2. Content is correct. Key text appears in the right language. Not just "the page loads" but "the Dutch heading says the right thing."

3. It works on mobile. No horizontal overflow at 375px width. Check scrollWidth vs clientWidth.

4. Interactive elements work. Forms validate, navigation opens, accordions toggle.

How to ask Claude for tests: not "write tests for contact" but "Write Playwright tests for the contact page. Test: 200 status all locales, form validation (empty shows errors, valid succeeds), responsive at 375px, correct heading per locale." Specific asks produce specific tests.

The accumulation: after 10 pages you have 50+ test cases. Running npx playwright test before a commit takes 30 seconds and catches regressions you'd never find manually. Refactoring becomes safe because tests verify nothing broke.

The pragmatic truth: test behavior, not appearance. Design tweaks and copy changes don't need tests. Form submissions and API routes do.

Do you need this? Solo developer, one machine: nice to have. Multiple developers: prevents "works on my machine." Deploying to production: your dev matches production.

Step 1: Create Dockerfile.dev for development with hot reload. FROM node:22-alpine, WORKDIR /app, COPY package files, RUN npm install, COPY everything, EXPOSE 3000, CMD npm run dev.

Step 2: Create docker-compose.yml. Services: dev service that builds from Dockerfile.dev, maps port 3000, mounts your code as a volume (so edits reflect instantly), passes environment variables from .env.local.

Step 3: Run it. docker compose up dev. Open localhost:3000. Your project runs inside Docker. Edit a file in VS Code. Browser updates. Same experience as npm run dev, but consistent.

Step 4: Stop it. docker compose down.

What just happened: your project runs in a container with Node 22 on Alpine Linux, regardless of what's on your machine. A colleague clones the repo, runs docker compose up dev, gets the exact same environment.

The production Dockerfile uses a multi-stage build: base, dependencies, build, runner. The runner stage uses a non-root user and minimal image. Ask Claude to generate it for your specific project.

Day 1 vs Day 30.

CLAUDE.md: started with 5 rules. Now has 15. Each new rule prevented a mistake that happened once and never happened again. The Current Status section has been updated 40+ times. Always accurate.

Skills: started with 3. Now have 8-10. Each earned its existence by solving a recurring problem. The critical skill has 15+ lessons learned. New team members read it and skip the mistakes you already made.

Tests: started with 0. Now have 100+. Every page tested in all locales. Every form validated. Refactoring is safe because tests catch regressions in 30 seconds.

Daily rhythm: morning ritual takes 2 minutes and gives perfect context. Building follows a predictable pattern. Quality checks are automatic. Evening wrap-up takes 5 minutes and tomorrow starts exactly where today ended.

The compound effect: each skill makes Claude smarter. Each test makes refactoring safer. Each CLAUDE.md update makes context loading faster. The system doesn't just maintain quality. It raises the baseline.

The honest truth: not every lesson sticks on day 1. The morning ritual takes a week to become automatic. The second pass feels expensive until it catches a production bug. Skills feel like overhead until the third time they prevent the same mistake. Give it 30 days.