AI Agent Project — Production-Grade Configuration

Quick Start

# Create a new project (interactive)
npx create-ai-agent-setup my-app

# Or with options
npx create-ai-agent-setup my-api --type backend --db postgresql --tier standard

# Mobile projects
npx create-ai-agent-setup my-mobile-app --type mobile-expo
npx create-ai-agent-setup my-mobile-app --type mobile-cli

# Skip prompts with defaults
npx create-ai-agent-setup my-app -y

Alternative Methods

# Clone and run init script
npx degit hoangNguyenAngelhack/ai-agent-setup my-project
cd my-project
./scripts/init.sh

# Copy only .claude config to existing project
npx degit hoangNguyenAngelhack/ai-agent-setup/.claude .claude

The CLI will guide you through:

1. Project name
2. Project type (backend / frontend / nextjs / fullstack / mobile-expo / mobile-cli)
3. Rule tier (Starter / Standard / Strict)
4. Database (PostgreSQL / MySQL / SQLite)
5. Author info

Overview

This repository provides a production-grade configuration for Claude Code AI agents. It includes:

• Structured development workflow (Spec → Plan → Build → Test → Review → Ship)
• 11 specialized agents for different development roles
• 13 mandatory rules covering code quality, architecture, and operations
• 8 slash commands for common workflows
• 6 reference checklists for security, testing, performance, accessibility, and mobile

Development Workflow

┌──────────────────────────────────────────────────────────────────┐
│                                                                  │
│   /spec  →  /plan  →  /build  →  /test  →  /review  →  /deploy  │
│                                                                  │
│   Define    Plan     Build     Verify    Review      Ship        │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

| Phase | Command | Description | |-------|---------|-------------| | Define | /spec | Create PRD with objectives, scope, and boundaries | | Plan | /plan | Decompose into vertical slices with acceptance criteria | | Build | /build | Implement incrementally using TDD | | Verify | /test | Write tests with RED-GREEN-REFACTOR | | Review | /review | Five-axis code review | | Ship | /deploy | Build, test, and deploy |

Supporting Commands

| Command | Description | |---------|-------------| | /debug | Systematic error diagnosis | | /simplify | Reduce code complexity | | /fix-issue | Analyze and fix issues |

Project Structure

.claude/
├── CLAUDE.md                    # Main AI configuration
│
├── commands/                    # Slash commands (8 total)
│   ├── spec.md                  # /spec — PRD creation
│   ├── plan.md                  # /plan — Task breakdown
│   ├── build.md                 # /build — Incremental implementation
│   ├── test.md                  # /test — TDD workflow
│   ├── review.md                # /review — Code review
│   ├── deploy.md                # /deploy — Deployment
│   ├── debug.md                 # /debug — Error diagnosis
│   ├── simplify.md              # /simplify — Code simplification
│   └── fix-issue.md             # /fix-issue — Issue resolution
│
├── agents/                      # Specialized agents (11 total)
│   ├── frontend.md              # Frontend Developer
│   ├── backend.md               # Backend Developer
│   ├── mobile.md                # Mobile Developer (React Native)
│   ├── systems-architect.md     # Systems Architect
│   ├── code-reviewer.md         # Code Reviewer
│   ├── test-engineer.md         # Test Engineer
│   ├── security-auditor.md      # Security Auditor
│   ├── qa.md                    # QA Engineer
│   ├── project-manager.md       # Project Manager
│   ├── ui-ux-designer.md        # UI/UX Designer
│   └── copywriter-seo.md        # Copywriter/SEO
│
├── rules/                       # Mandatory rules (13 total)
│   ├── clean-code.md            # Clean Code principles
│   ├── code-style.md            # Formatting & naming
│   ├── error-handling.md        # Error patterns
│   ├── tech-stack.md            # Approved technologies
│   ├── system-design.md         # System design patterns
│   ├── project-structure.md     # Folder organization
│   ├── api-conventions.md       # REST API standards
│   ├── naming-conventions.md    # Naming patterns
│   ├── database.md              # Database patterns
│   ├── security.md              # Security requirements
│   ├── monitoring.md            # Observability
│   ├── testing.md               # Test standards
│   └── git-workflow.md          # Git conventions
│
├── skills/                      # Advanced skills
│   ├── tdd/SKILL.md             # Test-Driven Development
│   ├── code-review/SKILL.md     # Five-axis review
│   ├── incremental-implementation/SKILL.md
│   ├── deploy/SKILL.md
│   └── security-review/SKILL.md
│
├── references/                  # Quick checklists
│   ├── security-checklist.md
│   ├── testing-patterns.md
│   ├── performance-checklist.md
│   ├── accessibility-checklist.md
│   ├── mobile-performance-checklist.md
│   └── mobile-release-checklist.md
│
└── settings.json                # Project settings

