scripte/archivmail
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Migrate from agent markdown files to Skills, Rules, and Sub-Agents

Browse Source 
Replace the manual "read .claude/agents/*.md" workflow with native
Claude Code features for a more efficient, scalable development experience:

- **Skills** (.claude/skills/): 7 auto-discovered slash commands
  (/requirements, /architecture, /frontend, /backend, /qa, /deploy, /help)
  with forked sub-agents for heavy tasks and inline execution for interactive ones
- **Rules** (.claude/rules/): 4 modular rule files (general, frontend, backend,
  security) auto-applied based on file context
- **Sub-Agents** (.claude/agents/): Lightweight configs for frontend-dev,
  backend-dev, and qa-engineer with model, tool, and turn limit settings
- **Context Engineering**: Layered context loading, context isolation via
  forked skills, built-in context recovery after compaction, and
  "always read, never guess" rules to prevent hallucinated code references
- **CLAUDE.md**: Auto-loaded project context replacing PROJECT_CONTEXT.md
- **Feature tracking**: features/INDEX.md as persistent state across sessions
- **Production guides**: docs/production/ for error tracking, security,
  performance, database optimization, and rate limiting
- **Init Mode**: /requirements detects empty PRD and bootstraps full project
  setup (PRD + all feature specs) from a single project description

