Project Guidelines Skill (Example)

This is an example of a project-specific skill. Use this as a template for your own projects.

Based on a real production application: Zenith - AI-powered customer discovery platform.

When to Use

Reference this skill when working on the specific project it's designed for. Project skills contain:

• Architecture overview
• File structure
• Code patterns
• Testing requirements
• Deployment workflow

Architecture Overview

Tech Stack:

• Frontend: Next.js 15 (App Router), TypeScript, React
• Backend: FastAPI (Python), Pydantic models
• Database: Supabase (PostgreSQL)
• AI: Claude API with tool calling and structured output
• Deployment: Google Cloud Run
• Testing: Playwright (E2E), pytest (backend), React Testing Library

Services:

┌─────────────────────────────────────────────────────────────┐
│                         Frontend                            │
│  Next.js 15 + TypeScript + TailwindCSS                     │
│  Deployed: Vercel / Cloud Run                              │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                         Backend                             │
│  FastAPI + Python 3.11 + Pydantic                          │
│  Deployed: Cloud Run                                       │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
        ┌──────────┐   ┌──────────┐   ┌──────────┐
        │ Supabase │   │  Claude  │   │  Redis   │
        │ Database │   │   API    │   │  Cache   │
        └──────────┘   └──────────┘   └──────────┘

File Structure

project/
├── frontend/
│   └── src/
│       ├── app/              # Next.js app router pages
│       │   ├── api/          # API routes
│       │   ├── (auth)/       # Auth-protected routes
│       │   └── workspace/    # Main app workspace
│       ├── components/       # React components
│       │   ├── ui/           # Base UI components
│       │   ├── forms/        # Form components
│       │   └── layouts/      # Layout components
│       ├── hooks/            # Custom React hooks
│       ├── lib/              # Utilities
│       ├── types/            # TypeScript definitions
│       └── config/           # Configuration
│
├── backend/
│   ├── routers/              # FastAPI route handlers
│   ├── models.py             # Pydantic models
│   ├── main.py               # FastAPI app entry
│   ├── auth_system.py        # Authentication
│   ├── database.py           # Database operations
│   ├── services/             # Business logic
│   └── tests/                # pytest tests
│
├── deploy/                   # Deployment configs
├── docs/                     # Documentation
└── scripts/                  # Utility scripts

Code Patterns

API Response Format (FastAPI)

python
1from pydantic import BaseModel
2from typing import Generic, TypeVar, Optional
3
4T = TypeVar('T')
5
6class ApiResponse(BaseModel, Generic[T]):
7    success: bool
8    data: Optional[T] = None
9    error: Optional[str] = None
10
11    @classmethod
12    def ok(cls, data: T) -> "ApiResponse[T]":
13        return cls(success=True, data=data)
14
15    @classmethod
16    def fail(cls, error: str) -> "ApiResponse[T]":
17        return cls(success=False, error=error)

Frontend API Calls (TypeScript)

typescript
1interface ApiResponse<T> {
2  success: boolean
3  data?: T
4  error?: string
5}
6
7async function fetchApi<T>(
8  endpoint: string,
9  options?: RequestInit
10): Promise<ApiResponse<T>> {
11  try {
12    const response = await fetch(`/api${endpoint}`, {
13      ...options,
14      headers: {
15        'Content-Type': 'application/json',
16        ...options?.headers,
17      },
18    })
19
20    if (!response.ok) {
21      return { success: false, error: `HTTP ${response.status}` }
22    }
23
24    return await response.json()
25  } catch (error) {
26    return { success: false, error: String(error) }
27  }
28}

Claude AI Integration (Structured Output)

python
1from anthropic import Anthropic
2from pydantic import BaseModel
3
4class AnalysisResult(BaseModel):
5    summary: str
6    key_points: list[str]
7    confidence: float
8
9async def analyze_with_claude(content: str) -> AnalysisResult:
10    client = Anthropic()
11
12    response = client.messages.create(
13        model="claude-sonnet-4-5-20250514",
14        max_tokens=1024,
15        messages=[{"role": "user", "content": content}],
16        tools=[{
17            "name": "provide_analysis",
18            "description": "Provide structured analysis",
19            "input_schema": AnalysisResult.model_json_schema()
20        }],
21        tool_choice={"type": "tool", "name": "provide_analysis"}
22    )
23
24    # Extract tool use result
25    tool_use = next(
26        block for block in response.content
27        if block.type == "tool_use"
28    )
29
30    return AnalysisResult(**tool_use.input)

