Cc Skill Project Guidelines Example

# 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](https://zenith.chat) - 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

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)

```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 (!