Claude Code Boilerplate

A comprehensive boilerplate template for building professional software projects with CLI Coding Agents (Claude Code and Open Code). This template provides a complete development environment with AI-powered agent orchestration, automated workflows, and intelligent project management.

What is Claude Code?

Claude Code is Anthropic's official CLI tool that brings AI-powered development assistance directly to your terminal. It enables natural language interaction with your codebase and provides intelligent automation for common development tasks.

• Claude Code
• Docs

Open Code CLI Coding Agents extend Claude Code with specialized AI agents that handle specific aspects of software development - from planning and research to testing and documentation. This creates a collaborative AI development team that works alongside human developers.

• Open Code
• Docs

Related Projects & Directories

• claudekit - Website of ClaudeKit
  • Directory: ../claudekit
  • Repo: https://github.com/claudekit/claudekit
• claudekit-marketing - Marketing Kit repository
  • Directory: ../claudekit-marketing
  • Repo: https://github.com/claudekit/claudekit-marketing
• claudekit-cli - CLI tool for quick project setup
  • Directory: ../claudekit-cli
  • Repo: https://github.com/mrgoonie/claudekit-cli
• claudekit-docs - Public documentation repository: https://docs.claudekit.cc
  • Directory: ../claudekit-docs
  • Repo: https://github.com/claudekit/claudekit-docs

Key Benefits

🚀 Accelerated Development

• AI-Powered Planning: Automated technical planning and architecture design
• Intelligent Code Generation: Context-aware code creation and modification
• Automated Testing: Comprehensive test generation and execution
• Smart Documentation: Synchronized docs that evolve with your code

🎯 Enhanced Quality

• Multi-Agent Code Review: Specialized agents for security, performance, and standards
• Automated Quality Assurance: Continuous testing and validation
• Best Practices Enforcement: Built-in adherence to coding standards
• Security-First Development: Proactive security analysis and recommendations

🏗️ Structured Workflow

• Agent Orchestration: Coordinated AI agents working in parallel and sequential workflows
• Task Management: Automated project tracking and progress monitoring
• Documentation Sync: Always up-to-date technical documentation
• Clean Git Workflow: Professional commit messages and branch management

Documentation

📚 Core Documentation

• Project Overview & PDR - Comprehensive project overview, goals, features, and product development requirements
• Codebase Summary - High-level overview of project structure, technologies, and components
• Code Standards - Coding standards, naming conventions, and best practices
• System Architecture - Detailed architecture documentation, component interactions, and data flow
• Commands Reference - Complete guide to all available slash commands

📖 Additional Resources

• CLAUDE.md - Development instructions and workflows for AI agents
• CHANGELOG.md - Version history and release notes
• Windows Statusline Support - Windows compatibility guide for Claude Code statusline
• Statusline Architecture - Technical documentation for statusline implementation

Quick Start

Prerequisites

• Claude Code installed and configured
• Git for version control
• Node.js 18+ (or your preferred runtime)
• Operating Systems: macOS 10.15+, Ubuntu 20.04+/Debian 10+, or Windows 10+ (with WSL 1, WSL 2, or Git for Windows)
• Hardware: 4GB+ RAM

Setup your new project with ClaudeKit

1. Install ClaudeKit Engineer (includes CLI):

   npm install -g @doananh234/claudekit-engineer

2. Create your new project with ClaudeKit framework:

   ck new --dir my-project --kit engineer

   Note: If you want to use the kit with your existing project:

   cd /path/to/project
   ck update --kit engineer

   Alternative: Install locally in your project:

   npm install @doananh234/claudekit-engineer
   npx ck new --dir my-project --kit engineer

3. Start development:

   # Begin with Claude Code
   claude
   # [YOLO mode - not recommended]
   # claude --dangerously-skip-permissions
   
   # now you can use these specific commands
   /plan "implement user authentication"
   /cook "add database integration"

📖 Learn more from our docs: https://docs.claudekit.cc

Project Structure

├── .claude/                 # Claude Code configuration
│   ├── agents/             # Claude Code agents
│   ├── commands/           # Claude Code commands
│   ├── hooks/              # Claude Code hooks
│   ├── skills/             # Claude Code skills
│   ├── CLAUDE.md           # Global development instructions
│   └── send-discord.sh     # Notification script
├── .opencode/              # Open Code CLI agent definitions
│   ├── agent/              # Specialized agent configurations
│   │   ├── planner.md      # Technical planning agent
│   │   ├── researcher.md   # Research and analysis agent
│   │   ├── tester.md       # Testing and validation agent
│   │   ├── debugger.md     # Issue analysis agent
│   │   ├── code-reviewer.md# Code quality agent
│   │   ├── docs-manager.md # Documentation agent
│   │   ├── git-manager.md  # Version control agent
│   │   └── project-manager.md # Progress tracking agent
│   └── command/            # Custom command definitions
├── docs/                   # Project documentation
│   ├── codebase-summary.md # Auto-generated codebase overview
│   ├── code-standards.md   # Development standards
│   ├── project-overview-pdr.md # Product requirements
│   └── development-roadmap.md  # Project roadmap
├── plans/                  # Implementation plans and reports
│   ├── templates/          # Plan templates
│   └── reports/            # Agent-to-agent communication
├── CLAUDE.md              # Project-specific Claude instructions
├── AGENTS.md              # Agent coordination guidelines
└── README.md              # This file

