Requirements → Design → Code → Test → Review → Deploy

Requirements → Brainstorm (3-5 variants) → User selects → Refine → Storybook → Components

Analyze Folder → Identify Type → Write CLAUDE.md → Verify

# Cross-app imports - ALWAYS with alias
from apps.orders import models as order_models
from apps.users import services as user_services

# Own modules (relative)
from .models import User
from . import constants

# services/activation.py
def activate_user_item(
    user: User,
    item_code: str,
    *,
    activated_by: Admin,
) -> Item:
    """Activate item for user."""
    item = Item.objects.get(code=item_code)
    item.user = user
    item.is_active = True
    item.save(update_fields=['user', 'is_active', 'updated_at'])
    return item

def create_order(
    user: User,
    amount: Decimal,
    order_type: str,
    *,  # Keyword-only after
    item: Item | None = None,
    notify: bool = True,
) -> Order:
    ...

class ItemActivationView(APIView):
    def post(self, request):
        serializer = ItemActivationRequest(data=request.data)
        serializer.is_valid(raise_exception=True)
        item = services.activate_user_item(
            user=request.user,
            item_code=serializer.validated_data['item_code'],
        )
        return Response(ItemResponse(item).data)

What does the function do?
│
├─ Changes DB (CREATE/UPDATE/DELETE)?
│  └─ services/
├─ Makes external API calls?
│  └─ services/ or integrations/
├─ Pure function (validation, calculation)?
│  └─ utils/
└─ Data transformation?
   └─ utils/

class BaseModel(models.Model):
    uid = models.UUIDField(default=uuid.uuid4, unique=True)
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

    class Meta:
        abstract = True

@pytest.mark.django_db
def test_activate_item_success(user, item):
    result = services.activate_user_item(
        user=user,
        item_code=item.code,
    )
    assert result.is_active is True
    assert result.user == user

from fastapi import FastAPI, Depends, HTTPException
from pydantic import BaseModel

app = FastAPI()

class ItemCreate(BaseModel):
    name: str
    price: float

@app.post("/items/", response_model=ItemResponse)
async def create_item(
    item: ItemCreate,
    db: Session = Depends(get_db),
    current_user: User = Depends(get_current_user),
):
    return await services.create_item(db, item, current_user)

project/
├── pyproject.toml
├── src/
│   └── package/
│       ├── __init__.py
│       ├── main.py
│       └── models/
├── tests/
│   ├── conftest.py
│   └── test_*.py
├── .env.example
└── README.md

from typing import Optional, List, Dict

def process_users(
    users: List[User],
    options: Optional[Dict[str, str]] = None,
) -> List[ProcessedUser]:
    ...

// src/components/Button/Button.tsx
interface ButtonProps {
  variant: 'primary' | 'secondary';
  children: React.ReactNode;
  onClick?: () => void;
}

export const Button: React.FC<ButtonProps> = ({
  variant,
  children,
  onClick,
}) => {
  return (
    <button className={styles[variant]} onClick={onClick}>
      {children}
    </button>
  );
};

// hooks/useUser.ts
export function useUser(userId: string) {
  const [user, setUser] = useState<User | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<Error | null>(null);

  useEffect(() => {
    fetchUser(userId)
      .then(setUser)
      .catch(setError)
      .finally(() => setLoading(false));
  }, [userId]);

  return { user, loading, error };
}

// tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true
  }
}

project/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts
│   ├── routes/
│   ├── services/
│   └── models/
├── tests/
│   └── *.test.ts
└── .env.example

app/
├── layout.tsx       # Root layout
├── page.tsx         # Home page
├── (auth)/
│   ├── login/
│   │   └── page.tsx
│   └── register/
│       └── page.tsx
├── dashboard/
│   ├── layout.tsx   # Dashboard layout
│   └── page.tsx
└── api/
    └── users/
        └── route.ts

// Component test with Testing Library
import { render, screen } from '@testing-library/react';
import { Button } from './Button';

test('renders button with text', () => {
  render(<Button variant="primary">Click me</Button>);
  expect(screen.getByText('Click me')).toBeInTheDocument();
});

project/
├── cmd/
│   └── server/
│       └── main.go
├── internal/
│   ├── handlers/
│   ├── services/
│   └── models/
├── pkg/           # Reusable packages
├── go.mod
└── go.sum

func GetUser(id string) (*User, error) {
    user, err := db.FindUser(id)
    if err != nil {
        return nil, fmt.Errorf("get user %s: %w", id, err)
    }
    return user, nil
}

// Define interface where it's used
type UserRepository interface {
    Find(id string) (*User, error)
    Save(user *User) error
}

// Implementation
type PostgresUserRepo struct {
    db *sql.DB
}

func (r *PostgresUserRepo) Find(id string) (*User, error) {
    // implementation
}

// Worker pool pattern
func worker(jobs <-chan Job, results chan<- Result) {
    for job := range jobs {
        results <- process(job)
    }
}

