AI Coding Project Boilerplate for Claude Code 🤖

Read this in other languages: 日本語

Agentic coding starter kit and workflow boilerplate for Claude Code — Build production-ready TypeScript projects with sub-agents, context engineering, and zero context exhaustion.

⚡ This boilerplate is for developers who want to:

• Build TypeScript projects faster with AI-driven workflows
• Avoid context exhaustion in long AI coding sessions
• Standardize team workflows with specialized AI agents

📖 Table of Contents

1. Quick Start (3 Steps)
2. Updating Existing Projects
3. Beyond Vibe Coding: Why Sub Agents?
4. Slash Commands
5. Customizing Skills
6. Skills System
7. Built with This Boilerplate
8. Documentation & Guides
9. Development Workflow
10. Project Structure
11. Package Manager Configuration
12. Multilingual Support
13. FAQ

⚡ Quick Start (3 Steps)

# 1. Create your project
npx create-ai-project my-project

# 2. Install dependencies (automatic)
cd my-project && npm install

# 3. Launch Claude Code and configure
claude                    # Launch Claude Code
/project-inject          # Set up project prerequisites (read every session by AI)
/implement <your feature> # Start building!

💡 First time? Check the Quick Start Guide for detailed setup instructions

🔄 Updating Existing Projects

Keep your project's agent definitions, commands, skills, and AI rules up to date. Run from your project's root directory:

# Preview changes without applying
npx create-ai-project update --dry-run

# Apply updates
npx create-ai-project update

How It Works

When you run npx create-ai-project update, the CLI:

1. Checks your project's .create-ai-project.json manifest for the current version
2. Compares it with the latest package version
3. Shows the CHANGELOG for review
4. Replaces managed files with the latest versions
5. Regenerates active directories for your language setting

What Gets Updated

Target	Path
Agent definitions	.claude/agents-{lang}/
Command definitions	.claude/commands-{lang}/
Skill definitions	.claude/skills-{lang}/
AI rules	CLAUDE.{lang}.md

Your source code (src/), package.json, and other project files are never touched.

Protecting Customized Files

If you've customized a file and don't want it overwritten:

# Add to ignore list
npx create-ai-project update --ignore skills project-context
npx create-ai-project update --ignore agents task-executor
npx create-ai-project update --ignore commands implement
npx create-ai-project update --ignore CLAUDE.md

# Remove from ignore list
npx create-ai-project update --unignore skills project-context

Ignored files are preserved during updates. Note that ignoring files may cause version mismatch with other updated components.

First Run on Existing Projects

If your project was created before the update feature, just run npx create-ai-project update from your project's root directory. It will automatically initialize the manifest by detecting your language from .claudelang.

🚀 Beyond Vibe Coding: Why Sub Agents?

As teams move beyond vibe coding, agentic coding — delegating structured workflows to specialized AI agents — is gaining traction as a practical approach. This boilerplate implements that approach with Claude Code sub-agents:

Traditional AI coding struggles with:

• ❌ Losing context in long sessions
• ❌ Declining code quality over time
• ❌ Frequent session restarts for large tasks

Sub agents solve this through context engineering:

• ✅ Splitting work into specialized roles (design, implementation, review)
• ✅ Each agent gets fresh, focused context — no exhaustion
• ✅ Handling large projects without degradation

This works because Claude Code's sub-agent mechanism runs each agent in its own context window. The parent session delegates tasks, and each sub-agent starts with a clean, focused context. Quality checks (lint, type check, test, build) run locally before each commit — not in CI. The feedback loop stays fast, and code is already verified when it's pushed.

👉 Learn more about Sub Agents (Anthropic docs)

📸 Demo

Sub agents working together on a TypeScript project

📝 Slash Commands

Essential commands for Claude Code:

Command	Purpose	When to Use
/implement	End-to-end feature development	New features
/task	Single task with skill-based precision	Bug fixes, small changes
/design	Create design docs only	Architecture planning
/plan	Create work plan from design	After design approval
/prepare-implementation	Get the plan ready for /build (verify readiness and resolve gaps)	Before /build to ensure the plan is implementable
/build	Execute from existing plan	Resume work
/review	Check code compliance	Post-implementation
/diagnose	Problem diagnosis workflow	Debugging, troubleshooting
/reverse-engineer	Generate PRD/Design Docs from code	Legacy system documentation
/create-skill	Create a new skill through interactive dialog	Adding project-specific rules
/refine-skill	Modify an existing skill with quality review	Improving skill accuracy

Frontend equivalents (/front-design for UI Spec + Design Doc, /front-build, /front-review, /front-plan) and utility commands (/add-integration-tests, /update-doc) are also available.