The AI Agent Team

This boilerplate includes specialized AI agents that work together to deliver high-quality software:

🎯 Core Development Agents

Planner Agent

• Researches technical approaches and best practices
• Creates comprehensive implementation plans
• Analyzes architectural trade-offs
• Spawns multiple researcher agents for parallel investigation

Researcher Agent

• Investigates specific technologies and frameworks
• Analyzes existing solutions and patterns
• Provides technical recommendations
• Supports the planner with detailed findings

Tester Agent

• Generates comprehensive test suites
• Validates functionality and performance
• Ensures cross-platform compatibility
• Reports on test coverage and quality metrics

🔍 Quality Assurance Agents

Code Reviewer Agent

• Performs automated code quality analysis
• Enforces coding standards and conventions
• Identifies security vulnerabilities
• Provides improvement recommendations

Debugger Agent

• Analyzes application logs and error reports
• Diagnoses performance bottlenecks
• Investigates CI/CD pipeline issues
• Provides root cause analysis

📚 Documentation & Management Agents

Docs Manager Agent

• Maintains synchronized technical documentation
• Updates API documentation automatically
• Ensures documentation accuracy
• Manages codebase summaries

Git Manager Agent

• Creates clean, conventional commit messages
• Manages branching and merge strategies
• Handles version control workflows
• Ensures professional git history

Project Manager Agent

• Tracks development progress and milestones
• Updates project roadmaps and timelines
• Manages task completion verification
• Maintains project health metrics

Agent Orchestration Patterns

Sequential Chaining

Use when tasks have dependencies:

# Planning → Implementation → Testing → Review
/plan "implement user dashboard"
# Wait for plan completion, then:
/cook "follow the implementation plan"
# After implementation:
/test "validate dashboard functionality"
# Finally:
/review "ensure code quality standards"

Parallel Execution

Use for independent tasks:

# Multiple researchers exploring different approaches
planner agent spawns:
- researcher (database options)
- researcher (authentication methods)
- researcher (UI frameworks)
# All report back to planner simultaneously

Context Management

• Agents communicate through file system reports
• Context is preserved between agent handoffs
• Fresh context prevents conversation degradation
• Essential information is documented in markdown

Development Workflow

1. Feature Development

# Start with planning
/plan "add real-time notifications"

# Research phase (automatic)
# Multiple researcher agents investigate approaches

# Implementation
/cook "implement notification system"

# Quality assurance
/test
/review

# Documentation update
/docs

# Project tracking
/watzup  # Check project status

2. Bug Fixing

# Analyze the issue
/debug "investigate login failures"

# Create fix plan
/plan "resolve authentication bug"

# Implement solution
/fix "authentication issue"

# Validate fix
/test

3. Documentation Management

# Update documentation
/docs

# Generate codebase summary
repomix  # Creates ./docs/codebase-summary.md

# Review project status
/watzup

Configuration Files

CLAUDE.md

Project-specific instructions for Claude Code. Customize this file to define:

• Project architecture guidelines
• Development standards and conventions
• Agent coordination protocols
• Specific workflows for your project

