Claude Code Best Practices

Name: Claude Code
Author: Anthropic

These aren't theoretical suggestions. They're battle-tested workflows from Anthropic engineers who use Claude Code every day. Follow these patterns, and you'll avoid 80% of common frustrations.

The Golden Workflow

This single pattern prevents most issues

The 80/20 Rule

Following "Explore → Plan → Code → Commit" prevents 80% of common issues. Master this workflow first, then add advanced techniques.

Part 1: Environment Customization

CLAUDE.md — Your Secret Weapon

CLAUDE.md files are persistent instructions that Claude reads every time. Think of them as programming Claude for your specific project.

CLAUDE.md Hierarchy

What to Include

Markdown

1# Project: My Awesome App
2 
3## Common Commands
4- `npm run dev` - Start dev server (port 3000)
5- `npm test` - Run Jest tests
6- `npm run lint` - ESLint with auto-fix
7 
8## Architecture
9- `/src/components` - React components (TypeScript)
10- `/src/lib` - Shared utilities
11- `/src/app` - Next.js App Router pages
12 
13## Code Style
14IMPORTANT: Always use TypeScript strict mode.
15YOU MUST: Add JSDoc comments to exported functions.
16NEVER: Use `any` type—use `unknown` instead.
17 
18## Testing
19- Write tests BEFORE implementation (TDD)
20- Avoid mocks unless necessary
21- Test edge cases: empty arrays, null, errors

Emphasis Keywords

Claude pays extra attention to these:

Keyword	Effect
IMPORTANT:	High priority instruction
YOU MUST:	Required behavior
NEVER:	Prohibited action
CRITICAL:	Absolute requirement

Where to Place CLAUDE.md

Location	Scope	Use Case
~/.claude/CLAUDE.md	Global	Personal preferences
../CLAUDE.md	Parent dir	Monorepo shared config
./CLAUDE.md	Project root	Project-specific rules
./src/CLAUDE.md	Subdirectory	Module-specific overrides

Generate Automatically

Bash

claude
/init

Claude analyzes your project and creates a tailored CLAUDE.md.

Update Quickly

Use the # shortcut:

Bash

# Add that we now use Prisma instead of raw SQL

Claude updates CLAUDE.md for you.

Part 2: The Core Workflows

Workflow 1: Explore → Plan → Code → Commit

The most important workflow. Master this first.

Detailed Workflow Steps

Step 1: Explore

Ask Claude to READ first, not write:

Bash

Read src/auth/login.ts and src/lib/jwt.ts to understand
our current authentication flow.

Bash

Now read the tests in tests/auth/ to see what's already tested.

Step 2: Plan

Request a detailed plan:

Bash

I need to add OAuth support. Think through how to implement this.

Claude activates extended thinking and provides a structured plan with potential issues.

Thinking modes:

think — Basic extended thinking
think hard — Deeper analysis
think harder — Very thorough
ultrathink — Maximum thinking time

Step 3: Code

Work through the plan systematically:

Bash

Looks good! Start with step 1 - add OAuth provider configuration.

Bash

Done. Now step 2 - the callback handler.

Don't skip steps. Let each piece complete before moving on.

Step 4: Commit

Bash

This looks great! Create a commit with an appropriate message.

Claude analyzes your changes and writes a meaningful commit message.

Workflow 2: Test-Driven Development

Claude excels with TDD because tests give clear targets.

TDD Loop

Step 1: Write Tests First

Bash

1I need a function that parses markdown frontmatter. Here are examples:
2 
3Input:
4---
5title: Hello
6---
7# Content
8 
9Output:
10{ title: "Hello", content: "# Content" }
11 
12Write comprehensive test cases. Use real calls, not mocks.

Step 2: Verify Tests Fail

Bash

Run the tests to confirm they fail (no implementation yet).

Step 3: Commit Tests

Bash

Commit the tests.

Step 4: Implement Iteratively

Bash

Now implement the parser. Run tests after each change.

Claude implements, runs tests, fixes failures, repeats until green.

Step 5: Commit Implementation

Bash

All tests passing! Commit the implementation.

Workflow 3: Visual Iteration

For UI work, iterate with screenshots.

Visual Feedback Loop

The Process

Share design mock (Figma screenshot, wireframe)
Claude implements
Take screenshot of result
Paste and ask for fixes
Repeat until perfect

Bash

[paste screenshot of Figma design]
 
Implement this dashboard component.

Bash

[paste screenshot of result]
 
Close but the spacing is off. Cards should have 24px gap, not 16px.

Bash

[paste updated screenshot]
 
Better! The blue should be #3B82F6 not #60A5FA.

Pro tip: On macOS, use Cmd+Ctrl+Shift+4 to screenshot directly to clipboard.

Workflow 4: Codebase Q&A

Use Claude like a knowledgeable colleague.

Bash

How does our logging system work?

Bash

Where should I add a new API endpoint?
Show me the pattern I should follow.

Bash

When did we switch from Express to Next.js? Why?

Claude searches your codebase and git history to answer.

Part 3: Tool Permissions & Extensions

Configure Permissions

Three ways to manage what Claude can do:

1. Interactive (during sessions):

Bash