Removed: 6 monolithic agent files, PROJECT_CONTEXT.md, HOW_TO_USE_AGENTS.md,
TEMPLATE_CHANGELOG.md

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
“alexvisualmakers”
2026-02-13 10:15:27 +01:00
parent d7abbc3f8c
commit 600552c858
35 changed files with 1908 additions and 2673 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+228 -209
View File
@@ -1,18 +1,8 @@
# AI Coding Starter Kit – Production-Ready Template
# AI Coding Starter Kit
> **Build scalable, production-ready web apps faster** with AI agents handling Requirements, Architecture, Development, QA, and Deployment.
> Build production-ready web apps faster with AI-powered Skills handling Requirements, Architecture, Development, QA, and Deployment.
This template includes everything you need for professional AI-powered development:
- ✅ **Next.js 16** (latest) with TypeScript + Tailwind CSS
- ✅ **6 Production-Ready AI Agents** (Requirements → Deployment)
- ✅ **Production Guides** (Error Tracking, Security, Performance, Scaling)
- ✅ **Feature Changelog System** (Agents know what already exists → Code Reuse)
- ✅ **PM-Friendly** (No code in specs, automatic handoffs between agents)
- ✅ **Supabase-Ready** (optional)
- ✅ **shadcn/ui-Ready** (add components as needed)
- ✅ **Vercel Deployment-Ready**
---
This template uses [Claude Code](https://docs.anthropic.com/en/docs/claude-code) with modern Skills, Rules, and Sub-Agents to provide a complete AI-powered development workflow.
## Quick Start
@@ -31,11 +21,11 @@ If you need a backend:
1. Create Supabase Project: [supabase.com](https://supabase.com)
2. Copy `.env.local.example` to `.env.local`
3. Add your Supabase credentials
4. Activate Supabase Client in `src/lib/supabase.ts` (uncomment code)
4. Uncomment the Supabase client in `src/lib/supabase.ts`
**Skip this step** if you're building frontend-only (landing pages, portfolios, etc.)
Skip this step if you're building frontend-only (landing pages, portfolios, etc.)
### 3. Start Development Server
### 3. Start Development
```bash
npm run dev
@@ -43,121 +33,85 @@ npm run dev
Open [http://localhost:3000](http://localhost:3000) in your browser.
### 4. Use AI Agents
### 4. Initialize Your Project
⚠️ **Important:** Agents are **not Skills** – you can't call them with `/requirements-engineer`!
**How to use Agents:**
Open Claude Code and describe your project. The `/requirements` skill automatically detects that this is a fresh project and enters **Init Mode**:
```
Hey Claude, read .claude/agents/requirements-engineer.md and create a feature spec for [your idea].
/requirements I want to build a project management tool for small teams
where users can create projects, assign tasks, and track progress.
```
**Full Guide:** See [HOW_TO_USE_AGENTS.md](HOW_TO_USE_AGENTS.md)
The skill will:
1. Ask interactive questions to clarify your vision, target users, and MVP scope
2. Create your **Product Requirements Document** (`docs/PRD.md`)
3. Break the project into individual features (Single Responsibility)
4. Create all **feature specs** (`features/PROJ-1.md`, `PROJ-2.md`, etc.)
5. Update **feature tracking** (`features/INDEX.md`)
6. Recommend which feature to build first
**Available Agents:**
- `requirements-engineer.md` - Feature Specs with interactive questions
- `solution-architect.md` - PM-friendly Tech Design (no code snippets)
- `frontend-dev.md` - UI Components + Automatic Backend/QA Handoff
- `backend-dev.md` - APIs + Database + **Performance Best Practices**
- `qa-engineer.md` - Testing + Regression Tests
- `devops.md` - Deployment + **Production-Ready Essentials**
You don't need to put everything in the first prompt - a brief description is enough. The skill asks follow-up questions interactively.
### 5. Build Features
After project initialization, build features one at a time using skills:
```
/architecture Design the tech approach for features/PROJ-1-user-auth.md
/frontend Build the UI for features/PROJ-1-user-auth.md
/backend Build the API for features/PROJ-1-user-auth.md
/qa Test features/PROJ-1-user-auth.md
/deploy Deploy to Vercel
```
Each skill suggests the next step when it finishes. Handoffs are always user-initiated.
To add more features later, run `/requirements` again - it detects the existing PRD and adds a single feature.
---
## Project Structure
## Available Skills
```
ai-coding-starter-kit/
├── .claude/
│ └── agents/ ← 6 AI Agents (Production-Ready)
├── features/ ← Feature Specs (includes specs, test results, deployment status)
│ └── README.md
├── src/
│ ├── app/ ← Pages (Next.js App Router)
│ │ ├── layout.tsx
│ │ ├── page.tsx
│ │ └── globals.css
│ ├── components/ ← React Components
│ │ └── ui/ ← shadcn/ui components (add as needed)
│ └── lib/ ← Utility functions
│ ├── supabase.ts ← Supabase Client (commented out by default)
│ └── utils.ts
├── public/ ← Static files
├── PROJECT_CONTEXT.md ← Project Documentation (fill this out!)
├── TEMPLATE_CHANGELOG.md ← Template Version History (v1.0 - v1.3)
├── HOW_TO_USE_AGENTS.md ← Agent Usage Guide
├── .env.local.example ← Environment Variables Template
└── package.json
```
| Skill | Command | What It Does |
|-------|---------|-------------|
| Requirements Engineer | `/requirements` | Creates feature specs with user stories, acceptance criteria, edge cases |
| Solution Architect | `/architecture` | Designs PM-friendly tech architecture (no code, only high-level design) |
| Frontend Developer | `/frontend` | Builds UI with React, Tailwind CSS, and shadcn/ui |
| Backend Developer | `/backend` | Builds APIs, database schemas, RLS policies with Supabase |
| QA Engineer | `/qa` | Tests features against acceptance criteria + security audit |
| DevOps | `/deploy` | Deploys to Vercel with production-ready checks |
| Help | `/help` | Context-aware guide: shows where you are and what to do next |
### How Skills Work
- **Skills** are defined in `.claude/skills/` and auto-discovered by Claude Code
- **Rules** in `.claude/rules/` are auto-applied based on file context (no manual loading)
- **Sub-Agents** run heavy tasks (frontend, backend, QA) in isolated contexts for cost efficiency
- **CLAUDE.md** provides project context automatically at every session start
---
## Production-Ready Features ⚡
## Development Workflow
This template includes production-readiness guides integrated into the agents:
### DevOps Agent includes:
- **Error Tracking Setup** (Sentry) – 5-minute setup with code examples
- **Security Headers** (XSS/Clickjacking Protection) – Copy-paste `next.config.js`
- **Environment Variables Best Practices** – Secrets management
- **Performance Monitoring** (Lighthouse) – Built-in Chrome DevTools
### Backend Agent includes:
- **Database Indexing** – Make queries 10-100x faster
- **Query Optimization** – Avoid N+1 problems with Supabase joins
- **Caching Strategy** – Next.js `unstable_cache` examples
- **Input Validation** – Zod schemas for API safety
- **Rate Limiting** – Optional Upstash Redis setup
All guides are **practical** with **copy-paste code examples** – no theory!
---
## Agent-Team Workflow
### 1. Requirements Phase
```bash
# Tell Claude:
"Read .claude/agents/requirements-engineer.md and create a feature spec for [your idea]"
```
1. Define /requirements --> Feature spec in features/PROJ-X.md
2. Design /architecture --> Tech design added to feature spec
3. Build /frontend --> UI components implemented
/backend --> APIs + database (if needed)
4. Test /qa --> Test results added to feature spec
5. Ship /deploy --> Deployed to Vercel
```
Agent asks questions → You answer → Agent creates Feature Spec in `/features/PROJ-1-feature.md`
### Feature Tracking
### 2. Architecture Phase
```bash
# Tell Claude:
"Read .claude/agents/solution-architect.md and design the architecture for /features/PROJ-1-feature.md"
```
Features are tracked in `features/INDEX.md`:
Agent designs PM-friendly Tech Design (no code!) → You review
| ID | Feature | Status | Spec |
|----|---------|--------|------|
| PROJ-1 | User Login | Deployed | [Spec](features/PROJ-1-user-login.md) |
| PROJ-2 | Dashboard | In Progress | [Spec](features/PROJ-2-dashboard.md) |
### 3. Implementation Phase
```bash
# Frontend:
"Read .claude/agents/frontend-dev.md and implement /features/PROJ-1-feature.md"
# Backend (if using Supabase):
"Read .claude/agents/backend-dev.md and implement /features/PROJ-1-feature.md"
```
**Note:** Frontend Agent automatically checks if Backend is needed and hands off to QA when done!
### 4. Testing Phase
```bash
# Tell Claude:
"Read .claude/agents/qa-engineer.md and test /features/PROJ-1-feature.md"
```
Agent tests all Acceptance Criteria → Adds test results to feature spec
### 5. Deployment Phase
```bash
# Tell Claude:
"Read .claude/agents/devops.md and deploy to Vercel"
```
Agent guides you through deployment + Production-Ready setup (Error Tracking, Security, Performance)
Every skill reads this file at start and updates it when done, preventing duplicate work.
---
@@ -165,140 +119,205 @@ Agent guides you through deployment + Production-Ready setup (Error Tracking, Se
| Category | Tool | Why? |
|----------|------|------|
| **Framework** | Next.js 16 | React + Server Components + Routing |
| **Language** | TypeScript | Type Safety |
| **Styling** | Tailwind CSS | Utility-First CSS |
| **UI Library** | shadcn/ui | Copy-Paste Components |
| **Backend** | Supabase (optional) | PostgreSQL + Auth + Storage |
| **Deployment** | Vercel | Zero-Config Next.js Hosting |
| **Error Tracking** | Sentry (optional) | Production Error Monitoring |
| **Framework** | Next.js 16 | React + Server Components + App Router |
| **Language** | TypeScript | Type safety |
| **Styling** | Tailwind CSS | Utility-first CSS |
| **UI Library** | shadcn/ui | Copy-paste, customizable components |
| **Backend** | Supabase (optional) | PostgreSQL + Auth + Storage + Realtime |
| **Deployment** | Vercel | Zero-config Next.js hosting |
| **Validation** | Zod | Runtime type validation |
---
## Next Steps
## Project Structure
1. **Fill out PROJECT_CONTEXT.md**
- Define your vision
- Add features to roadmap
2. **Build your first feature**
- Use Requirements Engineer for Feature Spec
- Follow the Agent-Team workflow
3. **Add shadcn/ui components** (as needed)
```bash
npx shadcn@latest add button
npx shadcn@latest add card
# etc.
```
4. **Production Setup** (first deployment)
- Follow DevOps Agent guides:
- Error Tracking (Sentry) – 5 minutes
- Security Headers (`next.config.js`) – Copy-paste
- Performance Check (Lighthouse) – Chrome DevTools
5. **Deploy**
- Push to GitHub
- Connect with Vercel
- Use DevOps Agent for deployment help
```
ai-coding-starter-kit/
+-- CLAUDE.md <-- Auto-loaded project context
+-- .claude/
| +-- settings.json <-- Team permissions (committed)
| +-- settings.local.json <-- Personal overrides (gitignored)
| +-- rules/ <-- Auto-applied coding rules
| | +-- general.md Git workflow, feature tracking
| | +-- frontend.md shadcn/ui, component standards
| | +-- backend.md RLS, validation, queries
| | +-- security.md Secrets, headers, auth
| +-- skills/ <-- Invocable workflows (/command)
| | +-- requirements/SKILL.md /requirements
| | +-- architecture/SKILL.md /architecture
| | +-- frontend/SKILL.md /frontend (runs as sub-agent)
| | +-- backend/SKILL.md /backend (runs as sub-agent)
| | +-- qa/SKILL.md /qa (runs as sub-agent)
| | +-- deploy/SKILL.md /deploy
| | +-- help/SKILL.md /help (lightweight, uses haiku)
| +-- agents/ <-- Sub-agent configs
| +-- frontend-dev.md Model, tools, limits
| +-- backend-dev.md
| +-- qa-engineer.md
+-- features/ <-- Feature specifications
| +-- INDEX.md Status tracking
| +-- README.md Spec format documentation
+-- docs/
| +-- PRD.md <-- Product Requirements Document
| +-- production/ <-- Production setup guides
| +-- error-tracking.md Sentry setup (5 min)
| +-- security-headers.md XSS/Clickjacking protection
| +-- performance.md Lighthouse, optimization
| +-- database-optimization.md Indexing, N+1, caching
| +-- rate-limiting.md Upstash Redis
+-- src/
| +-- app/ <-- Pages (Next.js App Router)
| +-- components/
| | +-- ui/ <-- shadcn/ui components (35+ installed)
| +-- hooks/ <-- Custom React hooks
| +-- lib/ <-- Utilities
+-- public/ <-- Static files
```
---
## What's Included
## Getting Started
### ✅ Works out-of-the-box
### 1. Fill Out Your PRD
- Next.js 16 with App Router
- TypeScript (strict mode)
- Tailwind CSS (configured)
- ESLint 9 (Next.js defaults)
- 6 Production-Ready AI Agents
- Feature Changelog System (Code-Reuse!)
- Project Structure (best practices)
- Environment Variables Setup
- .gitignore (Node modules, .env, etc.)
Define your product vision in `docs/PRD.md`:
- What are you building and why?
- Who are the target users?
- What features are on the roadmap?
### 📦 You add yourself
### 2. Build Your First Feature
- shadcn/ui Components (as needed)
- Supabase Setup (optional)
- Your Features (with Agent-Team)
- Production Setup (Error Tracking, Security Headers)
Run `/requirements` with your feature idea. The skill will:
- Ask interactive questions to clarify requirements
- Create a feature spec in `features/PROJ-1-name.md`
- Update `features/INDEX.md` with the new feature
- Suggest running `/architecture` as the next step
### 3. Add shadcn/ui Components (as needed)
35+ components are pre-installed. Add more as needed:
```bash
npx shadcn@latest add [component-name]
```
### 4. Production Setup (first deployment)
When you're ready to deploy, the `/deploy` skill guides you through:
- Vercel setup and deployment
- Error tracking with Sentry
- Security headers configuration
- Performance monitoring with Lighthouse
See `docs/production/` for detailed setup guides.
---
## Why This Template?
## How It Works Under the Hood
### For Product Managers
- **No deep tech background needed** – Agents explain in PM-friendly language
- **Automatic handoffs** – Frontend → Backend Check → QA (no manual coordination)
- **Production-ready** – Security, Performance, Error Tracking included
### Skills (`.claude/skills/`)
Each skill is a structured workflow that Claude Code discovers automatically. Skills can run inline (in the main conversation) or as forked sub-agents (isolated context, cheaper model).
### For Solo Founders
- **Build faster** – Agents handle Requirements → Deployment
- **Built for scale** – Database indexing, query optimization, caching
- **MVP to Production** – One template for both
| Skill | Execution | Why? |
|-------|-----------|------|
| `/requirements` | Inline | Needs live interaction with user |
| `/architecture` | Inline | Short output, user reviews in real-time |
| `/frontend` | Sub-agent (forked) | Heavy file editing, lots of output |
| `/backend` | Sub-agent (forked) | Heavy file editing, SQL, API code |
| `/qa` | Sub-agent (forked) | Systematic testing, lots of output |
| `/deploy` | Inline | Deployment needs user oversight |
| `/help` | Inline (haiku) | Lightweight status check, minimal cost |
### For Small Teams (2-5 people)
- **Consistent workflow** – Everyone follows the same agent system
- **Code reuse** – Git history shows what exists, prevents duplication
- **Knowledge sharing** – All decisions documented in Feature Specs
### Rules (`.claude/rules/`)
Coding standards that are auto-applied based on which files Claude is working with. No manual loading needed.
### Sub-Agent Configs (`.claude/agents/`)
Lightweight configurations that define model, tool access, and turn limits for forked skills.
### CLAUDE.md
Auto-loaded at every session start. Contains tech stack, conventions, and references to PRD and feature index.
---
## Documentation
## Context Engineering
### Template Docs
- [HOW_TO_USE_AGENTS.md](HOW_TO_USE_AGENTS.md) – Agent usage guide
- [PROJECT_CONTEXT.md](PROJECT_CONTEXT.md) – Project documentation template
- [TEMPLATE_CHANGELOG.md](TEMPLATE_CHANGELOG.md) – Template version history
- [features/README.md](features/README.md) – Feature spec format
AI agents work best with clean, structured context - not longer prompts. This template is designed around these principles:
### External Docs
- [Next.js Docs](https://nextjs.org/docs)
- [Tailwind CSS Docs](https://tailwindcss.com/docs)
- [shadcn/ui Docs](https://ui.shadcn.com)
- [Supabase Docs](https://supabase.com/docs)
### State lives in files, not in memory
Every skill reads `features/INDEX.md` and the relevant feature spec at start. After context compaction or a new session, nothing is lost - the agent simply re-reads the files. Progress tracking, acceptance criteria, and tech designs all live in markdown files, not in the conversation.
### Context is layered
Not everything is loaded at once. Information is layered by relevance:
| Layer | What | When loaded |
|-------|------|-------------|
| `CLAUDE.md` | Tech stack, conventions, commands | Every session (auto) |
| `.claude/rules/` | Coding standards | When editing matching files (auto) |
| Skill `SKILL.md` | Workflow instructions | When skill is invoked |
| Feature spec | Requirements, AC, tech design | On demand (skill reads it) |
| `docs/production/` | Deployment guides | Only when referenced |
### Context is isolated
Heavy implementation skills (`/frontend`, `/backend`, `/qa`) run as **forked sub-agents** with their own context window. Research noise from one skill doesn't pollute another. Each fork starts clean and loads only what it needs.
### Context recovery is built in
All forked skills include a **Context Recovery** section: if the context is compacted mid-task, the agent re-reads the feature spec, checks `git diff` for progress, and continues without restarting or duplicating work.
### Always read, never guess
A global rule (`rules/general.md`) enforces: always read a file before modifying it, never assume contents from memory, verify import paths and API routes by reading. This prevents hallucinated code references - the most common source of AI coding errors.
---
## Customization for Your Team
This template is designed as a starting point. Customize it for your team:
1. **Edit CLAUDE.md** - Add your project-specific conventions and build commands
2. **Edit docs/PRD.md** - Define your product vision and roadmap
3. **Edit .claude/rules/** - Adjust coding standards for your team
4. **Edit .claude/skills/** - Modify workflows to match your process
5. **Edit .claude/settings.json** - Configure team permissions
---
## Production Guides
Standalone guides in `docs/production/`:
| Guide | Setup Time | What It Does |
|-------|-----------|-------------|
| [Error Tracking](docs/production/error-tracking.md) | 5 min | Sentry integration for automatic error capture |
| [Security Headers](docs/production/security-headers.md) | 2 min | XSS, Clickjacking, MIME sniffing protection |
| [Performance](docs/production/performance.md) | 10 min | Lighthouse checks, image optimization, caching |
| [Database Optimization](docs/production/database-optimization.md) | 15 min | Indexing, N+1 prevention, query optimization |
| [Rate Limiting](docs/production/rate-limiting.md) | 10 min | Upstash Redis for API abuse prevention |
---
## Scripts
```bash
npm run dev # Start development server (localhost:3000)
npm run dev # Development server (localhost:3000)
npm run build # Production build
npm run start # Start production server
npm run lint # Run ESLint
npm run start # Production server
npm run lint # ESLint
```
---
## Template Versions
## Author
**Current:** v1.4.0 (Git-Based Workflow)
Created by **Alex Sprogis** – AI Product Engineer & Content Creator.
See [TEMPLATE_CHANGELOG.md](TEMPLATE_CHANGELOG.md) for full version history.
**Updates:**
- v1.4.0 – Git-Based Workflow (removed FEATURE_CHANGELOG, test-reports)
- v1.3.0 – Production-Ready Guides (Error Tracking, Security, Performance)
- v1.2.0 – Agent System Improvements (Interactive Questions, PM-Friendly Output)
- v1.1.0 – Enhanced Documentation
- v1.0.0 – Initial Release
- [YouTube](https://www.youtube.com/@alex.sprogis)
- [Website](https://alexsprogis.de)
---
## License
MIT License – feel free to use for your projects!
---
**Built with AI Agent Team System + Claude Code** 🚀
Ready to build production-ready apps? Start with the Requirements Engineer!
```bash
"Read .claude/agents/requirements-engineer.md and create a feature spec for [your idea]"
```
MIT License - feel free to use for your projects!