Practical workflows, prompting patterns, and team best practices learned from real production projects.
Getting Started
New to Claude Code? Here's how to go from zero to productive in under 10 minutes, regardless of your role.
1
Install Claude Code
Install via the VS Code extension marketplace or the CLI (npm install -g @anthropic-ai/claude-code). Both give you the same capabilities.
2
Open your project folder
Navigate to your project directory. Claude automatically reads your CLAUDE.md and understands your project structure.
3
Start with something small
Don't start with a massive task. Try 'explain what this file does' or 'find where the login flow is handled' to build familiarity.
4
Gradually increase scope
Once comfortable, try editing a file, writing a test, or generating a component. Build trust in the workflow before tackling larger tasks.
Quick-start prompts by role
Developers
• “Read through the codebase and explain the architecture”
• “Write unit tests for this function and run them”
• “Find all places where we call the Stripe API”
Designers & UX
• “Here's a screenshot — implement this design as a React component”
• “Check this page for accessibility issues and fix them”
• “Make this component responsive for mobile”
Marketers & Content
• “Update the hero headline on the landing page to focus on speed”
• “Add SEO meta descriptions to all pages that are missing them”
• “Give me 3 CTA variants to A/B test on the pricing page”
Set Up a Dedicated Workspace
Before you even open Claude Code, create a dedicated folder for each project or task. This gives you a clean environment to manage outputs, add context files, clone repos, and keep everything organized.
Open this folder in your terminal or VS Code, then launch Claude Code from there. This way, Claude has direct access to everything it needs — and you have a single place to find all artifacts from the session.
CLAUDE.md & Project Memory
A CLAUDE.mdfile at the root of your project is like a briefing document that Claude reads automatically at the start of every session. It's the single most impactful thing you can do to improve Claude's output quality.
What to include in CLAUDE.md
Architecture overview — Tech stack, key directories, how things connect
Conventions — Naming patterns, file organization, coding standards your team follows
Local dev setup — Port numbers, environment variables, how to run the app
Key decisions — Why you chose certain tools or patterns (so Claude doesn't suggest alternatives)
Gotchas — Known quirks, things that break easily, common mistakes
Example CLAUDE.md
# My Project
## Architecture
- Next.js 16 App Router with Tailwind CSS v4
- Database: PostgreSQL via raw SQL (no ORM)
- Auth: Auth0 v4 SDK
## Conventions
- API routes go in src/app/api/
- Components are organized by feature, not type
- Use 'query' helper for all DB calls (src/lib/db.ts)
## Local Development
- Port: 3200 (do not change)
- Run: npm run dev
- Env: copy .env.example to .env.local
Memory between sessions:Claude Code also maintains a memory system that persists across conversations. If you tell Claude to “remember” something, it saves it for future sessions — useful for personal preferences, project context, and recurring patterns.
Start with Clear Context & Goals
The more context you give upfront, the better the output. Don't start with a vague “build me a feature” — front-load your request with structured information.
Include in your first message:What you're building and why, technical constraints, links to relevant docs, example use cases, and what's already done (so Claude doesn't redo work).
Do
Share a detailed spec with "what" and "why"
List file paths explicitly
State what's already done
Include links to relevant docs or APIs
Avoid
Vague asks like "fix the app"
Leaving out existing code context
Huge paragraphs with no structure
Assuming Claude knows your repo layout
Use Plan Mode, Then Act Mode
Don't jump straight to coding. Use Plan Mode to explore the codebase, understand existing patterns, and propose architecture before writing a single line.
1
Plan Mode — Explore & Propose
Claude reads existing code, identifies patterns (auth flows, API routes, component structure), and proposes a detailed architecture. This catches scope surprises before any code changes.
2
Review the Plan
You review and give feedback. This is where you catch misunderstandings or redirect the approach — much cheaper than fixing implemented code.
3
Act Mode — Implement
Once aligned, Claude implements the approved plan. The code follows the patterns it discovered during exploration, so it fits naturally into your codebase.
Rule of thumb: Use Plan Mode for anything touching more than 3 files. The upfront planning consistently saves time compared to jumping straight into code.
Effective Prompting Patterns
Certain prompting patterns consistently lead to better results. Here are the ones that work in practice.
Patterns that work
“Where are we at?” — Great for resuming after interruptions
“What do we need to set up to run locally?” — Proactive about prerequisites
“Can you generate a comprehensive PR summary?” — Leveraging Claude for documentation
“Does this tell you anything?” + [terminal output] — Sharing raw data for debugging
“Small request — rename X to Y” — Clear, scoped requests
“Nothing more, nothing less” — Prevents over-engineering and scope creep
Patterns to avoid
“Fix the app” — Too vague, forces Claude to guess
“Improve this code” — Leads to unnecessary refactoring without clear goals
Approving everything without reading — Especially risky for destructive operations
Asking Claude to run long-running commands — Things like prisma db push against remote DBs are better run yourself
Test & Debug Iteratively
The build-test-debug loop is where Claude Code really shines. When something doesn't work, the quality of what you share determines how fast you get to a fix.
Do
Share the exact terminal output or error message
Include screenshots of the UI behavior
Paste full stack traces, not just the error line
Mention what you expected vs. what happened
Avoid
Just saying "it doesn't work"
Paraphrasing error messages from memory
Skipping the terminal output
Only sharing part of the stack trace
Real example
An OAuth flow returned 401. Instead of saying “auth is broken,” sharing the exact error led Claude to discover the correct endpoints via .well-known — a fix that would have taken much longer with a vague description.
Unit Testing with Claude
Unit tests verify that individual pieces of your code — a function, a component, an API route — work correctly in isolation. They're the safety net that catches bugs before they reach production, and Claude Code is exceptionally good at writing them.
Why unit tests matter
Catch regressions early — When you change code, tests tell you immediately if something else broke
Enable confident refactoring — You can restructure code knowing tests will flag any behavior changes
Document expected behavior — Tests show exactly how a function should behave, including edge cases
Speed up code review — Reviewers trust changes more when they come with passing tests
Reduce debugging time — A failing test points you to exactly what broke, not a vague “the app is broken”
How to get Claude to write great tests
1
Point Claude to the code
Share the file path and function name. Claude will read the implementation and understand what needs testing — inputs, outputs, edge cases, and error paths.
2
Be specific about what to test
Instead of 'write tests for this file,' say 'write unit tests for the calculateScore function — cover null inputs, boundary values, and the case where all categories score zero.'
3
Specify your test framework
Tell Claude which framework to use (Jest, Vitest, Playwright, pytest, etc.) and where test files should go. If your project already has tests, point Claude to an existing test file as a pattern to follow.
4
Run the tests together
Ask Claude to run the tests after writing them. If any fail, share the output — Claude can debug and fix test issues in the same session.
Example prompt
Write unit tests for src/lib/assessment/scoring.ts
- Use Vitest (our test runner)
- Follow the pattern in __tests__/example.test.ts
- Cover: valid inputs, missing data, boundary scores (0 and 100), and invalid category names
- Mock the database calls, test the scoring logic in isolation
- Run the tests when done and fix any failures
Do
"Write tests for the calculateScore function covering edge cases"
"Add tests that verify the API returns 401 for unauthenticated requests"
"Follow the existing test patterns in __tests__/"
"Run the tests and fix any failures before committing"
Avoid
"Write tests" with no specifics about what to test
Asking for tests without specifying the test framework
Skipping the "run the tests" step — untested tests are just code
Testing implementation details instead of behavior
Pro tip: After Claude writes tests, ask it to “review these tests — are we missing any edge cases or error paths?” Claude often catches gaps in its own test coverage when prompted to self-review.
Git Operations with Guardrails
Claude Code can handle git operations directly, but certain operations need human oversight. Establish clear guardrails.
Let Claude handle
• git add, git commit, git push for feature branches
• Creating descriptive commit messages from the diff
• Generating PR summaries
Review before running
• Force pushes or rebase operations
• Anything touching main / production branches
• Commits with --no-verify (understand why hooks are failing first)
Handle PR Reviews Systematically
When you get PR feedback, don't address items one at a time. Use Claude to batch the work efficiently.
1
Share the full review
Copy the complete PR review comments — Claude can parse and categorize them.
2
Categorize by priority
Ask Claude to classify issues as High / Medium / Low priority, and propose which to fix now vs. follow-up.
3
Batch the fixes
Implement all fixes in a focused session, then commit with a descriptive message referencing the review.
4
Verify & push
Run tests, confirm the fixes, and push in a single commit.
Working with Design & UX
Claude Code isn't just for backend developers. Designers, UX researchers, and front-end folks can use it to rapidly prototype, implement designs, and bridge the gap between mockups and code.
What designers can do with Claude
• Screenshot-to-code — Paste a screenshot or mockup and ask Claude to implement it in your framework
• Component creation — Describe a component's behavior and Claude builds it with proper accessibility
• Design system enforcement — Reference your design tokens and Claude will use them consistently
• Responsive layouts — Ask Claude to make existing components work across breakpoints
• Accessibility audits — Claude can review components for WCAG compliance and fix issues
Example prompt for UX work
Here's a screenshot of our new pricing page design.
Implement this as a React component using:
- Our design system (Tailwind with tokens in globals.css)
- Sora for headings, Inter for body text
- Brand color #2063F8
- Make it responsive (mobile-first)
- Include proper aria labels and keyboard navigation
Tip for designers:You don't need to know how to code to use Claude Code effectively. Describe what you want in plain language — “a card with a subtle shadow that slides up on hover” — and Claude translates your design intent into working code.
Content & Copywriting
Marketers and content strategists can use Claude Code to draft, refine, and manage content directly within the codebase — no handoff required.
Content tasks Claude handles well
• Page copy — Write or rewrite headlines, descriptions, CTAs directly in the component files
• SEO metadata — Generate title tags, meta descriptions, and Open Graph content for every page
• Content audits — Review all pages for consistency in tone, terminology, and messaging
• A/B test variants — Generate multiple headline or CTA options to test
• Structured data — Add JSON-LD schema markup for rich search results
Do
Share your brand voice guidelines and target audience upfront
Ask Claude to edit copy in-place within the actual component files
Provide examples of copy you like and ask Claude to match the tone
Request multiple options: "give me 3 headline variants for A/B testing"
Avoid
Asking for generic copy without brand context
Having Claude write copy in a separate doc then manually pasting it in
Forgetting to specify the audience (B2B vs B2C changes everything)
Not reviewing copy for accuracy — Claude can sound confident about wrong facts
SEO
Claude Code is a powerful SEO co-pilot — it can audit pages, generate schema markup, optimize metadata, and implement technical fixes directly in your codebase without switching between tools.
What SEOs can do with Claude
Technical audits — Ask Claude to crawl your routes and check for missing meta tags, broken canonical URLs, duplicate titles, or missing hreflang tags
Schema markup — Generate JSON-LD structured data (FAQ, HowTo, Article, Product) and inject it directly into page components
Meta optimization — Rewrite title tags, meta descriptions, and Open Graph tags across all pages in a single session
Internal linking — Analyze your site structure and suggest internal link opportunities based on content relevance
Core Web Vitals — Identify render-blocking resources, image optimization issues, and layout shift problems in the code
Sitemap & robots.txt — Generate or update XML sitemaps and robots.txt rules based on your current routes
Programmatic SEO — Build template-driven pages at scale (location pages, comparison pages) with unique content and proper canonicalization
Example prompt
Audit the SEO for our marketing pages:
1. Check every page in src/app/ for missing or duplicate meta titles and descriptions
2. Verify Open Graph tags are present on all public pages
3. Look for pages missing canonical URLs
4. Generate JSON-LD Article schema for our blog posts
5. List any images missing alt text
Output a summary table of issues found and fix the critical ones.
Pro tip: Pair Claude Code with Google Search Console data. Export your GSC performance report, share it with Claude, and ask it to identify pages with high impressions but low CTR — then have it rewrite the meta descriptions for those specific pages.
Paid Search
Paid search managers can use Claude Code to build landing pages, analyze campaign data, implement tracking, and automate repetitive tasks — all without waiting on a dev team.
What paid search marketers can do with Claude
Landing page creation — Describe your offer, audience, and keywords — Claude builds a conversion-optimized landing page that matches your design system
A/B test variants — Generate multiple headline, CTA, and layout variants for testing, each in its own component or route
Tracking & pixels — Implement Google Ads conversion tracking, Meta pixel events, or custom UTM parameter handling directly in the code
Dynamic keyword insertion — Build pages that swap headlines or content based on URL parameters from ad campaigns
Ad copy at scale — Generate responsive search ad copy (headlines + descriptions) from a product feed or feature list, formatted for bulk upload
Performance dashboards — Build internal reporting pages that pull from Google Ads or Analytics APIs to visualize campaign performance
Do
"Build a landing page for our [product] campaign targeting [keyword] — match our brand design system"
"Add Google Ads gtag conversion tracking to the signup form submission"
"Generate 15 RSA headline variants for our top-performing ad group"
"Read UTM params from the URL and display the matching offer headline"
Avoid
Asking for landing pages without specifying the audience or offer
Implementing tracking without specifying which events to fire
Building pages that don't match the existing design system
Forgetting to test conversion tracking in preview mode first
APIs & Integrations
Claude Code is excellent at working with third-party APIs — reading docs, generating client code, debugging webhook payloads, and building integrations from scratch.
1
Share the API documentation
Paste the relevant API docs, or point Claude to the URL. Claude can fetch and read documentation pages to understand endpoints, auth patterns, and response shapes.
2
Start with a single endpoint
Don't ask Claude to build an entire API client at once. Start with one endpoint — get it working, test it, then expand. This catches auth issues early.
3
Share real responses
Paste actual API responses (with secrets redacted) so Claude can build accurate types and handle real-world edge cases, not just the happy path from docs.
4
Debug with raw payloads
When webhooks or API calls fail, share the raw request/response. Claude can spot issues like wrong content types, missing headers, or malformed payloads instantly.
Example prompt
I need to integrate with the Stripe API for subscription billing.
Here's the relevant docs: https://docs.stripe.com/api/subscriptions
Auth: Bearer token via STRIPE_SECRET_KEY env var
Build a helper at src/lib/stripe.ts that:
1. Creates a checkout session for a given price ID
2. Handles the webhook for subscription.created
3. Uses proper TypeScript types from the stripe package
We already have the stripe npm package installed.
Database Operations Safely
Database changes require extra caution. ORM commands against production databases can have irreversible consequences.
The safe approach
Ask Claude to generate the SQL migration file
Review the SQL yourself
Run it via your database dashboard or psql
Learned the hard way:prisma db push against production once wanted to drop columns. Generating a standalone SQL migration and running it manually is always safer.
Pair Programming Mode
Claude Code isn't just a task runner — it's an effective pair programming partner. Instead of giving Claude a complete task and waiting for results, you can think through problems together in real time.
When to pair program with Claude
Exploring unfamiliar code — “Walk me through how auth works in this codebase” is faster than reading every file yourself
Rubber-duck debugging — Explain the bug to Claude and let it ask clarifying questions. Often you'll spot the issue just by describing it
Architecture decisions — “I'm deciding between approach A and B — what are the tradeoffs?”
Learning new patterns — “Show me how server components work in Next.js with an example from our codebase”
Code review prep — Before submitting a PR, ask Claude to review your changes and flag potential issues
Do
"Think through this with me — I'm not sure of the best approach yet"
"What are the tradeoffs between these two approaches?"
"Review what I just wrote and tell me what I'm missing"
"Explain this error like I'm seeing this codebase for the first time"
Avoid
Only using Claude for complete, pre-defined tasks
Not sharing your thought process or constraints
Ignoring Claude's suggestions without explaining why
Treating it like a search engine instead of a collaborator
The “teach me” pattern:If Claude makes a change you don't understand, ask “explain why you did it this way.” This turns every task into a learning opportunity — especially valuable for junior developers or anyone working in an unfamiliar part of the stack.
Multi-Agent & Parallel Tasks
For complex tasks, Claude Code can spawn sub-agents — independent workers that research, search, or analyze in parallel. This is a power-user feature that dramatically speeds up broad tasks.
How it works
Automatic delegation — When a task requires searching many files or exploring multiple approaches, Claude automatically spawns sub-agents to work in parallel
Independent context — Each sub-agent has its own context window, so exploring large codebases doesn't eat into your main conversation's capacity
Results synthesis — Sub-agents report back, and Claude combines their findings into a coherent answer
Tasks that benefit from parallel agents
• Searching for all usages of a deprecated API across a large monorepo
• Running different types of audits (SEO, accessibility, performance) at the same time
• Researching multiple implementation approaches before making a recommendation
• Reviewing changes across many files in a large PR
You don't need to manage this manually.Claude decides when parallel work is appropriate. But you can encourage it: “Search the entire codebase for all places we use the old auth pattern — check both the API routes and the frontend components.”
Security & Secrets
Claude Code can read your entire filesystem, which means it can see .envfiles, API keys, and credentials. That's powerful for development — but it means you need guardrails to prevent secrets from leaking into commits, logs, or generated code.
Never let Claude commit these
• .env / .env.local files with real credentials
• API keys, tokens, or passwords hardcoded in source files
• Private keys, certificates, or service account JSON files
• Database connection strings with embedded passwords
Safe practices
• Keep a .env.example with placeholder values — Claude can read this for context without seeing real secrets
• Add .env* to your .gitignore (most frameworks do this by default)
• Review git diff before approving any commit — check for accidentally included secrets
• Use environment variables for all sensitive values, never inline strings
• Tell Claude “use environment variables for all credentials” in your CLAUDE.md
If a secret gets committed: Don't just delete it in a new commit — it's still in git history. Rotate the credential immediately, then use git filter-branch or BFG Repo-Cleaner to scrub the history.
Manage Your Context Window
Long conversations degrade quality as the context window fills up. Know the signs and act before it becomes a problem.
Signs it's time for a new session
• Context usage exceeds ~75%
• The conversation has shifted to a new topic
• You're starting a new round of review fixes
• Claude starts “forgetting” earlier decisions
Ask Claude to “create a context summary for a new session” before ending. The new conversation picks up exactly where you left off.
The Ideal Workflow
Here's the end-to-end workflow that consistently produces the best results.
1
Share detailed requirements + context
Structured prompt with what, why, file paths, constraints, and what's already done.
2
Plan Mode — Explore & propose
Let Claude explore the codebase and propose architecture before writing code.
3
Review & approve the plan
Catch misunderstandings early when changes are cheap.
4
Act Mode — Implement in focused batches
Claude implements the approved plan, following existing codebase patterns.
5
Test locally & share logs
Build → test → share terminal output if issues arise → iterate.
6
Commit, push, create PR
Let Claude generate descriptive commit messages and PR summaries.
7
Handle review feedback in batches
Categorize, prioritize, fix in one commit, verify, push.
8
Start a new session when context gets large
Ask for a context summary, then continue fresh.
Common Gotchas
These are the most common pitfalls people hit when starting with Claude Code. Knowing them upfront saves hours of frustration.
Context window filling up
Long conversations degrade output quality. If Claude starts repeating itself, forgetting earlier decisions, or producing lower-quality code, it's time for a fresh session. Ask for a “context summary” before starting a new conversation.
Hallucinated file paths or APIs
Claude sometimes references files or functions that don't exist, especially in large codebases. Always verify file paths in the output. If Claude says “I'll update src/lib/utils/helpers.ts,” make sure that file actually exists before approving.
Over-engineering simple tasks
Without constraints, Claude tends to add error handling, type guards, abstractions, and edge-case coverage that you didn't ask for. Use phrases like “nothing more, nothing less” or “keep it simple” to keep scope tight.
Approving without reviewing
Claude asks for permission before running commands or making changes. It's tempting to approve everything quickly, but always read what's being proposed — especially for git operations, file deletions, and anything touching production databases.
Not specifying existing patterns
If your project uses a specific pattern (e.g., raw SQL instead of an ORM, or a particular folder structure), tell Claude explicitly. Otherwise it may default to the most common approach — which might not match your codebase.
Treating every session as independent
Claude Code has memory and project files (CLAUDE.md) that persist between sessions. Set these up once and every future conversation starts with full project context — no need to re-explain your stack every time.
Team Patterns & Anti-Patterns
Quick reference for teams adopting Claude Code.
Patterns that work
Practice
Why it works
List file paths explicitly
Eliminates ambiguity, Claude can jump straight to reading
State what's already done
Prevents Claude from re-solving solved problems
Plan mode for >3 files
Catches scope surprises before any code changes
Name the branch
Critical for monorepos or feature branches
Say “nothing more, nothing less”
Prevents over-engineering and scope creep
Interrupt and redirect quickly
A quick correction is cheaper than letting it finish wrong
Anti-patterns to avoid
Anti-pattern
What happens
“Fix the app”
Forces Claude to guess, wastes rounds on clarification
“Improve this code” without specifics
Leads to unnecessary refactoring
Not mentioning existing code
Claude may create duplicates instead of reusing
Huge prompts with no structure
Bullet points and headers are parsed much faster
Approving everything without reading
Especially risky for destructive operations
Prompt Template
Use this template as a starting point for complex tasks. It front-loads the context Claude needs to produce great results on the first try.