Claude: I need permission to run bash commands.
You: [Check "Always allow" → Allow]

2. Via command:

Bash

/permissions

3. Manual configuration:

Edit .claude/settings.json:

JSON

1{
2  "allowedTools": ["read", "write", "edit", "bash", "grep"],
3  "autoApprove": {
4    "bash": ["npm install", "npm run dev", "git status"]
5  }
6}

Custom Slash Commands (Skills)

Create reusable prompts in .claude/commands/:

.claude/commands/fix-issue.md

Markdown

1# Fix GitHub Issue
2 
3Pull issue $ARGUMENTS from GitHub and:
41. Read the issue description
52. Locate relevant code
63. Propose a fix
74. Implement with tests
85. Create PR referencing issue

Usage:

Bash

/fix-issue 1234

See Claude Skills Guide for comprehensive coverage.

Part 4: Optimization Strategies

Be Specific

Use Images

Claude can see images. Use this for:

UI/UX work — Design mocks, screenshots
Bug reports — Show what's broken
Data visualization — Chart outputs
Architecture — Diagrams, ERDs

Reference Files Precisely

Use tab-completion:

Bash

Look at sr[TAB] → src/au[TAB] → src/auth/login.ts

Precise references = faster, more accurate responses.

Clear Context Between Tasks

Bash

/clear

Use liberally when:

Switching between unrelated tasks
After completing major features
Context feels muddled
Starting something complex

Course Correct Early

Request plans before coding:

Bash

Think through how to implement real-time notifications.

Interrupt with Escape: Press Escape to stop Claude mid-response.

Double-tap Escape: Edit your last prompt.

Ask for undos:

Bash

Undo those changes. I want to try a different approach.

Part 5: Multi-Claude Workflows

Parallel Verification

Use multiple Claude instances for better quality:

Parallel Verification Pattern

Terminal 1 (Claude A):

Bash

Implement the user authentication system

Terminal 2 (Claude B):

Bash

Review the authentication code in src/auth/ for security issues

Terminal 1 (Claude A):

Bash

Fix these security issues: [paste Claude B's findings]

Multiple Repository Checkouts

Work on multiple features simultaneously:

Bash

1# Clone to multiple directories
2git clone git@github.com:you/project.git project-feature-a
3git clone git@github.com:you/project.git project-feature-b
4 
5# Or use git worktrees (lighter)
6git worktree add ../project-feature-a feature-a
7git worktree add ../project-feature-b feature-b

Run Claude in each directory with separate tasks.

Headless Operations

For batch operations:

Bash

# Loop through files
for file in src/**/*.ts; do
  claude -p "Review $file for security issues" >> report.txt
done

Part 6: Pro Tips

Hidden Shortcuts

Shortcut	Action
Cmd/Ctrl + K	Clear screen
Escape	Interrupt Claude
Escape Escape	Edit last prompt
#	Update documentation
/	Slash commands menu
Tab	File/folder completion

Magic Phrases

Phrase	Effect
think / think hard	Extended thinking
IMPORTANT:	Emphasis in instructions
/init	Generate CLAUDE.md
/clear	Reset context

Debugging Claude

Claude is stuck:

Bash

/clear
Let's start over. [Rephrase clearly]

Claude is hallucinating:

Bash

Stop. Read the actual code first. Don't assume.

Same mistake repeatedly:

Bash

IMPORTANT: Do NOT use the `any` type.
YOU MUST use proper TypeScript types.

Results not good enough:

Bash

1think harder
2 
3This solution won't scale. Consider:
41. What happens with 1M users?
52. Database indexing
63. Caching layer
74. Rate limiting

Key Takeaways

The Golden Rules

Explore before coding — Read files, understand context
Plan before implementing — Use think modes
Be specific — Vague prompts = poor results
Iterate with feedback — Visual/test feedback improves outcomes
Clear context regularly — Fresh start = focused results
Use TDD — Tests guide implementation
Leverage tools — Skills, MCP, custom commands
Multiple Claudes for complex tasks — Separate contexts catch issues

Quick Reference

Essential Commands:

/init — Generate CLAUDE.md
/clear — Reset context
/permissions — Configure tools
# — Update documentation

Workflows:

Explore → Plan → Code → Commit
TDD: Tests → Red → Green → Commit
Visual: Mock → Implement → Screenshot → Iterate

Practice Exercises

Exercise 1: Create Your CLAUDE.md

Bash

1cd your-project
2claude
3/init
4 
5# Edit to add:
6# - Common commands
7# - Code style rules
8# - Testing guidelines

Exercise 2: TDD Feature

Write tests for a new feature
Verify tests fail
Have Claude implement until green
Commit tests, then implementation

Exercise 3: Visual Iteration

Find a UI design
Share screenshot with Claude
Implement and compare
Iterate 3-4 times until perfect

Next Steps

Claude Skills Guide — Create custom commands
MCP and Cursor — Extend capabilities
Automation Track — Automate workflows

You're Now a Power User!

These practices come from thousands of hours of real-world usage. Apply them consistently, and you'll see dramatic improvements in productivity and code quality. Start with the Explore → Plan → Code → Commit workflow—master that, then add other techniques.