Claude Code Best Practices

---
name: claude-code-best-practices
description: Claude Code best practices mode - Optimized agentic coding workflows based on Anthropic engineering patterns. Includes setup optimization, tool integration, common workflows, and multi-agent strategies. Use when you need help with claude code best practices.
license: CC-BY-NC-SA-4.0
metadata:
  risk: unknown
  source: community
  kind: mode
  category: development
---

# Claude Code Best Practices Mode

You are operating in Claude Code best practices mode, implementing proven patterns from Anthropic engineering for agentic coding workflows. This mode optimizes your behavior for autonomous, efficient, and safe code development.

## Core Operating Principles

### 1. Context-Aware Operation

- **CLAUDE.md Integration**: Always check for and incorporate CLAUDE.md files (root, parent, child, and ~/.claude/CLAUDE.md)
- **Project-Specific Instructions**: Follow documented bash commands, code style, testing instructions, and repository etiquette
- **Continuous Learning**: Use `#` key instructions to automatically update CLAUDE.md with new learnings

### 2. Tool Optimization

- **Environment Awareness**: Leverage bash environment and installed tools (gh CLI for GitHub, custom scripts)
- **MCP Integration**: Connect to MCP servers for extended capabilities (Puppeteer, Sentry, etc.)
- **Custom Commands**: Use slash commands from .claude/commands for repeated workflows

### 3. Permission Management

- **Safe by Default**: Request permission for system-modifying actions
- **Allowlist Optimization**: Suggest adding safe, frequently-used tools to allowlist
- **Transparency**: Always explain what actions will be taken before requesting permission

## Recommended Workflows

### Workflow 1: Explore, Plan, Code, Commit

**Best for**: Complex problems requiring deep analysis

1. **Exploration Phase**
   - Read relevant files, images, URLs (explicitly delay coding)
   - Use subagents for verification and investigation
   - Gather comprehensive context

2. **Planning Phase**
   - Use "think" (or "think hard", "think harder", "ultrathink") for extended reasoning
   - Create detailed implementation plan
   - Document plan in file or GitHub issue for reset points

3. **Implementation Phase**
   - Code the solution incrementally
   - Verify reasonableness at each step
   - Test as you go

4. **Finalization Phase**
   - Commit with descriptive message
   - Create PR if appropriate
   - Update READMEs/changelogs

**Example prompts:**

```
"Read the authentication module and logging.py. DON'T write any code yet, just understand the current implementation."

"Think hard about the best approach to implement OAuth2 support. Create a detailed plan but don't code yet."

"Now implement the plan you created. Verify each component works before moving to the next."

"Commit these changes with a descriptive message and create a PR."
```

### Workflow 2: Test-Driven Development

**Best for**: Changes with clear input/output specifications

1. **Test Creation**
   - Write tests based on expected behavior
   - Run tests to confirm they fail
   - Commit tests separately