Full command reference →

🌱 Customizing Skills

This boilerplate ships with general-purpose skills that work out of the box. But skills reach their full potential when you tailor them to your project — your coding conventions, domain constraints, and team decisions.

Think of the included skills as a baseline. The next step is making them yours:

• /project-inject — Capture project-specific prerequisites (run once, referenced every session)
• /create-skill — Create a new skill through interactive dialog
• /refine-skill — Improve an existing skill with optimization review

For principles and best practices on writing effective skills, see the Skills Editing Guide.

Validating Skill Effectiveness

Creating a skill is one thing — knowing whether it actually improves agent behavior is another. Skills interact with each other and with project context, so the only reliable way to know is to run with and without the skill and compare results.

rashomon is a Claude Code plugin for this. Use it when you want evidence, not intuition, that a skill change made things better.

🎨 Skills System

This boilerplate provides the principles used in agentic implementation workflows as skills, making them available for reference in everyday tasks as needed.

Applied Skills

Skill	Purpose
coding-standards	Universal coding principles, anti-patterns, debugging
typescript-rules	TypeScript type safety, async patterns, refactoring
typescript-testing	Vitest, TDD, coverage requirements
documentation-criteria	PRD, ADR, Design Doc, UI Spec standards
technical-spec	Architecture, environment, build commands
implementation-approach	Strategy patterns, task decomposition
integration-e2e-testing	Integration tests and two-lane E2E (fixture-e2e / service-integration-e2e), ROI-based selection, journey definition
frontend-typescript-rules	React component design, Props-driven patterns
frontend-typescript-testing	React Testing Library, MSW, Playwright E2E (fixture and service-integration patterns)
frontend-technical-spec	React architecture, environment, data flow
llm-friendly-context	Clarity of LLM-facing output — prompts, handoffs, and generated artifacts
project-context	Project-specific prerequisites for AI accuracy (set via /project-inject)

👉 Learn how Skills work (Claude Code docs)

🎯 Built with This Boilerplate

⏱️ Time Comparison

• Without this boilerplate: ~1 week for setup + infrastructure
• With this boilerplate: ~2 days to production-ready application

Success Stories

Sub Agents MCP Server — MCP server enabling Claude Code/Cursor CLI as sub agents ⏱️ Initial development in 2 days — test code makes up ~90% of the codebase, now in production

MCP Image Generator — AI image generation via Gemini API ⏱️ Initial development in 1.5 days — complete creative tool with multi-image blending and character consistency

Both were built using the default /implement workflow — no manual agent orchestration needed.

See these projects: sub-agents-mcp ・ mcp-image

📚 Documentation & Guides

• Quick Start Guide - Get running in 5 minutes
• Use Cases & Commands - Daily workflow reference
• Skills Editing Guide - Add library docs, team rules, and project-specific knowledge for AI
• Design Philosophy - Why this approach works

🤖 Claude Code Workflow

graph LR
    A[Requirements] --> B[Scale Detection]
    B -->|Small| C[Direct Implementation]
    B -->|Medium| D[Design → Implementation]
    B -->|Large| E[PRD → Design → Implementation]

    C --> F[Quality Check → Commit]
    D --> F
    E --> F

Reverse Engineering Workflow

Generate PRD and Design Docs from existing code:

graph TB
    subgraph Phase1[Phase 1: PRD Generation]
        SD[scope-discoverer] --> PRD[prd-creator]
        PRD --> CV1[code-verifier]
        CV1 --> DR1[document-reviewer]
        DR1 -->|Revision needed| PRD
        DR1 -->|Approved| NEXT1[Next unit]
    end

    subgraph Phase2[Phase 2: Design Doc Generation]
        TD[technical-designer] --> CV2[code-verifier]
        CV2 --> DR2[document-reviewer]
        DR2 -->|Revision needed| TD
        DR2 -->|Approved| NEXT2[Next unit]
    end

    NEXT1 -->|"All PRDs Approved (reuse scope)"| TD
    NEXT2 --> REPORT[Final report]

How It Works

1. Requirement Analysis: /implement command analyzes task scale
2. Document Generation: Creates necessary docs (PRD, UI Spec, Design Doc, Work Plan)
3. Task Execution: Specialized agents handle each phase
4. Quality Assurance: Automatic testing, type checking, and fixes
5. Commit & Continue: Clean commits for each completed task

📂 Project Structure

ai-coding-project-boilerplate/
├── .claude/               # AI agent configurations
│   ├── agents/           # Specialized sub-agent definitions
│   ├── comman