examples/                        # Sample implementations
├── backend/                     # Express + Prisma + Redis
│   ├── user-service.ts
│   ├── user-controller.ts
│   └── ... (11 files)
├── frontend/                    # React + TanStack Query + Zustand
│   ├── use-users.ts
│   ├── user-list.tsx
│   └── ... (4 files)
├── mobile-expo/                 # Expo + React Navigation + NativeWind
│   ├── api.ts, auth-store.ts
│   ├── user-list.tsx, login-screen.tsx
│   └── ... (10 files)
└── mobile-cli/                  # React Native CLI + NativeWind
    ├── api.ts, auth-store.ts
    ├── root-navigator.tsx
    └── ... (8 files)

templates/                       # Project templates
├── mobile-expo/                 # Ready-to-use Expo template
└── mobile-cli/                  # Ready-to-use RN CLI template

Specialized Agents

Development Agents

| Agent | Role | Invoke When | |-------|------|-------------| | Frontend Developer | Next.js, React, TypeScript, UI | Components, pages, state | | Backend Developer | Express, Prisma, Redis, BullMQ | APIs, services, jobs | | Mobile Developer | React Native, Expo, NativeWind | iOS/Android apps, navigation | | Systems Architect | Architecture, ADRs, scaling | System design decisions |

Quality Agents

| Agent | Role | Invoke When | |-------|------|-------------| | Code Reviewer | Five-axis code review | PR reviews, quality checks | | Test Engineer | TDD, coverage, test strategy | Writing and reviewing tests | | Security Auditor | Vulnerability, threat modeling | Security reviews | | QA Engineer | Test plans, E2E, bug reports | Quality assurance |

Product Agents

| Agent | Role | Invoke When | |-------|------|-------------| | Project Manager | Stories, sprints, planning | Project planning | | UI/UX Designer | Design system, accessibility | UX decisions | | Copywriter/SEO | Copy, meta tags, SEO | Content creation |

Approved Tech Stack

| Layer | Technology | |-------|-----------| | Frontend (SEO) | Next.js 14 (App Router) | | Frontend (Admin) | React + Vite | | Styling | Tailwind CSS + shadcn/ui | | State | Zustand + TanStack Query | | Backend | Express.js + TypeScript | | ORM | Prisma | | Database | PostgreSQL | | Cache | Redis (ioredis) | | Queue | BullMQ (simple) / RabbitMQ (enterprise) | | Auth | NextAuth.js / JWT + bcrypt | | Testing | Vitest + Playwright | | Monitoring | Prometheus + Grafana + Pino | | CI/CD | GitHub Actions | | Deploy | Vercel + Railway/Fly.io | | Mobile | React Native 0.74+ / Expo SDK 51+ | | Mobile UI | NativeWind (Tailwind CSS) | | Mobile Nav | React Navigation / Expo Router | | Mobile State | Zustand + MMKV |

Mandatory Rules

All 13 rules in .claude/rules/ must be followed:

Code Quality

• clean-code.md — Variables, functions, SOLID, async/await
• code-style.md — 2-space indent, single quotes, semicolons
• error-handling.md — AppError class, centralized handler

Architecture

• tech-stack.md — Approved technologies only
• system-design.md — CAP, caching, scaling patterns
• project-structure.md — Layered architecture
• api-conventions.md — REST standards, response envelopes

Data & Naming

• naming-conventions.md — Cache keys, DB, queues, env vars
• database.md — Prisma patterns, N+1 prevention

Operations

• security.md — CRITICAL — Never violate
• monitoring.md — Prometheus, Grafana, alerting
• testing.md — 80% coverage minimum
• git-workflow.md — Conventional commits

Quick Start

# Clone repository
git clone <repo-url>
cd ai-agent

# Copy to your project
cp -r .claude/ /path/to/your/project/

# Or use as template

Using Commands

# In Claude Code, use slash commands:
/spec "User authentication feature"
/plan
/build
/test
/review
/deploy

Using Agents

"Act as the Frontend Developer and build the login page"
"As Systems Architect, design the notification system"
"Code Reviewer: review this PR for security issues"
"Test Engineer: write tests for the payment flow"

Key Concepts

Five-Axis Code Review

Every code review evaluates:

1. Correctness — Does it work? Edge cases?
2. Readability — Can others understand it?
3. Architecture — Follows patterns? Appropriate abstractions?
4. Security — Input validation? Auth? No secrets?
5. Performance — N+1? Pagination? Async?

Test-Driven Development

RED    → Write failing test
GREEN  → Write minimal code to pass
REFACTOR → Improve while green

Vertical Slicing

Build features end-to-end, not layer-by-layer:

✅ Task 1: User can create task (DB + API + UI)
✅ Task 2: User can view tasks (DB + API + UI)

❌ Task 1: Create all DB models
❌ Task 2: Create all API routes

Security

Never commit:

• .env files
• API keys, secrets, passwords
• .claude/settings.local.json

Always:

• Use environment variables
• Validate all inputs
• Hash passwords (bcrypt >= 12 rounds)
• Parameterize queries

Contributing

1. Follow the development workflow (/spec → /plan → /build)
2. Ensure all tests pass
3. Run /review before submitting PR
4. Follow conventional commit format

Author

Hoang Nguyen

• Email: [email protected]