claude-code-best-practices

# Claude Code Best Practices - Project Guide

## Overview

This is a documentation repository focusing on Claude Code best practices, patterns, and real-world usage examples. The project serves as a comprehensive guide for developers looking to integrate Claude Code into their terminal-based coding workflows effectively.

### Project Type

Documentation / Knowledge Repository with Custom Claude Code Commands.

### Quick Start

```bash
# Clone the repository
git clone <repository-url>
cd claude-code-best-practices

# Read the main documentation
cat README.md

# View available custom commands
ls .claude/commands/

# Get help with custom commands
/help-commands     # View all available commands and usage

# Use custom commands (examples)
/commit            # Create conventional commits
/custom-init       # Initialize CLAUDE.md for any project
/issue <number>    # Work on GitHub issues
/reviewpr <number> # Review pull requests
/test <scope>      # Run and improve tests
```

## Architecture

### Project Structure

```
claude-code-best-practices/
├── LICENSE                      # MIT License
├── README.md                    # Main documentation with best practices
├── .gitmessage                  # Git commit message template
├── .github/                     # GitHub templates and workflows
│   ├── pull_request_template.md # Standardized PR template
│   └── COMMIT_CONVENTION.md     # Commit best practices guide
└── .claude/                     # Claude Code configuration
    ├── settings.json            # Permissions + hooks (project scope)
    ├── commands/                # Custom slash commands
    │   ├── commit.md            # Conventional commit helper
    │   ├── custom-init.md       # CLAUDE.md generation command
    │   ├── help-commands.md     # Command help and usage guide
    │   ├── issue.md             # GitHub issue workflow
    │   ├── reviewpr.md          # Pull request review tool
    │   └── test.md              # Test suite management
    ├── agents/                  # Specialized AI agents
    │   ├── general-backend-developer.md
    │   ├── general-code-quality-debugger.md
    │   ├── general-devops.md
    │   ├── general-frontend-developer.md
    │   ├── general-fullstack-developer.md
    │   ├── general-pm.md
    │   ├── general-qa.md
    │   ├── general-solution-architect.md
    │   ├── general-technical-project-lead.md
    │   └── general-technical-writer.md
    └── skills/                  # Model-invoked skills
        └── conventional-commits/
            └── SKILL.md         # Auto-enforces commit convention
```

### Content Organization

The project follows a documentation-first approach with integrated tooling:

- **`README.md`**: Primary content with comprehensive Claude Code guidance.
- **`LICENSE`**: MIT license for open-source usage.
- **`.gitmessage`**: Git commit message template with conventional format.
- **`.github/`**: GitHub templates and workflow configurations.
- **`.claude/settings.json`**: Project-scoped permissions and hooks.
- **`.claude/commands/`**: Custom workflow commands for Claude Code users.
- **`.claude/agents/`**: Specialized AI agents that enhance command capabilities.
- **`.claude/skills/`**: Model-invoked skills that apply conventions automatically.

## Technology Stack

### Core Technologies

- **Documentation**: Markdown.
- **Version Control**: Git.
- **Claude Code**: Custom commands, workflows, and specialized AI agents.

### Dependencies

- **GitHub CLI (`gh`)**: Required for issue and PR management commands.
- **Browser Automation**: Puppeteer/Playwright/Selenium (project-dependent).
- **Testing Frameworks**: Varies by project (Jest, pytest, RSpec, etc.).

## Key Features

### 1. Comprehensive Best Practices Guide

- **Location**: `README.md:1-76`
- **Purpose**: Practical guidance for Claude Code usage.
- **Sections**: 
  - Setup tips and environment configuration.
  - Prompt design and context handling.
  - Testing and debugging workflows.
  - Git integration patterns.
  - Hooks and automation.
  - Safety and control measures.

### 2. Custom Claude Code Commands

- **Location**: `.claude/commands/`
- **Purpose**: Streamline common development workflows.
- **Help**: Use `/help-commands` - @.claude/commands/help-commands.md for detailed usage information.

#### Available Commands

- `/custom-init` - `CLAUDE.md` Generator.
- `/commit` - Conventional Commits.
- `/help-commands` - Command Help and Usage Guide.
- `/issue` - GitHub Issue Workflow.
- `/reviewpr` - Pull Request Review.
- `/test` - Test Suite Management.

For detailed information about each command, including usage examples, features, and best practices, use `/help-commands` - @.claude/commands/.

#### Template Integration

Commands now reference standardized templates:

- **Commit messages**: @.gitmessage - Four format variants (single-line, multiline, parent/child, post-review).
- **Pull requests**: @.github/pull_request_template.md - Structured PR format.
- **Commit conventions**: @.github/COMMIT_CONVENTION.md - Best practices guide.

#### Agent Integration

