# Claude Code Best Practices Deep Dive

## What Is It?

**Claude Code Best Practices** is a community-driven collection of workflows, commands, and agents for optimizing Claude Code usage. With **5 custom slash commands** and **10 specialized agents**, it provides a complete GitHub Flow integration for professional development.

**Repository:** [awattar/claude-code-best-practices](https://github.com/awattar/claude-code-best-practices)

---

## The Problem It Solves

Using Claude Code effectively requires:
- Consistent workflows for common tasks
- Specialized agents for different activities
- Integration with GitHub workflows
- Project-specific conventions

This repository provides:
- **Custom slash commands** for instant access
- **Specialized agents** for focused tasks
- **GitHub Flow integration** via CLAUDE.md
- **Templates** for project setup

---

## Key Statistics

| Metric | Value |
|--------|-------|
| **Custom Commands** | 5 |
| **Specialized Agents** | 10 |
| **GitHub Flow** | Full integration |
| **CLAUDE.md Template** | Included |
| **License** | MIT |

---

## Custom Slash Commands

### /commit

Quick commit with conventional format:

```markdown
# .claude/commands/commit.md

Generate a commit message for staged changes following Conventional Commits:

1. Run `git diff --staged`
2. Analyze changes
3. Generate message: `type(scope): description`

Types: feat, fix, docs, style, refactor, test, chore
```

**Usage:**
```bash
/commit
# Claude analyzes staged changes and suggests commit message
```

### /issue

Create GitHub issue from description:

```markdown
# .claude/commands/issue.md

Create a GitHub issue:

1. Accept issue description from user
2. Format with proper sections:
   - Title
   - Description
   - Acceptance Criteria
   - Labels suggestion
3. Use `gh issue create`
```

**Usage:**
```bash
/issue Add dark mode support
# Creates well-formatted GitHub issue
```

### /reviewpr

Review pull request for issues:

```markdown
# .claude/commands/reviewpr.md

Review the current PR:

1. Get PR diff with `gh pr diff`
2. Analyze for:
   - Code quality issues
   - Security concerns
   - Performance problems
   - Missing tests
3. Suggest improvements
4. Rate: Approve, Request Changes, or Comment
```

**Usage:**
```bash
/reviewpr
# Reviews current branch's PR
```

### /test

Generate tests for code:

```markdown
# .claude/commands/test.md

Generate tests for specified file or function:

1. Read the target code
2. Identify testable behaviors
3. Generate comprehensive tests:
   - Happy path
   - Edge cases
   - Error handling
4. Use project's testing framework
```

**Usage:**
```bash
/test src/utils.py
# Generates pytest tests for utils.py
```

### /custom-init

Initialize Claude Code in a project:

```markdown
# .claude/commands/custom-init.md

Set up Claude Code for this project:

1. Create .claude/ directory
2. Generate CLAUDE.md from template
3. Add project-specific rules
4. Configure slash commands
5. Set up recommended agents
```

**Usage:**
```bash
/custom-init
# Sets up complete Claude Code configuration
```

---

## Specialized Agents

### 1. Code Review Agent

Focus: Thorough code review

```markdown
# .claude/agents/code-review.md

You are a senior code reviewer. When reviewing:

1. Check for:
   - SOLID principles
   - DRY violations
   - Security issues
   - Performance concerns

2. Provide:
   - Specific line references
   - Concrete suggestions
   - Priority: Critical > Major > Minor

3. Be constructive, not critical
```

### 2. Documentation Agent

Focus: Writing and updating docs

```markdown
# .claude/agents/documentation.md

You are a technical writer. When documenting:

1. Focus on:
   - Clear explanations
   - Practical examples
   - Common use cases

2. Structure:
   - Overview
   - Quick Start
   - API Reference
   - Examples

3. Keep audience in mind
```

### 3. Refactoring Agent

Focus: Code improvement

```markdown
# .claude/agents/refactoring.md

You are a refactoring expert. When refactoring:

1. Preserve behavior (no new features)
2. Improve:
   - Readability
   - Maintainability
   - Performance
3. Make incremental changes
4. Ensure tests pass after each step
```

### 4. Security Audit Agent

Focus: Security analysis

```markdown
# .claude/agents/security.md

You are a security auditor. Check for:

1. OWASP Top 10:
   - Injection
   - Broken Auth
   - Sensitive Data
   - XXE
   - Access Control
   - Misconfig
   - XSS
   - Deserialization
   - Components
   - Logging

2. Report format:
   - Severity: Critical/High/Medium/Low
   - Location
   - Description
   - Remediation
```

### 5. Test Generation Agent

Focus: Comprehensive testing

```markdown
# .claude/agents/testing.md

You are a QA engineer. When generating tests:

1. Coverage types:
   - Unit tests
   - Integration tests
   - Edge cases

2. Patterns:
   - Arrange-Act-Assert
   - Given-When-Then

3. Aim for:
   - High coverage
   - Meaningful assertions
   - Clear test names
```

### 6. Performance Agent

Focus: Optimization

```markdown
# .claude/agents/performance.md

You are a performance engineer. Analyze:

1. Algorithmic complexity
2. Memory usage
3. I/O operations
4. Database queries
5. Network calls

Suggest:
- Caching strategies
- Lazy loading
- Batch processing
- Query optimization
```

### 7. Migration Agent

Focus: Version upgrades

```markdown
# .claude/agents/migration.md

You are a migration specialist. When migrating:

1. Assess:
   - Breaking changes
   - Deprecated APIs
   - New features

2. Create:
   - Step-by-step plan
   - Rollback strategy
   - Testing checklist
```

### 8. API Design Agent

Focus: API creation

```markdown
# .claude/agents/api-design.md

You are an API architect. Design APIs with:

1. REST best practices:
   - Proper HTTP methods
   - Status codes
   - Resource naming

2. Documentation:
   - OpenAPI/Swagger
   - Examples
   - Error responses
```

### 9. Debugging Agent

Focus: Bug investigation

```markdown
# .claude/agents/debugging.md

You are a debugger. When investigating:

1. Reproduce the issue
2. Identify root cause
3. Consider:
   - Recent changes
   - Environmental factors
   - Edge cases
4. Propose fix with tests
```

### 10. Architecture Agent

Focus: System design

```markdown
# .claude/agents/architecture.md

You are a software architect. When designing:

1. Consider:
   - Scalability
   - Maintainability
   - Security
   - Performance

2. Patterns:
   - Microservices vs Monolith
   - Event-driven
   - CQRS

3. Document decisions (ADRs)
```

---

## CLAUDE.md Template

The repository includes a comprehensive CLAUDE.md template:

```markdown
# Project: [Name]

## Quick Reference

### Commands
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`

### Branch Strategy
- main: Production
- develop: Integration
- feature/*: New features
- fix/*: Bug fixes

## Coding Standards

### Naming
- camelCase: variables, functions
- PascalCase: classes, types
- UPPER_SNAKE: constants

### Files
- Components: PascalCase.tsx
- Utilities: camelCase.ts
- Tests: *.test.ts

## Architecture

### Directory Structure
```
src/
  components/    # React components
  hooks/         # Custom hooks
  utils/         # Utility functions
  types/         # TypeScript types
```

## Do's and Don'ts

### Do
- Write tests for new features
- Use TypeScript strict mode
- Document public APIs

### Don't
- Commit .env files
- Use `any` type
- Skip code review
```

---

## GitHub Flow Integration

### Workflow

```
1. Create Branch
   └── /issue → Creates issue
   └── git checkout -b feature/issue-123

2. Development
   └── Make changes
   └── /test → Generate tests
   └── /commit → Commit with message

3. Review
   └── Push branch
   └── gh pr create
   └── /reviewpr → Self-review

4. Merge
   └── Address feedback
   └── Squash and merge
```

### Automation Hooks

```yaml
# .github/workflows/claude-review.yml
name: Claude Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Claude Review
        run: |
          # Trigger Claude Code review
          claude "/reviewpr"
```

---

## Project Setup

### Step 1: Clone the Repository

```bash
git clone https://github.com/awattar/claude-code-best-practices
```

### Step 2: Copy to Your Project

```bash
cp -r claude-code-best-practices/.claude your-project/
cp claude-code-best-practices/CLAUDE.md your-project/
```

### Step 3: Customize

```bash
# Edit CLAUDE.md with project specifics
vim your-project/CLAUDE.md

# Adjust commands for your stack
vim your-project/.claude/commands/*
```

### Step 4: Initialize

```bash
cd your-project
claude
/custom-init
```

---

## Best Practices from the Repository

### 1. Keep CLAUDE.md Updated

```markdown
# After adding new patterns
## New Pattern: [Name]

Description and example...
```

### 2. Use Specific Commands

```bash
# Instead of explaining what you want
/commit  # Quick commit
/test    # Generate tests
/issue   # Create issue
```

### 3. Leverage Agents

```bash
# Invoke specific agent for focused help
@code-review Review this PR
@security Audit the auth module
@performance Optimize this function
```

### 4. Document Decisions

```markdown
# In CLAUDE.md
## Architecture Decisions

### ADR-001: Use PostgreSQL
- Context: Need relational database
- Decision: PostgreSQL for JSON support
- Consequences: More complex setup
```

---

## Command Creation Guide

### Basic Structure

```markdown
# .claude/commands/my-command.md

## Description
What this command does

## Steps
1. First action
2. Second action
3. Output format

## Examples
User: /my-command arg1
Claude: [Expected response]
```

### Best Practices

1. **Be specific** - Clear instructions
2. **Use steps** - Numbered sequence
3. **Include examples** - Show input/output
4. **Handle errors** - What to do when fails

---

## Agent Creation Guide

### Template

```markdown
# .claude/agents/my-agent.md

## Role
You are a [specialist type].

## Focus Areas
1. Primary focus
2. Secondary focus
3. Constraints

## Approach
- Step 1
- Step 2
- Step 3

## Output Format
How to structure responses
```

### Tips

1. **Single responsibility** - One area of expertise
2. **Clear boundaries** - What agent does NOT do
3. **Consistent format** - Predictable output
4. **Actionable advice** - Specific recommendations

---

## Integration with Other Tools

### With Aider

```bash
# Use commands in Aider context
aider --read .claude/commands/commit.md
```

### With GitHub Copilot

```
# Reference CLAUDE.md patterns
# @workspace follows CLAUDE.md standards
```

### With CI/CD

```yaml
# Use Claude for PR checks
- name: Claude Review
  run: claude "/reviewpr" > review.md
```

---

## Comparison to Similar Repositories

| Repository | Focus | Commands | Agents |
|------------|-------|----------|--------|
| **awattar/claude-code-best-practices** | Complete workflows | 5 | 10 |
| **Awesome Claude Code** | Curated resources | - | - |
| **Claude Cookbooks** | API patterns | - | - |

### Unique Value

1. **Ready-to-use commands** - Copy and customize
2. **Specialized agents** - Task-specific help
3. **GitHub integration** - End-to-end workflow
4. **CLAUDE.md template** - Project setup

---

## Troubleshooting

### Commands Not Working

```bash
# Verify command file exists
ls .claude/commands/

# Check file format (must be .md)
cat .claude/commands/commit.md
```

### Agent Not Responding

```bash
# Invoke with full path
@.claude/agents/code-review

# Or add to prompts
"Acting as the code-review agent..."
```

### CLAUDE.md Not Loaded

```bash
# Must be in project root
ls CLAUDE.md

# Or in .claude directory
ls .claude/CLAUDE.md
```

---

## Resources

- **Repository:** https://github.com/awattar/claude-code-best-practices
- **Claude Code Docs:** https://docs.anthropic.com/claude-code
- **GitHub Flow:** https://docs.github.com/en/get-started/quickstart/github-flow
- **Conventional Commits:** https://www.conventionalcommits.org

---

*Claude Code Best Practices provides the building blocks for professional Claude Code workflows. Whether you're setting up a new project or optimizing an existing one, these commands and agents accelerate development.*