.opencode/agent/*.md

Individual agent configurations defining:

• Agent expertise and responsibilities
• Interaction patterns
• Output formats
• Quality standards

plans/templates/*.md

Reusable templates for:

• Feature implementation plans
• Bug fix procedures
• Refactoring strategies
• Architecture decisions

Gemini Skills Configuration

This project includes several Gemini-powered skills that require a Google Gemini API key:

• gemini-audio - Audio analysis and speech generation
• gemini-video-understanding - Video analysis and understanding
• gemini-document-processing - PDF document processing
• gemini-image-gen - AI image generation
• gemini-vision - Image analysis and vision capabilities

API Key Setup

The Gemini skills check for GEMINI_API_KEY in the following order (priority from highest to lowest):

1. Environment Variable (Recommended for development)

   export GEMINI_API_KEY='your-api-key-here'

2. Project Root .env (Recommended for project-specific keys)

   # Create .env in project root
   echo 'GEMINI_API_KEY=your-api-key-here' > .env

3. .claude/.env (For Claude-specific configuration)

   # Copy example and edit
   cp .claude/.env.example .claude/.env
   # Then edit .claude/.env and set your API key

4. .claude/skills/.env (For shared skills configuration)

   # Copy example and edit
   cp .claude/skills/.env.example .claude/skills/.env
   # Then edit .claude/skills/.env and set your API key

5. Individual Skill Directory .env (For skill-specific keys)

   # Example for gemini-audio skill
   cp .claude/skills/gemini-audio/.env.example .claude/skills/gemini-audio/.env
   # Then edit and set your API key

Getting Your API Key

Get your free Gemini API key at: https://aistudio.google.com/apikey

Vertex AI Support

To use Vertex AI instead of Google AI Studio:

# Enable Vertex AI
export GEMINI_USE_VERTEX=true
export VERTEX_PROJECT_ID=your-gcp-project-id
export VERTEX_LOCATION=us-central1  # Optional, defaults to us-central1

Or in .env file:

GEMINI_USE_VERTEX=true
VERTEX_PROJECT_ID=your-gcp-project-id
VERTEX_LOCATION=us-central1

Usage Examples

# Audio analysis
claude "Analyze this audio file and summarize the key points: audio.mp3"

# Video understanding
claude "Describe what happens in this video: video.mp4"

# Document processing
claude "Extract all tables from this PDF: document.pdf"

# Image generation
claude "Generate an image of a serene mountain landscape"

# Image analysis
claude "What objects are in this image: photo.jpg"

Model Context Protocol (MCP)

✍️ Please read my technical blog article about MCP here.

Pre-requisites

In ClaudeKit, you need to setup the MCP servers in .claude/.mcp.json file.

Copy the example file:

mv .claude/.mcp.json.example .claude/.mcp.json

Then add your MCP servers, below are some examples:

Context7

{
   "mcpServers": {
      "context7": {
         "command": "npx",
         "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"],
      }
   }
}

Human MCP

{
   "mcpServers": {
      "human": {
         "command": "npx",
         "args": ["@goonnguyen/human-mcp@latest"],
         "env": { "GOOGLE_GEMINI_API_KEY": "YOUR_API_KEY" }
      }
   }
}

Chrome DevTools MCP

{
   "mcpServers": {
      "chrome-devtools": {
         "command": "npx",
         "args": ["-y", "chrome-devtools-mcp@latest"]
      }
   }
}

Best Practices

Development Principles

• YANGI: You Aren't Gonna Need It - avoid over-engineering
• KISS: Keep It Simple, Stupid - prefer simple solutions
• DRY: Don't Repeat Yourself - eliminate code duplication

Code Quality

• All code changes go through automated review
• Comprehensive testing is mandatory
• Security considerations are built-in
• Performance optimization is continuous

Documentation

• Documentation evolves with code changes
• API docs are automatically updated
• Architecture decisions are recorded
• Codebase summaries are regularly refreshed

Git Workflow

• Clean, conventional commit messages
• Professional git history
• No AI attribution in commits
• Focused, atomic commits

Usage Examples

Starting a New Feature

# Research and plan
claude "I need to implement user authentication with OAuth2"
# Planner agent creates comprehensive plan

# Follow the plan
claude "Implement the authentication plan"
# Implementation follows the detailed plan

# Ensure quality
claude "Review and test the authentication system"
# Testing and code review agents validate the implementation

Debugging Issues

# Investigate problem
claude "Debug the slow database queries"
# Debugger agent analyzes logs and performance

# Create solution
claude "Optimize the identified query performance issues"
# Implementation follows debugging recommendations

# Validate fix
claude "Test query performance improvements"
# Tester agent validates the optimization

Project Maintenance

# Check project health
claude "What's the current project status?"
# Project manager provides comprehensive status

# Update documentation
claude "Sync documentation with recent changes"
# Docs manager updates all relevant documentation

# Plan next sprint
claude "Plan the next development phase"
# Planner creates detailed roadmap for upcoming work

Advanced Features

Multi-Project Support

• Manage multiple repositories simultaneously
• Shared agent configurations across projects
• Consistent development patterns

Custom Agent Creation

• Define project-specific agents
• Extend existing agent capabilities
• Create domain-specific expertise

Integration Capabilities

• Discord notifications for project updates
• GitHub Actions integration
• CI/CD pipeline enhancement

Customization Guide

1. Project Setup

• Update CLAUDE.md with your project specifics
• Modify agent configurations in .opencode/agent/
• Customize plan templates in plans/templates/

2. Agent Specialization

• Add domain-specific knowledge to agents
• Create custom agents for unique requirements
• Configure agent interaction patterns

3. Workflow Optimization

• Define project-specific commands
• Create shortcuts for common tasks
• Establish team coding standards

Contributing

1. Fork this repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Follow the agent orchestration workflow
4. Ensure all tests pass and documentation is updated
5. Create a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Learn More

Claude Code Resources

• Claude Code Documentation
• Open Code CLI Documentation
• Agent Development Guide

Community

• Claude Code Community
• Discussion Forum
• Example Projects

Support

• Issue Tracker
• Feature Requests
• Documentation

Start building with AI-powered development today! This boilerplate provides everything you need to create professional software with intelligent agent assistance.