Commands leverage specialized AI agents to provide expert-level capabilities across different domains. The repository defines 10 custom agents in `.claude/agents/`; commands also use Claude Code's built-in **general-purpose** agent (not defined in this repo) for complex multi-step analysis and file searching.

**Core Agents:**
- **general-solution-architect** - Architecture analysis, technology stack decisions, and design patterns
- **general-technical-writer** - Documentation creation, formatting, and content organization
- **general-pm** - Issue creation, prioritization, progress tracking, and lifecycle management

**Development Agents:**
- **general-fullstack-developer** - End-to-end feature implementation spanning multiple layers
- **general-backend-developer** - API development, database patterns, and server-side logic
- **general-frontend-developer** - UI/UX implementation, component patterns, and browser automation
- **general-devops** - Infrastructure automation, CI/CD, container orchestration, and reliability engineering

**Quality Assurance Agents:**
- **general-qa** - Testing strategies, automation, and comprehensive validation
- **general-code-quality-debugger** - Code review, debugging, and quality assessment
- **general-technical-project-lead** - Security assessments, strategic decisions, and architectural review

**Agent Usage by Command:**
- **`/custom-init`**: solution-architect, backend-developer, devops, qa, code-quality-debugger, technical-writer (general-purpose as fallback)
- **`/commit`**: code-quality-debugger, technical-project-lead
- **`/issue`**: fullstack-developer, backend-developer, frontend-developer, qa, general-purpose
- **`/reviewpr`**: code-quality-debugger, technical-project-lead, qa, solution-architect
- **`/test`**: qa, code-quality-debugger, backend-developer, frontend-developer

### 3. Curated Resource Links

- **Location**: `README.md:38-76`
- **Content**: Links to official documentation, tutorials, and community resources.
- **Categories**:
  - Official Claude Code documentation.
  - Community tutorials and workflows.
  - Related tools and integrations.

## Command Prerequisites

### GitHub CLI Setup

```bash
# Install GitHub CLI
gh --version

# Authenticate
gh auth login

# Verify access
gh repo view
```

### Git Template Configuration

```bash
# Set commit message template
git config commit.template .gitmessage

# Verify template is set
git config commit.template
```

### Browser Automation

- **Puppeteer**: For Node.js projects.
- **Playwright**: Cross-browser testing.
- **Selenium**: Legacy browser automation.
- **Cypress**: Modern E2E testing.

## Project Context

### Purpose

Educational resource and practical tooling for Claude Code adoption in development workflows.

### Target Audience

- Developers new to Claude Code.
- Teams implementing AI-assisted coding workflows.
- Contributors to Claude Code ecosystem.

### Maintenance

- Documentation updates as Claude Code evolves.
- Command improvements based on user feedback.
- Integration testing for workflow commands.

## Related Resources

### Official Documentation

- Claude Code CLI reference.
- Model overview and capabilities.
- Integration guides for various IDEs.

### Community Resources

- YouTube tutorials and walkthroughs.
- Personal workflow examples.
- Automation and hooks implementations.

## Notes for AI Assistants

### When working with this repository:

1. **Content Focus**: Documentation + custom Claude Code commands + specialized AI agents + skills + project configuration.
2. **Primary Files**: `README.md`, `.claude/commands/*.md`, `.claude/agents/*.md`, `.claude/skills/**/SKILL.md`, and `.claude/settings.json`.
3. **Template Files**: Reference `.gitmessage` and `.github/` templates using `@` prefix.
4. **Command Usage**: Test commands in appropriate project contexts.
5. **Agent Integration**: Leverage specialized agents for domain-specific expertise.
6. **Update Patterns**: Maintain consistency between documentation, commands, templates, and agents.
7. **Version Control**: Track content, command, and agent changes.

### Common Tasks:

- Updating best practices based on new Claude Code features.
- Improving custom command workflows and agent integration.
- Adding new command templates and agent definitions.
- Testing command effectiveness across different project types.
- Maintaining consistency between documentation, commands, and agents.

### Command Development:

- **Format**: Use markdown with clear usage sections.
- **Structure**: Include usage, purpose, and step-by-step workflows.
- **Integration**: Ensure commands work with GitHub CLI, project tools, and specialized agents.
- **Testing**: Validate commands in real project environments.
- **Template References**: Use `@` prefix to reference template files for Claude Code context.
- **Agent Coordination**: Leverage appropriate specialized agents for domain expertise.

#### Recent Template Restructuring

The project recently underwent template restructuring:

- **Moved specifications**: Detailed format specs moved from command files to GitHub templates.
- **Template references**: Commands now use `@` prefix (e.g., `@.gitmessage`, `@.github/pull_request_template.md`).
- **Post-review format**: Added specific format for post-review commit fixes.
- **Centralized conventions**: Commit best practices consolidated in `@.github/COMMIT_CONVENTION.md`.