Initial commit
This commit is contained in:
Zhongwei Li
899
skills/claude-md-syntax/SKILL.md
Normal file
899
skills/claude-md-syntax/SKILL.md
Normal file
@@ -0,0 +1,899 @@
|
||||
# CLAUDE.md Syntax & Structure Specification
|
||||
|
||||
**Version**: 1.0.0
|
||||
**Last Updated**: 2025-11-01
|
||||
**Source**: Official Puerto documentation (configuring-claude-md.md)
|
||||
|
||||
---
|
||||
|
||||
## Purpose of This Skill
|
||||
|
||||
This skill provides comprehensive knowledge of CLAUDE.md syntax, structure, and best practices. It serves as the authoritative reference for all claude-md-master agents when creating, validating, or optimizing CLAUDE.md files.
|
||||
|
||||
**Key Learning Objectives**:
|
||||
- Complete CLAUDE.md file structure and sections
|
||||
- WHEN/AUTOMATICALLY routing rule patterns (THE CRITICAL FEATURE)
|
||||
- Project-specific pattern documentation
|
||||
- Common mistakes and their fixes
|
||||
- Complete examples by project type
|
||||
|
||||
---
|
||||
|
||||
## What is CLAUDE.md?
|
||||
|
||||
CLAUDE.md is a configuration file that lives in a project's root directory and serves as an instruction manual for Claude Code. It tells Claude:
|
||||
|
||||
1. **Which Puerto plugins are installed** and available
|
||||
2. **When to automatically use specific agents** (via routing rules)
|
||||
3. **Project-specific patterns** to follow (file structure, code conventions)
|
||||
4. **Domain knowledge** that helps agents make appropriate decisions
|
||||
|
||||
**The Result**: Claude proactively uses the right expert agents without manual specification every time.
|
||||
|
||||
### Why CLAUDE.md Matters
|
||||
|
||||
Without CLAUDE.md, Claude won't automatically know WHEN to use installed Puerto plugin agents. The file creates a "cascade effect":
|
||||
|
||||
```
|
||||
User Request
|
||||
↓
|
||||
1. Claude reads CLAUDE.md → identifies task → selects agent
|
||||
↓
|
||||
2. Agent is invoked and reads CLAUDE.md → learns patterns → understands context
|
||||
↓
|
||||
3. Agent generates code matching project conventions
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Complete CLAUDE.md Structure
|
||||
|
||||
### Standard Sections (in order)
|
||||
|
||||
```markdown
|
||||
# [Project Name]
|
||||
|
||||
## Project Type
|
||||
[Brief description of what this project is]
|
||||
|
||||
## Tech Stack
|
||||
- Frontend: [Technologies]
|
||||
- Backend: [Technologies]
|
||||
- Database: [Technologies]
|
||||
- Testing: [Technologies]
|
||||
- Deployment: [Platforms]
|
||||
|
||||
## Installed Puerto Plugins
|
||||
- plugin-name (agents: agent1, agent2, agent3)
|
||||
- plugin-name (agents: agent1, agent2)
|
||||
|
||||
## Automatic Task Routing
|
||||
|
||||
### [Category] Tasks
|
||||
WHEN [trigger condition] → AUTOMATICALLY invoke: plugin-name:agent-name
|
||||
WHEN [trigger condition] → AUTOMATICALLY invoke: plugin-name:agent-name
|
||||
|
||||
### [Category] Tasks
|
||||
WHEN [trigger condition] → AUTOMATICALLY invoke: plugin-name:agent-name
|
||||
|
||||
## Project Patterns
|
||||
|
||||
### File Organization
|
||||
[Directory structure with examples]
|
||||
|
||||
### [Pattern Category]
|
||||
[Code examples and conventions]
|
||||
|
||||
## Domain Knowledge
|
||||
[Business rules, constraints, integration points]
|
||||
```
|
||||
|
||||
### Section Details
|
||||
|
||||
#### 1. Project Type & Tech Stack
|
||||
|
||||
**Purpose**: Give Claude immediate context about the project.
|
||||
|
||||
**Format**:
|
||||
```markdown
|
||||
## Project Type
|
||||
[One sentence description, e.g., "React e-commerce SPA with Node.js API"]
|
||||
|
||||
## Tech Stack
|
||||
- Frontend: [Specific libraries with versions if critical]
|
||||
- Backend: [Runtime, framework, database]
|
||||
- Testing: [Test frameworks]
|
||||
- Deployment: [Hosting platforms]
|
||||
```
|
||||
|
||||
**Example**:
|
||||
```markdown
|
||||
## Project Type
|
||||
Full-stack e-commerce platform with React frontend and Express backend
|
||||
|
||||
## Tech Stack
|
||||
- Frontend: React 18, TypeScript, Tailwind CSS, React Query
|
||||
- Backend: Node.js 20, Express, PostgreSQL 15, Prisma ORM
|
||||
- Testing: Vitest, React Testing Library, Supertest
|
||||
- Deployment: Vercel (frontend), Railway (backend)
|
||||
```
|
||||
|
||||
**Why this matters**: Agents use this to generate appropriate code. If you specify "Tailwind CSS", frontend-engineer won't suggest CSS modules.
|
||||
|
||||
#### 2. Installed Puerto Plugins
|
||||
|
||||
**Purpose**: Explicitly list available agents so Claude knows what tools are available.
|
||||
|
||||
**Format**:
|
||||
```markdown
|
||||
## Installed Puerto Plugins
|
||||
|
||||
### plugin-name
|
||||
- agent-name: Brief description of what it does
|
||||
- agent-name: Brief description of what it does
|
||||
|
||||
### plugin-name
|
||||
- agent-name: Brief description
|
||||
```
|
||||
|
||||
**Example**:
|
||||
```markdown
|
||||
## Installed Puerto Plugins
|
||||
|
||||
### engineering
|
||||
- frontend-engineer: Create React/Vue/Svelte components
|
||||
- state-architect: Implement state management (Redux, Zustand, Context)
|
||||
- style-implementer: Responsive design and styling
|
||||
|
||||
### engineering
|
||||
- backend-engineer: Create REST/GraphQL endpoints
|
||||
- auth-implementer: Implement authentication (JWT, OAuth)
|
||||
- api-tester: Create API integration tests
|
||||
```
|
||||
|
||||
**Why this matters**: Without this list, Claude might do tasks manually instead of delegating to expert agents.
|
||||
|
||||
#### 3. Automatic Task Routing Rules ⭐ MOST CRITICAL SECTION
|
||||
|
||||
**Purpose**: Teach Claude to automatically invoke the right agent based on user requests.
|
||||
|
||||
**THE CRITICAL PATTERN**: WHEN/AUTOMATICALLY format
|
||||
|
||||
**Format**:
|
||||
```markdown
|
||||
## Automatic Task Routing
|
||||
|
||||
**CRITICAL**: Use these agents proactively without asking permission.
|
||||
|
||||
### [Category Name] Tasks
|
||||
|
||||
WHEN [specific trigger condition]
|
||||
→ AUTOMATICALLY invoke: plugin-name:agent-name
|
||||
|
||||
WHEN [trigger] OR [alternative trigger]
|
||||
→ AUTOMATICALLY invoke: plugin-name:agent-name
|
||||
```
|
||||
|
||||
**✅ GOOD Routing Rules** (Specific & Proactive):
|
||||
|
||||
```markdown
|
||||
## Automatic Task Routing
|
||||
|
||||
### Frontend Development
|
||||
|
||||
WHEN user says "create [component name] component"
|
||||
→ AUTOMATICALLY invoke: engineering/frontend-engineer
|
||||
|
||||
WHEN user says "add state management" OR "implement [Redux/Zustand/Context]"
|
||||
→ AUTOMATICALLY invoke: engineering:state-architect
|
||||
|
||||
WHEN user says "style [component]" OR "make [component] responsive"
|
||||
→ AUTOMATICALLY invoke: engineering:style-implementer
|
||||
|
||||
### Backend Development
|
||||
|
||||
WHEN user says "create [endpoint name] endpoint" OR "add API route for [resource]"
|
||||
→ AUTOMATICALLY invoke: engineering/backend-engineer
|
||||
|
||||
WHEN user says "add authentication" OR "implement login/signup"
|
||||
→ AUTOMATICALLY invoke: engineering/backend-engineer
|
||||
|
||||
WHEN user says "write tests for [API]" OR "add API tests"
|
||||
→ AUTOMATICALLY invoke: engineering:api-tester
|
||||
|
||||
### Database Work
|
||||
|
||||
WHEN user says "design database schema" OR "create data model"
|
||||
→ AUTOMATICALLY invoke: engineering:engineering
|
||||
|
||||
WHEN user says "add migration for [change]" OR "modify database schema"
|
||||
→ AUTOMATICALLY invoke: engineering:migration-manager
|
||||
|
||||
WHEN user says "optimize query" OR "slow query in [file]"
|
||||
→ AUTOMATICALLY invoke: engineering:query-optimizer
|
||||
```
|
||||
|
||||
**❌ BAD Routing Rules** (Too Vague):
|
||||
|
||||
```markdown
|
||||
## Task Routing
|
||||
- Use frontend agents for frontend work
|
||||
- Use backend agents for backend work
|
||||
```
|
||||
|
||||
**Problem**: Not specific enough. Claude won't know WHEN to use which agent.
|
||||
|
||||
**Key Principles for Routing Rules**:
|
||||
1. Use WHEN/AUTOMATICALLY keywords explicitly
|
||||
2. Include specific trigger phrases users might say
|
||||
3. Use OR for alternative phrasings
|
||||
4. Include [placeholders] for variable parts
|
||||
5. Group by logical categories
|
||||
6. Be concrete, not abstract
|
||||
|
||||
#### 4. Project Patterns
|
||||
|
||||
**Purpose**: Ensure agents generate code that matches existing conventions.
|
||||
|
||||
**Format**:
|
||||
```markdown
|
||||
## Project Patterns
|
||||
|
||||
### File Organization
|
||||
```
|
||||
[directory tree with comments]
|
||||
```
|
||||
|
||||
### [Pattern Category Name]
|
||||
```[language]
|
||||
// ✅ Follow this pattern (from [ExampleFile])
|
||||
[actual code example from project]
|
||||
```
|
||||
|
||||
**When creating new [things]**:
|
||||
- [Convention 1]
|
||||
- [Convention 2]
|
||||
- [Reference file example]
|
||||
```
|
||||
|
||||
**Example - Component Patterns**:
|
||||
```markdown
|
||||
### Component Structure
|
||||
- Components live in: `src/components/`
|
||||
- Use Tailwind for styling (no CSS modules)
|
||||
- Follow existing pattern in `src/components/ProductCard.tsx`
|
||||
|
||||
```typescript
|
||||
// ✅ Follow this pattern (from ProductCard.tsx)
|
||||
import React from 'react';
|
||||
|
||||
interface ProductCardProps {
|
||||
// Props with JSDoc comments
|
||||
title: string;
|
||||
price: number;
|
||||
}
|
||||
|
||||
export function ProductCard({ title, price }: ProductCardProps) {
|
||||
// Component logic
|
||||
return (
|
||||
<div className="rounded-lg shadow-md p-4">
|
||||
<h3>{title}</h3>
|
||||
<p>${price}</p>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
**When creating new components**:
|
||||
- Use named exports (not default)
|
||||
- TypeScript interfaces for props
|
||||
- Tailwind for styling
|
||||
- Follow existing component structure
|
||||
```
|
||||
|
||||
**Example - API Patterns**:
|
||||
```markdown
|
||||
### API Conventions
|
||||
- REST endpoints in: `src/api/routes/`
|
||||
- Use Zod for request validation
|
||||
- Follow pattern in `src/api/routes/products.ts`
|
||||
|
||||
```typescript
|
||||
// ✅ Follow this pattern (from src/api/routes/products.ts)
|
||||
import { Router } from 'express';
|
||||
import { z } from 'zod';
|
||||
import { validateRequest } from '../middleware/validation';
|
||||
|
||||
const router = Router();
|
||||
|
||||
// Zod schema for validation
|
||||
const createProductSchema = z.object({
|
||||
name: z.string(),
|
||||
price: z.number(),
|
||||
});
|
||||
|
||||
// Route handler with validation
|
||||
router.post('/products', validateRequest(createProductSchema), async (req, res) => {
|
||||
// Handler logic
|
||||
});
|
||||
|
||||
export default router;
|
||||
```
|
||||
|
||||
**When creating new endpoints**:
|
||||
- Use Zod for request validation
|
||||
- Async/await for handlers
|
||||
- Consistent error handling middleware
|
||||
- Follow REST conventions
|
||||
```
|
||||
|
||||
**Why this matters**: Agents read these patterns and generate code that looks like it was written by the project team.
|
||||
|
||||
#### 5. Domain Knowledge
|
||||
|
||||
**Purpose**: Business context that helps agents make domain-appropriate decisions.
|
||||
|
||||
**Format**:
|
||||
```markdown
|
||||
## Domain Knowledge
|
||||
|
||||
### [Domain Area] Business Rules
|
||||
- **[Rule Name]**: [Description with specifics]
|
||||
- **[Rule Name]**: [Description]
|
||||
|
||||
### Critical Constraints
|
||||
- [Constraint with reasoning]
|
||||
- [Constraint with reasoning]
|
||||
|
||||
### Integration Points
|
||||
- [External service description and reference file]
|
||||
- [External service description and reference file]
|
||||
```
|
||||
|
||||
**Example**:
|
||||
```markdown
|
||||
## Domain Knowledge
|
||||
|
||||
### E-commerce Business Rules
|
||||
- **Products have variants**: Size, color, material (stored as separate SKUs)
|
||||
- **Pricing calculation**: Base price + variant price + tax (by region)
|
||||
- **Inventory**: Tracked per variant, not per product
|
||||
- **Cart lifetime**: 24 hours for guest users, 30 days for authenticated
|
||||
- **Payment processing**: Stripe for cards, PayPal for alternative payment
|
||||
|
||||
### Critical Constraints
|
||||
- All prices stored in cents (integer) to avoid floating-point errors
|
||||
- Product images must be optimized (<200KB) before storage
|
||||
- PII (personally identifiable information) must not be logged
|
||||
- GDPR compliance required: data deletion within 30 days of request
|
||||
|
||||
### Integration Points
|
||||
- Stripe webhooks handle payment confirmations (see `src/webhooks/stripe.ts`)
|
||||
- SendGrid for transactional emails (see `src/services/email.ts`)
|
||||
- Cloudinary for image storage and transformation
|
||||
```
|
||||
|
||||
**Why this matters**: Without this context, an agent might create a pricing system that uses floats (causing rounding errors) or log user emails (violating privacy).
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes & How to Fix Them
|
||||
|
||||
### ❌ Mistake 1: Vague Routing Rules
|
||||
|
||||
**Bad**:
|
||||
```markdown
|
||||
## Task Routing
|
||||
Use frontend agents for frontend work
|
||||
```
|
||||
|
||||
**Problem**: Not specific enough. Claude won't know when to invoke agents.
|
||||
|
||||
**✅ Fix**:
|
||||
```markdown
|
||||
## Automatic Task Routing
|
||||
|
||||
WHEN user says "create [component name] component" OR "add [component name]"
|
||||
→ AUTOMATICALLY invoke: engineering/frontend-engineer
|
||||
|
||||
WHEN user says "style [component]" OR "make responsive"
|
||||
→ AUTOMATICALLY invoke: engineering:style-implementer
|
||||
```
|
||||
|
||||
### ❌ Mistake 2: Not Listing Installed Plugins
|
||||
|
||||
**Bad**:
|
||||
```markdown
|
||||
# My Project
|
||||
|
||||
## Project Patterns
|
||||
[Goes straight to patterns without listing plugins]
|
||||
```
|
||||
|
||||
**Problem**: Claude doesn't know which agents are available.
|
||||
|
||||
**✅ Fix**:
|
||||
```markdown
|
||||
## Installed Puerto Plugins
|
||||
- engineering
|
||||
- engineering
|
||||
- engineering
|
||||
|
||||
## Automatic Task Routing
|
||||
[Then routing rules that reference these plugins]
|
||||
```
|
||||
|
||||
### ❌ Mistake 3: Missing Project Patterns
|
||||
|
||||
**Bad**:
|
||||
```markdown
|
||||
## Project Patterns
|
||||
We use React and Tailwind
|
||||
```
|
||||
|
||||
**Problem**: Too vague. Agents don't know file structure, naming conventions, etc.
|
||||
|
||||
**✅ Fix**:
|
||||
```markdown
|
||||
## Project Patterns
|
||||
|
||||
### Component Structure
|
||||
- Location: `src/components/[Name].tsx`
|
||||
- Styling: Tailwind classes (see ProductCard.tsx for example)
|
||||
- Props: TypeScript interfaces
|
||||
|
||||
```typescript
|
||||
// Follow this pattern from ProductCard.tsx
|
||||
export function ProductCard({ title, price }: Props) {
|
||||
return <div className="rounded-lg shadow-md">...</div>;
|
||||
}
|
||||
```
|
||||
```
|
||||
|
||||
### ❌ Mistake 4: Information Overload
|
||||
|
||||
**Bad**:
|
||||
```markdown
|
||||
[50 pages of detailed documentation about every aspect of the project]
|
||||
```
|
||||
|
||||
**Problem**: Too much information. Claude gets overwhelmed and misses key points.
|
||||
|
||||
**✅ Fix**:
|
||||
```markdown
|
||||
## Key Points
|
||||
- Component location: `src/components/`
|
||||
- Styling: Tailwind only
|
||||
- API routes: `src/api/routes/`
|
||||
- Example component: See ProductCard.tsx
|
||||
- Example API: See src/api/routes/products.ts
|
||||
|
||||
[Focus on most important patterns, reference files for details]
|
||||
```
|
||||
|
||||
### ❌ Mistake 5: Outdated Information
|
||||
|
||||
**Bad**:
|
||||
```markdown
|
||||
## Tech Stack
|
||||
- React 16
|
||||
- Redux for state
|
||||
|
||||
[Project has since upgraded to React 18 and removed Redux]
|
||||
```
|
||||
|
||||
**Problem**: Agents generate code for the wrong stack.
|
||||
|
||||
**✅ Fix**:
|
||||
- Update when upgrading libraries
|
||||
- Update when adding/removing plugins
|
||||
- Update when changing patterns
|
||||
- Review quarterly for accuracy
|
||||
|
||||
---
|
||||
|
||||
## Complete Examples by Project Type
|
||||
|
||||
### Example 1: React SPA with REST API
|
||||
|
||||
**Scenario**: E-commerce frontend in React, backend in Node.js/Express
|
||||
|
||||
**Plugins**: engineering, engineering, engineering
|
||||
|
||||
```markdown
|
||||
# ShopHub - E-commerce Platform
|
||||
|
||||
## Project Type
|
||||
React single-page application (SPA) with Node.js REST API backend
|
||||
|
||||
## Tech Stack
|
||||
- Frontend: React 18, TypeScript, Tailwind CSS, React Query, React Router
|
||||
- Backend: Node.js 20, Express, PostgreSQL 15, Prisma ORM
|
||||
- Testing: Vitest, React Testing Library, Supertest
|
||||
- Deployment: Vercel (frontend), Railway (backend)
|
||||
|
||||
## Installed Puerto Plugins
|
||||
- engineering (frontend-engineer, state-architect, style-implementer)
|
||||
- engineering (backend-engineer, auth-implementer, api-tester)
|
||||
- engineering (api-designer, engineering)
|
||||
|
||||
## Automatic Task Routing
|
||||
|
||||
### Frontend Tasks
|
||||
WHEN creating components → AUTOMATICALLY invoke engineering/frontend-engineer
|
||||
WHEN implementing state → AUTOMATICALLY invoke engineering:state-architect
|
||||
WHEN styling → AUTOMATICALLY invoke engineering:style-implementer
|
||||
|
||||
### Backend Tasks
|
||||
WHEN creating endpoints → AUTOMATICALLY invoke engineering/backend-engineer
|
||||
WHEN adding authentication → AUTOMATICALLY invoke engineering/backend-engineer
|
||||
WHEN designing APIs → AUTOMATICALLY invoke engineering:api-designer
|
||||
|
||||
### Database Tasks
|
||||
WHEN designing schemas → AUTOMATICALLY invoke engineering:engineering
|
||||
|
||||
## Project Patterns
|
||||
|
||||
### Component Structure
|
||||
- Location: `src/components/[ComponentName].tsx`
|
||||
- Styling: Tailwind classes only (no CSS modules)
|
||||
- Props: TypeScript interfaces with JSDoc
|
||||
- Exports: Named exports (not default)
|
||||
- Example: See `src/components/ProductCard.tsx`
|
||||
|
||||
### API Structure
|
||||
- Routes: `src/api/routes/[resource].ts`
|
||||
- Validation: Zod schemas
|
||||
- Auth: JWT middleware in `src/api/middleware/auth.ts`
|
||||
- Example: See `src/api/routes/products.ts`
|
||||
|
||||
### State Management
|
||||
- Global state: React Query for server state
|
||||
- Local state: useState/useReducer
|
||||
- Auth state: Custom useAuth hook
|
||||
- No Redux (explicitly avoided)
|
||||
|
||||
## Domain Knowledge
|
||||
- Products have variants (size, color) as separate SKUs
|
||||
- Prices in cents (integer) to avoid floating-point errors
|
||||
- Cart expires after 24 hours (guest) or 30 days (authenticated)
|
||||
- Payment via Stripe webhooks
|
||||
- GDPR compliance: no PII in logs
|
||||
```
|
||||
|
||||
### Example 2: Node.js Microservices
|
||||
|
||||
**Scenario**: Backend-only microservices architecture
|
||||
|
||||
**Plugins**: engineering, engineering, engineering/devops-engineer, engineering
|
||||
|
||||
```markdown
|
||||
# PaymentProcessor - Microservices Platform
|
||||
|
||||
## Project Type
|
||||
Node.js microservices architecture with event-driven communication
|
||||
|
||||
## Tech Stack
|
||||
- Runtime: Node.js 20, TypeScript
|
||||
- Framework: Express, NestJS (auth service)
|
||||
- Message Queue: RabbitMQ
|
||||
- Databases: PostgreSQL (transactions), Redis (cache), MongoDB (logs)
|
||||
- Testing: Jest, Supertest
|
||||
- Deployment: Kubernetes (AWS EKS)
|
||||
|
||||
## Installed Puerto Plugins
|
||||
- engineering (backend-engineer, auth-implementer, api-tester)
|
||||
- engineering (api-designer, engineering, system-architect)
|
||||
- engineering/devops-engineer (cicd-builder, deployment-orchestrator, infrastructure-manager)
|
||||
- engineering (schema-designer, migration-manager, query-optimizer)
|
||||
|
||||
## Automatic Task Routing
|
||||
|
||||
### API Development
|
||||
WHEN creating endpoints → AUTOMATICALLY invoke engineering/backend-engineer
|
||||
WHEN implementing auth → AUTOMATICALLY invoke engineering/backend-engineer
|
||||
WHEN writing API tests → AUTOMATICALLY invoke engineering:api-tester
|
||||
|
||||
### Architecture
|
||||
WHEN designing APIs → AUTOMATICALLY invoke engineering:api-designer
|
||||
WHEN designing schemas → AUTOMATICALLY invoke engineering:engineering
|
||||
WHEN designing system architecture → AUTOMATICALLY invoke engineering:system-architect
|
||||
|
||||
### Database
|
||||
WHEN creating migrations → AUTOMATICALLY invoke engineering:migration-manager
|
||||
WHEN optimizing queries → AUTOMATICALLY invoke engineering:query-optimizer
|
||||
|
||||
### DevOps
|
||||
WHEN setting up CI/CD → AUTOMATICALLY invoke engineering/devops-engineer:cicd-builder
|
||||
WHEN deploying → AUTOMATICALLY invoke engineering/devops-engineer:deployment-orchestrator
|
||||
WHEN creating infrastructure → AUTOMATICALLY invoke engineering/devops-engineer:infrastructure-manager
|
||||
|
||||
## Project Patterns
|
||||
|
||||
### Service Structure
|
||||
```
|
||||
services/
|
||||
├── auth-service/ # NestJS service
|
||||
├── payment-service/ # Express service
|
||||
├── notification-service/ # Express service
|
||||
└── shared/ # Shared libraries
|
||||
```
|
||||
|
||||
### API Conventions
|
||||
- All services expose: `/health`, `/metrics`, `/ready`
|
||||
- OpenAPI spec required for all services
|
||||
- REST for sync, RabbitMQ for async
|
||||
- Correlation IDs for request tracing
|
||||
|
||||
### Event Patterns
|
||||
```typescript
|
||||
// Publisher pattern
|
||||
await messageQueue.publish('payment.processed', {
|
||||
correlationId: req.id,
|
||||
payload: { orderId, amount, status }
|
||||
});
|
||||
|
||||
// Consumer pattern
|
||||
messageQueue.subscribe('payment.processed', async (message) => {
|
||||
// Handle event
|
||||
});
|
||||
```
|
||||
|
||||
### Database Patterns
|
||||
- PostgreSQL for transactional data (ACID required)
|
||||
- MongoDB for append-only logs
|
||||
- Redis for caching and session storage
|
||||
- Migrations: Knex.js for PostgreSQL
|
||||
- Connection pooling: 20 max connections per service
|
||||
|
||||
## Domain Knowledge
|
||||
- Payment processing: PCI DSS compliance required
|
||||
- Idempotency: All payment endpoints must be idempotent (use idempotency keys)
|
||||
- Event ordering: Use RabbitMQ with consistent hash exchange
|
||||
- Retry logic: Exponential backoff with max 3 retries
|
||||
- Circuit breaker: Fail fast after 5 consecutive errors
|
||||
```
|
||||
|
||||
### Example 3: Full-Stack Next.js App
|
||||
|
||||
**Scenario**: Next.js with API routes and PostgreSQL
|
||||
|
||||
**Plugins**: engineering, engineering, engineering
|
||||
|
||||
```markdown
|
||||
# TaskMaster - Project Management SaaS
|
||||
|
||||
## Project Type
|
||||
Full-stack Next.js 14 application with App Router and server actions
|
||||
|
||||
## Tech Stack
|
||||
- Framework: Next.js 14 (App Router), TypeScript, React 18
|
||||
- Styling: Tailwind CSS, Shadcn UI components
|
||||
- Database: PostgreSQL 15 with Drizzle ORM
|
||||
- Auth: NextAuth.js v5
|
||||
- Deployment: Vercel
|
||||
|
||||
## Installed Puerto Plugins
|
||||
- engineering (frontend-engineer, state-architect, style-implementer)
|
||||
- engineering (backend-engineer, auth-implementer)
|
||||
- engineering (schema-designer, migration-manager, query-optimizer)
|
||||
|
||||
## Automatic Task Routing
|
||||
|
||||
### Frontend
|
||||
WHEN creating components → AUTOMATICALLY invoke engineering/frontend-engineer
|
||||
WHEN implementing client state → AUTOMATICALLY invoke engineering:state-architect
|
||||
|
||||
### Backend
|
||||
WHEN creating API routes → AUTOMATICALLY invoke engineering/backend-engineer
|
||||
WHEN creating server actions → AUTOMATICALLY invoke engineering/backend-engineer
|
||||
WHEN implementing auth → AUTOMATICALLY invoke engineering/backend-engineer
|
||||
|
||||
### Database
|
||||
WHEN designing schemas → AUTOMATICALLY invoke engineering:schema-designer
|
||||
WHEN creating migrations → AUTOMATICALLY invoke engineering:migration-manager
|
||||
WHEN optimizing queries → AUTOMATICALLY invoke engineering:query-optimizer
|
||||
|
||||
## Project Patterns
|
||||
|
||||
### File Structure (App Router)
|
||||
```
|
||||
app/
|
||||
├── (auth)/ # Auth group
|
||||
│ ├── login/
|
||||
│ └── signup/
|
||||
├── (dashboard)/ # Protected group
|
||||
│ ├── projects/
|
||||
│ └── tasks/
|
||||
├── api/ # API routes
|
||||
└── actions/ # Server actions
|
||||
components/
|
||||
├── ui/ # Shadcn components
|
||||
└── [feature]/ # Feature components
|
||||
```
|
||||
|
||||
### Component Patterns
|
||||
- Use Shadcn UI components as base
|
||||
- Server Components by default
|
||||
- Client Components only when needed (mark with 'use client')
|
||||
- Co-locate components with routes when route-specific
|
||||
|
||||
### Server Actions Pattern
|
||||
```typescript
|
||||
// app/actions/tasks.ts
|
||||
'use server';
|
||||
|
||||
import { revalidatePath } from 'next/cache';
|
||||
import { auth } from '@/lib/auth';
|
||||
|
||||
export async function createTask(formData: FormData) {
|
||||
const session = await auth();
|
||||
if (!session) throw new Error('Unauthorized');
|
||||
|
||||
// Business logic
|
||||
|
||||
revalidatePath('/dashboard/tasks');
|
||||
}
|
||||
```
|
||||
|
||||
### Database Patterns
|
||||
- Drizzle ORM for type-safe queries
|
||||
- Schemas in: `db/schema.ts`
|
||||
- Migrations in: `db/migrations/`
|
||||
- Use transactions for multi-table operations
|
||||
- Index frequently queried columns
|
||||
|
||||
## Domain Knowledge
|
||||
- Multi-tenancy: All data scoped to workspaceId
|
||||
- Permissions: Role-based (owner, admin, member)
|
||||
- Real-time: Use Supabase Realtime for live updates
|
||||
- Webhooks: Stripe for billing, Slack for notifications
|
||||
- Data retention: Soft delete with 30-day retention before hard delete
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Advanced Patterns
|
||||
|
||||
### Context-Specific Routing
|
||||
|
||||
Route differently based on file location:
|
||||
|
||||
```markdown
|
||||
## Context-Specific Routing
|
||||
|
||||
WHEN working in `src/admin/` directory
|
||||
→ Use admin-specific patterns (verbose logging, strict validation)
|
||||
|
||||
WHEN working in `src/public-api/` directory
|
||||
→ Use public API patterns (rate limiting, thorough docs)
|
||||
```
|
||||
|
||||
### Conditional Plugin Usage
|
||||
|
||||
```markdown
|
||||
## Conditional Agent Usage
|
||||
|
||||
WHEN implementing payment features
|
||||
→ MUST invoke: engineering/backend-engineer (for PCI compliance)
|
||||
→ MUST add: Audit logging
|
||||
|
||||
WHEN implementing user data features
|
||||
→ MUST consider: GDPR compliance (no PII in logs)
|
||||
```
|
||||
|
||||
### Reference External Docs
|
||||
|
||||
```markdown
|
||||
## Reference Documentation
|
||||
|
||||
For API design patterns: See `docs/api-guidelines.md`
|
||||
For component library: See Storybook at `http://localhost:6006`
|
||||
For database schema: See ER diagram at `docs/schema.png`
|
||||
```
|
||||
|
||||
### Plugin Combinations for Complex Tasks
|
||||
|
||||
```markdown
|
||||
## Complex Task Routing
|
||||
|
||||
WHEN user says "create new feature with [frontend + backend]"
|
||||
→ First invoke: engineering:system-architect (design architecture)
|
||||
→ Then invoke: engineering/frontend-engineer (build UI)
|
||||
→ Then invoke: engineering/backend-engineer (build API)
|
||||
→ Then invoke: engineering:schema-designer (design schema)
|
||||
|
||||
This ensures proper architecture before implementation.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
Use this checklist when validating CLAUDE.md files:
|
||||
|
||||
### Structure Validation
|
||||
- [ ] Has Project Type section
|
||||
- [ ] Has Tech Stack section
|
||||
- [ ] Has Installed Puerto Plugins section
|
||||
- [ ] Has Automatic Task Routing section
|
||||
- [ ] Has Project Patterns section (optional but recommended)
|
||||
- [ ] Has Domain Knowledge section (optional but recommended)
|
||||
|
||||
### Routing Rules Validation
|
||||
- [ ] Uses WHEN/AUTOMATICALLY keywords
|
||||
- [ ] Routing rules are specific (not vague)
|
||||
- [ ] Includes trigger phrases users might say
|
||||
- [ ] Uses OR for alternative phrasings
|
||||
- [ ] Groups rules by logical categories
|
||||
- [ ] References installed plugins correctly
|
||||
|
||||
### Pattern Validation
|
||||
- [ ] Includes concrete code examples
|
||||
- [ ] References actual project files
|
||||
- [ ] Specifies file locations
|
||||
- [ ] Documents naming conventions
|
||||
- [ ] Shows technology usage (not just lists)
|
||||
|
||||
### Domain Knowledge Validation
|
||||
- [ ] Includes business rules if applicable
|
||||
- [ ] Documents critical constraints
|
||||
- [ ] Lists integration points
|
||||
- [ ] Explains "why" not just "what"
|
||||
|
||||
### Quality Validation
|
||||
- [ ] Concise (not information overload)
|
||||
- [ ] Up to date (matches current tech stack)
|
||||
- [ ] Actionable (agents can follow patterns)
|
||||
- [ ] Consistent (formatting throughout)
|
||||
|
||||
---
|
||||
|
||||
## Maintenance Best Practices
|
||||
|
||||
### Keep It Updated
|
||||
|
||||
Track changes:
|
||||
```markdown
|
||||
## Change Log
|
||||
- 2025-11-01: Added engineering plugin
|
||||
- 2025-10-15: Migrated from Redux to React Query
|
||||
- 2025-09-20: Upgraded to React 18
|
||||
```
|
||||
|
||||
### Version Control
|
||||
|
||||
Commit to repository:
|
||||
```bash
|
||||
git add CLAUDE.md
|
||||
git commit -m "docs: add CLAUDE.md with routing rules for Puerto plugins"
|
||||
```
|
||||
|
||||
### Iterative Improvement
|
||||
|
||||
1. **Start simple**: Basic routing rules and patterns
|
||||
2. **Observe**: See how Claude uses it
|
||||
3. **Refine**: Add specificity where Claude gets confused
|
||||
4. **Expand**: Add domain knowledge as needed
|
||||
|
||||
---
|
||||
|
||||
## Summary: Key Principles
|
||||
|
||||
1. **CLAUDE.md guides agent selection** - Without it, Claude won't automatically use installed plugins
|
||||
|
||||
2. **Be specific in routing rules** - Use WHEN/AUTOMATICALLY format with concrete task descriptions
|
||||
|
||||
3. **Document patterns with examples** - Show actual code from the project that agents should follow
|
||||
|
||||
4. **Include domain knowledge** - Business context helps agents make appropriate decisions
|
||||
|
||||
5. **Keep it maintained** - Update when changing tech stack or patterns
|
||||
|
||||
6. **Test and iterate** - Start simple, observe behavior, refine based on results
|
||||
|
||||
---
|
||||
|
||||
**End of CLAUDE.md Syntax Specification**
|
||||
|
||||
This skill should be loaded at the start of every claude-md-master agent invocation to ensure complete and accurate knowledge of CLAUDE.md structure, syntax, and best practices.
|
||||
Reference in New Issue
Block a user