Claude Code Best Practices

$ claude                                    # Open Claude (use npx or global npm on first install)
$ claude .                                  # Open in current directory
$ claude mcp add <servername> <command>     # Add an MCP server
$ claude --loops 10                         # Continue without changing (also supports "continue")
$ claude --dangerously-skip-permissions     # Danger mode: skip permission confirmations
$ claude --model claude-sonnet-4-20250514   # Specify a model

Give me an overview of this codebase
Explain how the documents are processed
What is the format of the document expected by the document_processor
Trace the process of handling user's query from frontend to backend
Draw a diagram that illustrate this flow
Describe the api endpoints
How can I run the application
explain the main architecture patterns used here
what are the key data models?
how is XXX handled?

find the files that handle user authentication
how do these authentication files work together
trace the login process from front-end to database

I need to implement a new ... system using ... . Think deeply about the best approach for implementing this in our codebase.
think about potential security vulnerabilities in this approach
think hard about edge cases we should handle

find XXX in our codebase
suggest how to refactor XXX to use XXXXX
Apply the change safely: refactor XXX to use XXXXX while maintaining the same behavior
verify refactor: run tests for the refactored code

use the code-reviewer subagent to check XXX
have the debugger subagent investigate why users can't log in
First use the A subagent to find performance issues, then use the optimiser subagent to fix them

$ git worktree add <directory>/<worktree-name>

# For example, establish three parallel worktrees under .trees:
$ git worktree add .trees/ui_feature
$ git worktree add .trees/testing_feature
$ git worktree add .trees/quality_feature

# List all active worktrees
$ git branch -a

# Dev cycle: open a terminal in each worktree directory, launch claude, commit changes:
$ git add .
$ git commit -m "feat: complete specific subsystem task"

# Merge isolated branches back into the main codebase from root:
$ git merge .trees/ui_feature
$ git merge .trees/testing_feature
$ git merge .trees/quality_feature

# Use the standard merge command to consolidate active worktrees:
# "use the git merge command to merge in all the worktrees in the .trees folder and fix conflicts"

# Clean up and remove completed worktrees:
$ git worktree remove <directory>/<worktree-name>

# Pattern 1: Piping Logs or Commands Directly
$ cat logs/error.log | claude -p "analyze these errors and suggest fixes"

# Pattern 2: Context reference using file symbols
Read @logs/performance.csv and create visualizations

# Pattern 3: Dynamic documentation scraping
Fetch https://api.example.com/docs and summarize the authentication flow

# Pattern 4: Direct inline log paste
Here's the error message: [paste large stacktrace logs]
Debug this issue.

# Pattern 5: Screenshot uploads for layout fixing
[Cmd + Ctrl + Shift + 4 Screenshot] → [Ctrl + V Paste]
"The UI looks broken in this screenshot. Fix the CSS."

Write comprehensive tests for the XXXX.

Requirements:
- Test successful XXX
- Test XXX scenario  
- Test network timeout handling
- Test invalid XX data
- Test duplicate transaction prevention

Use pytest and create fixtures for common test data.
DO NOT write any implementation code yet.

Run pytest and show me all the failing tests.
Confirm that each test fails for the RIGHT reason.

Now implement PaymentProcessor to make tests pass.
Run tests after each major change.
Keep iterating until all tests are green.

After passing, use a subagent to verify:
- Are we handling edge cases correctly?
- Is the code overfitting to the tests?
- Are there scenarios we haven't considered?

I'm getting this error: [paste stacktrace / logs]
Context:
- It happens when: [describe trigger conditions]
- Expected behavior: [describe expectations]
- Relevant files: @src/api/handler.py @src/database/connection.py
- Recent changes: [describe recent commits or edits]

Please:
1. Analyze the error and identify root cause
2. Explain why it's happening
3. Provide a fix with explanation
4. Add a test to prevent regression

cat logs/error.log | claude -p "Analyze these error logs
1. Identify patterns and common errors
2. Group related errors together  
3. Suggest root cause for each group
4. Prioritize fixes by impact"

Profile the performance of @src/data/processor.py
Identify bottlenecks and suggest optimizations.
Run benchmarks before and after changes.

find functions in XXX that are not covered by tests
Run pytest --cov to check test coverage.
Identify functions with < 80% coverage.
Generate tests for those functions.
Prioritize: critical business logic > utility functions > simple getters/setters

Review @document_name and generate tests for edge cases:
- Empty inputs
- Null/undefined values
- Maximum/minimum values
- Invalid types
- Concurrent access scenarios

Set up end-to-end tests using Puppeteer MCP server:

Test scenario: User checkout flow
1. Navigate to homepage
2. Add product to cart  
3. Proceed to checkout
4. Fill in payment details
5. Submit order
6. Verify success page

Take screenshots at each step.
Assert expected elements are present.
Verify no console errors.

Create integration tests for the REST API:
- Test authentication flow
- Test CRUD operations for each resource
- Test error responses (400, 401, 403, 404, 500)
- Test rate limiting
- Test pagination

Use real database (test environment) not mocks.

I just fixed a bug where user logout didn't clear session properly.

Please:
1. Write a regression test for this specific bug
2. Verify the test fails on the old code (checkout previous commit)
3. Verify the test passes on the fixed code
4. Add test to the CI pipeline
5. Document the bug in tests/REGRESSION_TESTS.md

Generate OpenAPI documentation for @src/api/

Include:
- All endpoints with descriptions
- Request/response schemas
- Authentication requirements
- Example requests and responses
- Error codes and meanings

Output to docs/api_spec.yaml

Review all Python files in @src/
Check if:
- All public functions have docstrings
- Complex logic has inline comments
- Type hints are present
- Docstring format follows Google style

Generate a report of missing documentation.

Perform a security audit of @src/

Check for:
1. SQL injection vulnerabilities
2. XSS vulnerabilities  
3. Hard-coded secrets/credentials
4. Insecure dependencies (check package.json)
5. Missing input validation
6. Insecure authentication/authorization

Create a report with severity levels and fixes.

Profile the application and identify performance bottlenecks:

1. Run load tests using locust
2. Analyze database query performance
3. Check for N+1 queries
4. Review API response times
5. Identify memory leaks

Generate optimization recommendations with expected impact.

Create GitHub Actions workflows:

1. .github/workflows/test.yml
   - Run on every PR
   - Execute all tests
   - Check code coverage (>80%)
   - Block merge if failing

2. .github/workflows/deploy.yml  
   - Run on main branch merge
   - Build Docker image
   - Push to registry
   - Deploy to staging

3. .github/workflows/claude-triage.yml
   - Trigger on new issue
   - Analyze issue content
   - Add appropriate labels
   - Assign to relevant team