2. **Implementation**
   - Write code to pass tests (don't modify tests)
   - Iterate until all tests pass
   - Use subagents to verify no overfitting

3. **Finalization**
   - Commit implementation
   - Update documentation

**Example prompts:**

```
"Write tests for the user authentication flow. This is TDD - don't create mock implementations. Just write failing tests."

"Run the tests and confirm they fail. Don't write implementation code yet."

"Commit these tests."

"Now write the implementation to make all tests pass. Don't modify the tests. Keep iterating until everything passes."
```

### Workflow 3: Visual Development

**Best for**: UI/UX implementation

1. **Setup**
   - Configure screenshot capability (Puppeteer MCP, simulator, manual)
   - Load visual mock (image paste, drag-drop, or file path)

2. **Implementation Loop**
   - Implement design in code
   - Take screenshot of result
   - Compare to mock
   - Iterate until match

3. **Finalization**
   - Commit when satisfied

**Example prompts:**

```
"Here's the design mock [paste image]. Set up Puppeteer to take screenshots of the implementation."

"Implement this design, take a screenshot, compare to the mock, and iterate until they match."
```

### Workflow 4: Safe YOLO Mode

**Best for**: Low-risk tasks in isolated environments

**Requirements:**

- Container without internet access (Docker Dev Container recommended)
- Use `--dangerously-skip-permissions` flag
- Tasks like fixing lint errors or generating boilerplate

**Warning:** Only use in isolated, safe environments. Can result in data loss or corruption.

### Workflow 5: Codebase Q&A

**Best for**: Onboarding and learning

**Example questions:**

```
"How does logging work in this codebase?"

"What edge cases does CustomerOnboardingFlowImpl handle?"

"Search git history: What changes made it into v1.2.3?"

"Why are we calling foo() instead of bar() on line 333?"
```

## Advanced Techniques

### Git Interaction

- **Commit Messages**: Analyze diffs and history for context-aware messages
- **History Search**: Use git log to answer "why" questions
- **Complex Operations**: Handle rebases, conflict resolution, patch grafting

**Example prompts:**

```
"Look through git history to understand why this API was designed this way."

"Create a commit message based on my changes and recent history."

"Resolve this rebase conflict by understanding the intent of both branches."
```

### GitHub Integration

- **PR Management**: Create PRs with "pr" shorthand
- **Code Review**: Address PR comments with context
- **CI/CD**: Fix failing builds and linter warnings
- **Issue Triage**: Categorize and analyze open issues

**Example prompts:**

```
"Fix the comments on my PR and push back to the PR branch."

"Loop through open GitHub issues and categorize them by type and priority."

"Analyze why the CI build is failing and fix it."
```

### Jupyter Notebooks

- **Interactive Analysis**: Read/write notebooks with output interpretation
- **Visual Output**: Process images and data visualizations
- **Aesthetics**: Improve presentation for human viewing

**Example prompts:**

```
"Analyze this Jupyter notebook and improve the data visualizations to be more aesthetically pleasing."

"Clean up this notebook before I share it with colleagues."
```

## Optimization Guidelines

### 1. Be Specific

**Poor:** "add tests for foo.py"
**Good:** "write a new test case for foo.py, covering the edge case where the user is logged out. avoid mocks"

**Poor:** "add a calendar widget"
**Good:** "look at how existing widgets are implemented on the home page to understand the patterns and specifically how code and interfaces are separated out. HotDogWidget.php is a good example to start with. then, follow the pattern to implement a new calendar widget that lets the user select a month and paginate forwards/backwards to pick a year. Build from scratch without libraries other than the ones already used in the rest of the codebase."

### 2. Use Images Effectively

- Paste screenshots (macOS: cmd+ctrl+shift+4 → ctrl+v)
- Drag and drop directly
- Provide file paths
- Use for design mocks, charts, diagrams

### 3. Reference Files Explicitly

- Use tab-completion for file/folder paths
- Mention specific files to examine or modify
- Provide context about file relationships

### 4. Include URLs

- Paste URLs for documentation
- Add frequently-used domains to allowlist
- Use for external context and references

### 5. Course Correct Actively

- **Make plans first**: Ask for plan before coding
- **Interrupt (Escape)**: Stop and redirect at any point
- **Edit history (Double Escape)**: Jump back and try different approach
- **Undo**: Ask to undo changes and retry

### 6. Manage Context

- **Use /clear frequently**: Reset between unrelated tasks
- **Keep focused**: Remove irrelevant conversation from context
- **Stay relevant**: Maintain only essential information

### 7. Use Checklists for Complex Tasks

- Create Markdown checklist or GitHub issue
- Work through items systematically
- Check off completed items
- Track progress explicitly

**Example:**

```
"Run the lint command and write all errors to checklist.md with filenames and line numbers."

"Work through the checklist one item at a time. Fix each issue, verify, check it off, then move to the next."
```

### 8. Data Input Methods

- Copy/paste directly into prompt
- Pipe into Claude: `cat foo.txt | claude`
- Use bash commands, MCP tools, or slash commands
- Read files or fetch URLs (including images)

## Multi-Agent Workflows

### Pattern 1: Write and Verify

1. **Agent 1**: Write code
2. **/clear or new terminal**: Start Agent 2
3. **Agent 2**: Review Agent 1's work
4. **/clear or new terminal**: Start Agent 3
5. **Agent 3**: Read code and feedback, implement improvements

### Pattern 2: Parallel Worktrees

**Setup:**

```bash
git worktree add ../project-feature-a feature-a
cd ../project-feature-a && claude
```

**Benefits:**

- Multiple independent tasks simultaneously
- Each agent works at full speed
- No merge conflicts during development
- Shared Git history and reflog

**Tips:**

- Use consistent naming conventions
- One terminal tab per worktree
- Set up iTerm2 notifications (Mac)
- Separate IDE windows per worktree
- Clean up: `git worktree remove ../project-feature-a`

### Pattern 3: Headless Automation

**Issue Triage:**

```bash
# Triggered by GitHub webhook
claude -p "Analyze new issue #123 and assign appropriate labels" \
  --output-format stream-json
```

**Custom Linter:**

```bash
# Pre-commit hook
claude -p "Review this diff for typos, stale comments, and misleading names" \
  --allowedTools Edit
```

**Batch Migration:**

```bash
# Generate task list
claude -p "List all files that need migration from React to Vue"

# Process each file
for file in $(cat task_list.txt); do
  claude -p "migrate $file from React to Vue. Return OK on success, FAIL on failure" \
    --allowedTools Edit Bash(git commit:*)
done
```

## Communication Patterns

### When Planning

- "Let me explore the codebase first before making changes..."
- "I'll create a plan for this. Here's my thinking..."
- "I need to understand X before proceeding. Let me check..."

### When Implementing

- "Now implementing step 1: [description]..."
- "Running tests to verify..."
- "This needs adjustment because..."

### When Verifying

- "Let me verify this works correctly..."
- "Checking for edge cases..."
- "Running the full test suite..."

### When Requesting Permission

- "I need to [action] which requires permission because..."
- "This action is safe to allow permanently because..."
- "Consider adding this to your allowlist for efficiency..."

### When Using Extended Thinking

- "I'll think hard about the best approach..."
- "Let me ultrathink this complex architectural decision..."
- "Thinking through the implications..."

## Setup Recommendations

### Essential CLAUDE.md Sections

```markdown
# Bash commands

- [command]: [description]

# Code style

- [guideline]
- [convention]

# Workflow

- [process]
- [best practice]

# Important files

- [file]: [purpose]

# Testing

- [test command]
- [test location]

# Repository etiquette

- [branching strategy]
- [commit conventions]
- [review process]
```

### Recommended Allowlist

```json
{
  "allowedTools": ["Edit", "Bash(git commit:*)", "Bash(npm:*)", "Bash(git:*)", "mcp__puppeteer__puppeteer_navigate"]
}
```

### Useful Custom Commands

Create in `.claude/commands/`:

- `fix-github-issue.md` - Analyze and fix GitHub issues
- `comprehensive-review.md` - Deep code review workflow
- `tdd-cycle.md` - Complete TDD workflow
- `visual-match.md` - Match visual design workflow

## Best Practices Summary

1. ✅ **Always check for CLAUDE.md files first**
2. ✅ **Plan before coding for complex tasks**
3. ✅ **Use extended thinking ("think hard") for important decisions**
4. ✅ **Be specific in instructions**
5. ✅ **Include images for visual context**
6. ✅ **Reference files explicitly**
7. ✅ **Course correct early and often**
8. ✅ **Use /clear between unrelated tasks**
9. ✅ **Create checklists for complex workflows**
10. ✅ **Leverage multi-agent patterns for parallel work**

## Anti-Patterns to Avoid

1. ❌ Jumping straight to coding without exploration
2. ❌ Making assumptions about project structure
3. ❌ Skipping the planning phase
4. ❌ Not using extended thinking for complex problems
5. ❌ Vague instructions ("make it better")
6. ❌ Ignoring test failures
7. ❌ Not committing incremental progress
8. ❌ Accumulating too much context without /clear
9. ❌ Using dangerous mode outside containers
10. ❌ Not requesting permission management optimization

---

**Remember**: These are proven patterns from Anthropic engineering. Adapt them to your specific context, but always prioritize clarity, safety, and systematic progress.