func main() {
    jobs := make(chan Job, 100)
    results := make(chan Result, 100)

    for w := 1; w <= 3; w++ {
        go worker(jobs, results)
    }
}

RSpec.describe UserService do
  describe '#create' do
    let(:params) { { name: 'John', email: '[email protected]' } }

    it 'creates user with valid params' do
      result = described_class.create(params)
      expect(result).to be_success
    end
  end
end

// Service Pattern
class UserService
{
    public function create(array $data): User
    {
        return User::create($data);
    }
}

// Controller
class UserController extends Controller
{
    public function store(CreateUserRequest $request, UserService $service)
    {
        $user = $service->create($request->validated());
        return new UserResource($user);
    }
}

class UserTest extends TestCase
{
    public function test_user_can_be_created(): void
    {
        $response = $this->postJson('/api/users', [
            'name' => 'John',
            'email' => '[email protected]',
        ]);

        $response->assertStatus(201);
    }
}

@Service
@RequiredArgsConstructor
public class UserService {
    private final UserRepository userRepository;

    public User createUser(CreateUserDto dto) {
        User user = User.builder()
            .name(dto.getName())
            .email(dto.getEmail())
            .build();
        return userRepository.save(user);
    }
}

@SpringBootTest
class UserServiceTest {
    @Autowired
    private UserService userService;

    @Test
    void shouldCreateUser() {
        CreateUserDto dto = new CreateUserDto("John", "[email protected]");
        User result = userService.createUser(dto);
        assertThat(result.getName()).isEqualTo("John");
    }
}

public class UserService : IUserService
{
    private readonly IUserRepository _repository;

    public UserService(IUserRepository repository)
    {
        _repository = repository;
    }

    public async Task<User> CreateAsync(CreateUserDto dto)
    {
        var user = new User { Name = dto.Name, Email = dto.Email };
        return await _repository.AddAsync(user);
    }
}

public class UserServiceTests
{
    [Fact]
    public async Task CreateAsync_ShouldReturnUser()
    {
        var mockRepo = new Mock<IUserRepository>();
        var service = new UserService(mockRepo.Object);

        var result = await service.CreateAsync(new CreateUserDto("John", "[email protected]"));

        Assert.Equal("John", result.Name);
    }
}

project/
├── Cargo.toml
├── src/
│   ├── main.rs
│   ├── lib.rs
│   └── modules/
│       ├── mod.rs
│       └── user.rs
├── tests/
│   └── integration_test.rs
└── examples/

use thiserror::Error;

#[derive(Error, Debug)]
pub enum UserError {
    #[error("user not found: {0}")]
    NotFound(String),
    #[error("database error")]
    Database(#[from] sqlx::Error),
}

pub fn get_user(id: &str) -> Result<User, UserError> {
    db.find_user(id)
        .map_err(|e| UserError::Database(e))?
        .ok_or(UserError::NotFound(id.to_string()))
}

use tokio;

#[tokio::main]
async fn main() {
    let result = fetch_data().await;
    println!("{:?}", result);
}

async fn fetch_data() -> Result<Data, Error> {
    let response = reqwest::get("https://api.example.com/data").await?;
    response.json().await
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_create_user() {
        let user = User::new("John", "[email protected]");
        assert_eq!(user.name, "John");
    }

    #[tokio::test]
    async fn test_async_fetch() {
        let result = fetch_data().await;
        assert!(result.is_ok());
    }
}

-- Up migration
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    email VARCHAR(255) UNIQUE NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);

-- Down migration
DROP TABLE users;

# Bad: N+1 queries
users = User.objects.all()
for user in users:
    print(user.orders.count())  # New query each iteration

# Good: Prefetch
users = User.objects.prefetch_related('orders').all()
for user in users:
    print(len(user.orders.all()))  # Uses prefetched data

// Success
{
  "data": { ... },
  "meta": { "page": 1, "total": 100 }
}

// Error
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "details": [{ "field": "email", "error": "invalid_format" }]
  }
}

# Celery example
@celery_app.task
def send_welcome_email(user_id: int):
    user = User.objects.get(id=user_id)
    email_service.send(user.email, "Welcome!")

# Usage
send_welcome_email.delay(user.id)

import structlog

logger = structlog.get_logger()

logger.info(
    "user_created",
    user_id=user.id,
    email=user.email,
    source="api"
)

# Multi-stage build
FROM python:3.11-slim AS builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --user -r requirements.txt

FROM python:3.11-slim
WORKDIR /app
COPY --from=builder /root/.local /root/.local
COPY . .
ENV PATH=/root/.local/bin:$PATH
CMD ["python", "main.py"]

services:
  app:
    build: .
    ports:
      - "8000:8000"
    depends_on:
      - db
    environment:
      - DATABASE_URL=postgres://postgres:postgres@db:5432/app

  db:
    image: postgres:15
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: app
  template:
    metadata:
      labels:
        app: app
    spec:
      containers:
      - name: app
        image: app:latest
        ports:
        - containerPort: 8000
        resources:
          limits:
            memory: "256Mi"
            cpu: "500m"

