AI Coding Project Boilerplate 🤖

Read this in other languages: 日本語

⚡ This boilerplate is for developers who want to:

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

📖 Table of Contents

1. Quick Start (3 Steps)
2. Why Sub Agents?
3. Real Projects & Results
4. Documentation & Guides
5. Slash Commands
6. Development Workflow
7. Project Structure
8. Development Commands
9. Rules & Quality Assurance
10. Multilingual Support
11. FAQ

Which one should you use?

• Use this Boilerplate if you want to maximize precision with TypeScript × Sub-agent setup optimized for Claude Code.
• Use claude-code-workflows if you're on Claude Code and want to start with any project in 2 commands and language-agnostic workflows.
• Use Agentic Code if you want zero-config, tool-agnostic workflows without language restrictions (Codex CLI/Cursor/Aider etc.).

⚡ Quick Start (3 Steps)

# 1. Create your project (30 seconds)
npx github:shinpr/ai-coding-project-boilerplate my-project

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

# 3. Launch Claude Code and configure
claude                    # Launch Claude Code
/project-inject          # Configure project context
/implement <your feature> # Start building!

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

🚀 Why 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 by:

• ✅ Splitting work into specialized roles (design, implementation, review)
• ✅ Keeping context fresh and quality consistent
• ✅ Handling large projects without degradation

Each agent focuses on one thing and does it well. No context exhaustion, no quality drop.

👉 Learn more about Sub Agents (Anthropic docs)

📸 Demo

Sub agents working together to build a production-ready TypeScript project

🎯 Real-World Results

⏱️ 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

What: MCP server enabling Claude Code/Cursor CLI as sub agents
Time: 2 days → 30 TypeScript files with full test coverage
Result: Production-deployed, 3-minute setup

MCP Image Generator

What: AI image generation via Gemini API
Time: 1.5 days → Complete creative tool with advanced features
Result: Multi-image blending, character consistency, one-command integration

💡 Key Insight: Proper rules + sub agents = production-quality code at AI speed

📚 Documentation & Guides

• Quick Start Guide - Get running in 5 minutes
• Use Cases & Commands - Daily workflow reference
• Rule Editing Guide - Customize for your project
• Design Philosophy - Why it works (770K tokens without exhaustion)

📝 Slash Commands

Essential commands for Claude Code:

Command	Purpose	When to Use
/implement	End-to-end feature development	New features (Backend)
/task	Single task with rule precision	Bug fixes, small changes
/design	Create design docs only	Architecture planning (Backend)
/plan	Create work plan from design	After design approval (Backend)
/build	Execute from existing plan	Resume work (Backend)
/review	Check code compliance	Post-implementation
/front-design	Create frontend design docs	React/Vite architecture planning
/front-plan	Create frontend work plan	After frontend design approval
/front-build	Execute frontend implementation	React component development

Full command reference →

🤖 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

Loading

How It Works

1. Requirement Analysis: /implement command analyzes task scale
2. Document Generation: Creates necessary docs (PRD, 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
│   └── commands/         # Slash command definitions
├── docs/
│   ├── rules/            # Development rules & patterns
│   ├── guides/           # User documentation
│   ├── adr/              # Architecture decisions
│   ├── design/           # Design documents
│   └── prd/              # Product requirements
├── src/                  # Your source code
├── scripts/              # Utility scripts
└── CLAUDE.md             # Claude Code configuration

🛠️ Development Commands

Core Scripts

# Backend
npm run dev              # Start development server (Backend)
npm run build            # Production build (Backend, default)
npm run build:backend    # Production build (Backend, explicit)

# Frontend
npm run dev:frontend     # Start Vite dev server
npm run build:frontend   # Production build with Vite
npm run preview          # Preview production build

# Common
npm run test[:watch]     # Run tests (with optional watch mode)
npm run type-check       # TypeScript type check only
npm run check:all        # Complete check: types + lint + test + build

Quality Tools

npm run lint             # Lint check
npm run format           # Auto-format code
npm run check:deps       # Check circular dependencies

📋 Development Rules & Quality Assurance

Why Rules Matter

Rules guide AI to produce consistent, high-quality code. Without them, AI output varies wildly.
With them, you get predictable, production-ready results.

Core Principles

• ✅ Use: unknown type + type guards for safety
• ❌ Avoid: any type (breaks type checking)
• ✅ Use: Test-first development (Red-Green-Refactor)
• ❌ Avoid: Commented-out code (use git instead)
• ✅ Use: YAGNI principle (only build what's needed now)

Automated Quality Checks

Sub agents handle quality automatically:

Backend:

• task-executor: Implements with TDD approach
• quality-fixer: Fixes type/lint/test issues
• code-reviewer: Validates against design docs

Frontend:

• task-executor-frontend: React component implementation with TDD
• quality-fixer-frontend: Fixes quality + Lighthouse + bundle size
• technical-designer-frontend: React architecture & design decisions

Manual verification: npm run check:all

🌐 Multilingual Support

Full support for English and Japanese:

npm run lang:en         # Switch to English
npm run lang:ja         # Switch to Japanese
npm run lang:status     # Check current language

Automatically updates all configurations, rules, and agent definitions.

🤔 FAQ

Q: How do sub agents work?
A: Just use /implement or /task. The right agents activate automatically.

Q: What if there are errors?
A: quality-fixer auto-fixes most issues. If not, it provides clear instructions.

Q: Can I customize for my project?
A: Yes! Run /project-inject to configure project-specific context.

Q: What's the typical workflow?
A: /project-inject (once) → /implement (features) → auto quality checks → commit

Q: How is this different from Copilot/Cursor?
A: Those help write code. This manages entire development lifecycle with specialized agents.

🤖 Complete Sub Agents Roster

Agent	Specialization	Activation
requirement-analyzer	Scale assessment	Start of /implement
technical-designer	Design documentation	Medium/large features
work-planner	Task breakdown	After design approval
task-executor	Implementation	During build phase
quality-fixer	Automated fixes	On any quality issue
code-reviewer	Compliance check	/review command

Full agent list →

📄 License

MIT License - Free to use, modify, and distribute

🎯 About This Project

The AI Coding Project Boilerplate is engineered to maximize AI coding productivity while maintaining human-level code quality. By leveraging specialized sub agents and context engineering, it enables teams to build production-ready TypeScript applications at unprecedented speed.

---

Happy Coding with Claude Code! 🤖✨