- 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)
from
pydantic
import
BaseModel
from
typing
import
Generic
,
TypeVar
,
Optional
T
=
TypeVar
(
'T'
)
class
ApiResponse
(
BaseModel
,
Generic
[
T
]
)
:
success
:
bool
data
:
Optional
[
T
]
=
None
error
:
Optional
[
str
]
=
None
@classmethod
def
ok
(
cls
,
data
:
T
)
-
"ApiResponse[T]" : return cls ( success = True , data = data ) @classmethod def fail ( cls , error : str ) -
"ApiResponse[T]" : return cls ( success = False , error = error ) Frontend API Calls (TypeScript) interface ApiResponse < T
{ success : boolean data ? : T error ? : string } async function fetchApi < T
( endpoint : string , options ? : RequestInit ) : Promise < ApiResponse < T
{ try { const response = await fetch (
/api ${ endpoint }, { ... options , headers : { 'Content-Type' : 'application/json' , ... options ?. headers , } , } ) if ( ! response . ok ) { return { success : false , error :HTTP ${ response . status }} } return await response . json ( ) } catch ( error ) { return { success : false , error : String ( error ) } } } Claude AI Integration (Structured Output) from anthropic import Anthropic from pydantic import BaseModel class AnalysisResult ( BaseModel ) : summary : str key_points : list [ str ] confidence : float async def analyze_with_claude ( content : str ) -AnalysisResult : client = Anthropic ( ) response = client . messages . create ( model = "claude-sonnet-4-5-20250514" , max_tokens = 1024 , messages = [ { "role" : "user" , "content" : content } ] , tools = [ { "name" : "provide_analysis" , "description" : "Provide structured analysis" , "input_schema" : AnalysisResult . model_json_schema ( ) } ] , tool_choice = { "type" : "tool" , "name" : "provide_analysis" } )
Extract tool use result
tool_use
next ( block for block in response . content if block . type == "tool_use" ) return AnalysisResult ( ** tool_use . input ) Custom Hooks (React) import { useState , useCallback } from 'react' interface UseApiState < T
{ data : T | null loading : boolean error : string | null } export function useApi < T
( fetchFn : ( ) => Promise < ApiResponse < T
) { const [ state , setState ] = useState < UseApiState < T
( { data : null , loading : false , error : null , } ) const execute = useCallback ( async ( ) => { setState ( prev => ( { ... prev , loading : true , error : null } ) ) const result = await fetchFn ( ) if ( result . success ) { setState ( { data : result . data ! , loading : false , error : null } ) } else { setState ( { data : null , loading : false , error : result . error ! } ) } } , [ fetchFn ] ) return { ... state , execute } } Testing Requirements Backend (pytest)
Run all tests
poetry run pytest tests/
Run with coverage
poetry run pytest tests/ --cov = . --cov-report = html
Run specific test file
poetry run pytest tests/test_auth.py -v Test structure: import pytest from httpx import AsyncClient from main import app @pytest . fixture async def client ( ) : async with AsyncClient ( app = app , base_url = "http://test" ) as ac : yield ac @pytest . mark . asyncio async def test_health_check ( client : AsyncClient ) : response = await client . get ( "/health" ) assert response . status_code == 200 assert response . json ( ) [ "status" ] == "healthy" Frontend (React Testing Library)
Run tests
npm run test
Run with coverage
npm run test -- --coverage
Run E2E tests
npm run test:e2e Test structure: import { render , screen , fireEvent } from '@testing-library/react' import { WorkspacePanel } from './WorkspacePanel' describe ( 'WorkspacePanel' , ( ) => { it ( 'renders workspace correctly' , ( ) => { render ( < WorkspacePanel /
) expect ( screen . getByRole ( 'main' ) ) . toBeInTheDocument ( ) } ) it ( 'handles session creation' , async ( ) => { render ( < WorkspacePanel /
) fireEvent . click ( screen . getByText ( 'New Session' ) ) expect ( await screen . findByText ( 'Session created' ) ) . toBeInTheDocument ( ) } ) } ) 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
Build and deploy frontend
cd frontend && npm run build gcloud run deploy frontend --source .
Build and deploy backend
cd backend gcloud run deploy backend --source . Environment Variables
Frontend (.env.local)
NEXT_PUBLIC_API_URL
https://api.example.com NEXT_PUBLIC_SUPABASE_URL = https://xxx.supabase.co NEXT_PUBLIC_SUPABASE_ANON_KEY = eyJ .. .
Backend (.env)
DATABASE_URL
postgresql:// .. . ANTHROPIC_API_KEY = sk-ant- .. . SUPABASE_URL = https://xxx.supabase.co SUPABASE_KEY = eyJ .. . Critical Rules No emojis in code, comments, or documentation Immutability - never mutate objects or arrays TDD - write tests before implementation 80% coverage minimum Many small files - 200-400 lines typical, 800 max No console.log in production code Proper error handling with try/catch Input validation with Pydantic/Zod