apiVersion: v1
kind: Service
metadata:
  name: app
spec:
  selector:
    app: app
  ports:
  - port: 80
    targetPort: 8000
  type: ClusterIP

apiVersion: v1
kind: Secret
metadata:
  name: app-secrets
type: Opaque
data:
  DATABASE_PASSWORD: base64encoded

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  LOG_LEVEL: "info"

terraform/
├── modules/
│   ├── vpc/
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   └── outputs.tf
│   └── rds/
├── environments/
│   ├── dev/
│   │   └── main.tf
│   └── prod/
│       └── main.tf
└── backend.tf

terraform {
  backend "s3" {
    bucket         = "terraform-state"
    key            = "prod/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true
    dynamodb_table = "terraform-locks"
  }
}

VPC (10.0.0.0/16)
├── Public Subnets (10.0.1.0/24, 10.0.2.0/24)
│   └── NAT Gateway, ALB
├── Private Subnets (10.0.10.0/24, 10.0.11.0/24)
│   └── Application servers
└── Database Subnets (10.0.20.0/24, 10.0.21.0/24)
    └── RDS, ElastiCache

# GitHub Actions example
name: CI/CD
on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: npm test

  deploy:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - name: Deploy
        run: ./deploy.sh

                    ┌─────────────┐
                    │    ALB      │
                    └──────┬──────┘
                           │
              ┌────────────┴────────────┐
              │                         │
        ┌─────▼─────┐            ┌──────▼─────┐
        │   Blue    │            │   Green    │
        │  (live)   │            │   (new)    │
        └───────────┘            └────────────┘

1. Deploy to Green
2. Test Green
3. Switch ALB to Green
4. Blue becomes staging

Traffic Split:
1. 5% → New version (canary)
   95% → Old version
2. Monitor metrics
3. If OK: 25% → 50% → 100%
4. If error: rollback to 0%

# k6 example
import http from 'k6/http';

export const options = {
  stages: [
    { duration: '5m', target: 100 },  // Ramp up
    { duration: '10m', target: 100 }, // Stay
    { duration: '5m', target: 0 },    // Ramp down
  ],
};

export default function () {
  http.get('https://api.example.com/');
}

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://app:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /static/ {
        alias /var/www/static/;
        expires 30d;
    }

    gzip on;
    gzip_types text/plain application/json;
}

ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers on;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 10m;

add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

Primary (write)
    │
    ├─► Replica 1 (read)
    └─► Replica 2 (read)

Auto-failover: Primary fails → Replica promoted

# {Folder Name}

{One-sentence description}

## Overview
{2-3 sentences explaining what this folder contains}

## Structure
| Path | Purpose |
|------|---------|
| `file.py` | Description |

## Key Concepts
- **Concept1**: Explanation

## Entry Points
- `main_file.py` — Primary entry point

## Common Operations
### Operation 1
```bash
command example

**Size Guidelines:**
- Target: 100-150 lines
- Maximum: 200 lines

**Agent:** faion-code-agent

#### M-DEV-066: Storybook Setup

**Problem:** No component documentation.

**Framework:**
```typescript
// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta: Meta<typeof Button> = {
  title: 'Components/Button',
  component: Button,
};

export default meta;
type Story = StoryObj<typeof Button>;

export const Primary: Story = {
  args: {
    variant: 'primary',
    children: 'Click me',
  },
};

// tokens/
export const colors = {
  primary: {
    50: '#f0f9ff',
    500: '#3b82f6',
    900: '#1e3a8a',
  },
  semantic: {
    success: '#22c55e',
    error: '#ef4444',
    warning: '#f59e0b',
  },
};

export const spacing = {
  0: '0',
  1: '0.25rem',
  2: '0.5rem',
  4: '1rem',
  8: '2rem',
};

src/components/{Name}/
├── {Name}.tsx           # Component
├── {Name}.stories.tsx   # Storybook
├── {Name}.test.tsx      # Tests
├── {Name}.module.css    # Styles
└── index.ts             # Export

Task(subagent_type="faion-code-agent",
     prompt=f"Implement {feature} using {framework}")

Task(subagent_type="faion-test-agent",
     prompt=f"Write tests for {feature}")

# Phase 1: Brainstorming
Task(subagent_type="faion-frontend-brainstormer-agent",
     prompt=f"Create 3-5 DISTINCT design variants for: {requirements}")

# Phase 2: Storybook
Task(subagent_type="faion-storybook-agent",
     prompt=f"Setup Storybook for {project}")

# Phase 3: Components
Task(subagent_type="faion-frontend-component-agent",
     prompt=f"Develop {component_name} with story file")

Task(subagent_type="faion-devops-agent",
     prompt=f"Setup {infra_component} for {project}")