Custom Hooks (React)

typescript
1import { useState, useCallback } from 'react'
2
3interface UseApiState<T> {
4  data: T | null
5  loading: boolean
6  error: string | null
7}
8
9export function useApi<T>(
10  fetchFn: () => Promise<ApiResponse<T>>
11) {
12  const [state, setState] = useState<UseApiState<T>>({
13    data: null,
14    loading: false,
15    error: null,
16  })
17
18  const execute = useCallback(async () => {
19    setState(prev => ({ ...prev, loading: true, error: null }))
20
21    const result = await fetchFn()
22
23    if (result.success) {
24      setState({ data: result.data!, loading: false, error: null })
25    } else {
26      setState({ data: null, loading: false, error: result.error! })
27    }
28  }, [fetchFn])
29
30  return { ...state, execute }
31}

Testing Requirements

Backend (pytest)

bash
1# Run all tests
2poetry run pytest tests/
3
4# Run with coverage
5poetry run pytest tests/ --cov=. --cov-report=html
6
7# Run specific test file
8poetry run pytest tests/test_auth.py -v

Test structure:

python
1import pytest
2from httpx import AsyncClient
3from main import app
4
5@pytest.fixture
6async def client():
7    async with AsyncClient(app=app, base_url="http://test") as ac:
8        yield ac
9
10@pytest.mark.asyncio
11async def test_health_check(client: AsyncClient):
12    response = await client.get("/health")
13    assert response.status_code == 200
14    assert response.json()["status"] == "healthy"

Frontend (React Testing Library)

bash
1# Run tests
2npm run test
3
4# Run with coverage
5npm run test -- --coverage
6
7# Run E2E tests
8npm run test:e2e

Test structure:

typescript
1import { render, screen, fireEvent } from '@testing-library/react'
2import { WorkspacePanel } from './WorkspacePanel'
3
4describe('WorkspacePanel', () => {
5  it('renders workspace correctly', () => {
6    render(<WorkspacePanel />)
7    expect(screen.getByRole('main')).toBeInTheDocument()
8  })
9
10  it('handles session creation', async () => {
11    render(<WorkspacePanel />)
12    fireEvent.click(screen.getByText('New Session'))
13    expect(await screen.findByText('Session created')).toBeInTheDocument()
14  })
15})

Deployment Workflow

Pre-Deployment Checklist

• All tests passing locally
• npm run build succeeds (frontend)
• poetry run pytest passes (backend)
• No hardcoded secrets
• Environment variables documented
• Database migrations ready

Deployment Commands

bash
1# Build and deploy frontend
2cd frontend && npm run build
3gcloud run deploy frontend --source .
4
5# Build and deploy backend
6cd backend
7gcloud run deploy backend --source .

Environment Variables

bash
1# Frontend (.env.local)
2NEXT_PUBLIC_API_URL=https://api.example.com
3NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
4NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
5
6# Backend (.env)
7DATABASE_URL=postgresql://...
8ANTHROPIC_API_KEY=sk-ant-...
9SUPABASE_URL=https://xxx.supabase.co
10SUPABASE_KEY=eyJ...

Critical Rules

1. No emojis in code, comments, or documentation
2. Immutability - never mutate objects or arrays
3. TDD - write tests before implementation
4. 80% coverage minimum
5. Many small files - 200-400 lines typical, 800 max
6. No console.log in production code
7. Proper error handling with try/catch
8. Input validation with Pydantic/Zod

Related Skills

• coding-standards.md - General coding best practices
• backend-patterns.md - API and database patterns
• frontend-patterns.md - React and Next.js patterns
• tdd-workflow/ - Test-driven development methodology