Cc Skill Project Guidelines Example

1---
2name: cc-skill-project-guidelines-example
3description: Project Guidelines Skill (Example)
4author: affaan-m
5version: "1.0"
6---
7 
8# Project Guidelines Skill (Example)
9 
10This is an example of a project-specific skill. Use this as a template for your own projects.
11 
12Based on a real production application: [Zenith](https://zenith.chat) - AI-powered customer discovery platform.
13 
14---
15 
16## When to Use
17 
18Reference this skill when working on the specific project it's designed for. Project skills contain:
19- Architecture overview
20- File structure
21- Code patterns
22- Testing requirements
23- Deployment workflow
24 
25---
26 
27## Architecture Overview
28 
29**Tech Stack:**
30- **Frontend**: Next.js 15 (App Router), TypeScript, React
31- **Backend**: FastAPI (Python), Pydantic models
32- **Database**: Supabase (PostgreSQL)
33- **AI**: Claude API with tool calling and structured output
34- **Deployment**: Google Cloud Run
35- **Testing**: Playwright (E2E), pytest (backend), React Testing Library
36 
37**Services:**
38```
39┌─────────────────────────────────────────────────────────────┐
40│                         Frontend                            │
41│  Next.js 15 + TypeScript + TailwindCSS                     │
42│  Deployed: Vercel / Cloud Run                              │
43└─────────────────────────────────────────────────────────────┘
44                              │
45                              ▼
46┌─────────────────────────────────────────────────────────────┐
47│                         Backend                             │
48│  FastAPI + Python 3.11 + Pydantic                          │
49│  Deployed: Cloud Run                                       │
50└─────────────────────────────────────────────────────────────┘
51                              │
52              ┌───────────────┼───────────────┐
53              ▼               ▼               ▼
54        ┌──────────┐   ┌──────────┐   ┌──────────┐
55        │ Supabase │   │  Claude  │   │  Redis   │
56        │ Database │   │   API    │   │  Cache   │
57        └──────────┘   └──────────┘   └──────────┘
58```
59 
60---
61 
62## File Structure
63 
64```
65project/
66├── frontend/
67│   └── src/
68│       ├── app/              # Next.js app router pages
69│       │   ├── api/          # API routes
70│       │   ├── (auth)/       # Auth-protected routes
71│       │   └── workspace/    # Main app workspace
72│       ├── components/       # React components
73│       │   ├── ui/           # Base UI components
74│       │   ├── forms/        # Form components
75│       │   └── layouts/      # Layout components
76│       ├── hooks/            # Custom React hooks
77│       ├── lib/              # Utilities
78│       ├── types/            # TypeScript definitions
79│       └── config/           # Configuration
80│
81├── backend/
82│   ├── routers/              # FastAPI route handlers
83│   ├── models.py             # Pydantic models
84│   ├── main.py               # FastAPI app entry
85│   ├── auth_system.py        # Authentication
86│   ├── database.py           # Database operations
87│   ├── services/             # Business logic
88│   └── tests/                # pytest tests
89│
90├── deploy/                   # Deployment configs
91├── docs/                     # Documentation
92└── scripts/                  # Utility scripts
93```
94 
95---
96 
97## Code Patterns
98 
99### API Response Format (FastAPI)
100 
101```python
102from pydantic import BaseModel
103from typing import Generic, TypeVar, Optional
104 
105T = TypeVar('T')
106 
107class ApiResponse(BaseModel, Generic[T]):
108    success: bool
109    data: Optional[T] = None
110    error: Optional[str] = None
111 
112    @classmethod
113    def ok(cls, data: T) -> "ApiResponse[T]":
114        return cls(success=True, data=data)
115 
116    @classmethod
117    def fail(cls, error: str) -> "ApiResponse[T]":
118        return cls(success=False, error=error)
119```
120 
121### Frontend API Calls (TypeScript)
122 
123```typescript
124interface ApiResponse<T> {
125  success: boolean
126  data?: T
127  error?: string
128}
129 
130async function fetchApi<T>(
131  endpoint: string,
132  options?: RequestInit
133): Promise<ApiResponse<T>> {
134  try {
135    const response = await fetch(`/api${endpoint}`, {
136      ...options,
137      headers: {
138        'Content-Type': 'application/json',
139        ...options?.headers,
140      },
141    })
142 
143    if (!response.ok) {
144      return { success: false, error: `HTTP ${response.status}` }
145    }
146 
147    return await response.json()
148  } catch (error) {
149    return { success: false, error: String(error) }
150  }
151}
152```
153 
154### Claude AI Integration (Structured Output)
155 
156```python
157from anthropic import Anthropic
158from pydantic import BaseModel
159 
160class AnalysisResult(BaseModel):
161    summary: str
162    key_points: list[str]
163    confidence: float
164 
165async def analyze_with_claude(content: str) -> AnalysisResult:
166    client = Anthropic()
167 
168    response = client.messages.create(
169        model="claude-sonnet-4-5-20250514",
170        max_tokens=1024,
171        messages=[{"role": "user", "content": content}],
172        tools=[{
173            "name": "provide_analysis",
174            "description": "Provide structured analysis",
175            "input_schema": AnalysisResult.model_json_schema()
176        }],
177        tool_choice={"type": "tool", "name": "provide_analysis"}
178    )
179 
180    # Extract tool use result
181    tool_use = next(
182        block for block in response.content
183        if block.type == "tool_use"
184    )
185 
186    return AnalysisResult(**tool_use.input)
187```
188 
189### Custom Hooks (React)
190 
191```typescript
192import { useState, useCallback } from 'react'
193 
194interface UseApiState<T> {
195  data: T | null
196  loading: boolean
197  error: string | null
198}
199 
200export function useApi<T>(
201  fetchFn: () => Promise<ApiResponse<T>>
202) {
203  const [state, setState] = useState<UseApiState<T>>({
204    data: null,
205    loading: false,
206    error: null,
207  })
208 
209  const execute = useCallback(async () => {
210    setState(prev => ({ ...prev, loading: true, error: null }))
211 
212    const result = await fetchFn()
213 
214    if (result.success) {
215      setState({ data: result.data!, loading: false, error: null })
216    } else {
217      setState({ data: null, loading: false, error: result.error! })
218    }
219  }, [fetchFn])
220 
221  return { ...state, execute }
222}
223```
224 
225---
226 
227## Testing Requirements
228 
229### Backend (pytest)
230 
231```bash
232# Run all tests
233poetry run pytest tests/
234 
235# Run with coverage
236poetry run pytest tests/ --cov=. --cov-report=html
237 
238# Run specific test file
239poetry run pytest tests/test_auth.py -v
240```
241 
242**Test structure:**
243```python
244import pytest
245from httpx import AsyncClient
246from main import app
247 
248@pytest.fixture
249async def client():
250    async with AsyncClient(app=app, base_url="http://test") as ac:
251        yield ac
252 
253@pytest.mark.asyncio
254async def test_health_check(client: AsyncClient):
255    response = await client.get("/health")
256    assert response.status_code == 200
257    assert response.json()["status"] == "healthy"
258```
259 
260### Frontend (React Testing Library)
261 
262```bash
263# Run tests
264npm run test
265 
266# Run with coverage
267npm run test -- --coverage
268 
269# Run E2E tests
270npm run test:e2e
271```
272 
273**Test structure:**
274```typescript
275import { render, screen, fireEvent } from '@testing-library/react'
276import { WorkspacePanel } from './WorkspacePanel'
277 
278describe('WorkspacePanel', () => {
279  it('renders workspace correctly', () => {
280    render(<WorkspacePanel />)
281    expect(screen.getByRole('main')).toBeInTheDocument()
282  })
283 
284  it('handles session creation', async () => {
285    render(<WorkspacePanel />)
286    fireEvent.click(screen.getByText('New Session'))
287    expect(await screen.findByText('Session created')).toBeInTheDocument()
288  })
289})
290```
291 
292---
293 
294## Deployment Workflow
295 
296### Pre-Deployment Checklist
297 
298- [ ] All tests passing locally
299- [ ] `npm run build` succeeds (frontend)
300- [ ] `poetry run pytest` passes (backend)
301- [ ] No hardcoded secrets
302- [ ] Environment variables documented
303- [ ] Database migrations ready
304 
305### Deployment Commands
306 
307```bash
308# Build and deploy frontend
309cd frontend && npm run build
310gcloud run deploy frontend --source .
311 
312# Build and deploy backend
313cd backend
314gcloud run deploy backend --source .
315```
316 
317### Environment Variables
318 
319```bash
320# Frontend (.env.local)
321NEXT_PUBLIC_API_URL=https://api.example.com
322NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
323NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
324 
325# Backend (.env)
326DATABASE_URL=postgresql://...
327ANTHROPIC_API_KEY=sk-ant-...
328SUPABASE_URL=https://xxx.supabase.co
329SUPABASE_KEY=eyJ...
330```
331 
332---
333 
334## Critical Rules
335 
3361. **No emojis** in code, comments, or documentation
3372. **Immutability** - never mutate objects or arrays
3383. **TDD** - write tests before implementation
3394. **80% coverage** minimum
3405. **Many small files** - 200-400 lines typical, 800 max
3416. **No console.log** in production code
3427. **Proper error handling** with try/catch
3438. **Input validation** with Pydantic/Zod
344 
345---
346 
347## Related Skills
348 
349- `coding-standards.md` - General coding best practices
350- `backend-patterns.md` - API and database patterns
351- `frontend-patterns.md` - React and Next.js patterns
352- `tdd-workflow/` - Test-driven development methodology
353