Skip to main content
skill CX Codex

project-guidelines-example — Claude Code skill: features and setup

The project-guidelines-example skill gives an agent a sample project’s architecture, file layout, code patterns, and testing commands to reference while working on a codebase.

MIT ★ 6,739 updated 2026-01-23

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add WorldFlowAI/everything-claude-code
/plugin install everything-claude-code@everything-claude-code
Open on GitHub

What project-guidelines-example does

The example describes an app built with Next.js 15, TypeScript, and React, backed by FastAPI and Supabase. It lays out directories and shows patterns for API responses, Claude API calls, and React hooks.

Testing guidance covers pytest, React Testing Library, and E2E commands. The architecture also names Cloud Run and Vercel for deployment. Treat these choices as project-specific: copying them into a different codebase may not fit.

To install in Claude Code, add the marketplace and then install the skill. The repository also provides an npx skills add command as an alternative.

What it helps with

  • give an agent a project architecture to follow
  • map the frontend and backend directory layout
  • standardize FastAPI response examples
  • find commands for backend and frontend tests

Example prompts for the agent

  • Compare this codebase with the example architecture and point out the differences.
  • Show how to shape an API response using the skill’s pattern.
  • Which commands run the backend and frontend tests in this project guide?

How to install project-guidelines-example

1Plugin marketplace

/plugin marketplace add WorldFlowAI/everything-claude-code
/plugin install everything-claude-code@everything-claude-code

This installs the whole everything-claude-code plugin with all its skills

2Manually: put the files in place

~/.claude/skills/project-guidelines-example/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/project-guidelines-example/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about project-guidelines-example

How do I install project-guidelines-example in Claude Code?

Run /plugin marketplace add WorldFlowAI/everything-claude-code, then run /plugin install everything-claude-code@everything-claude-code.

What does project-guidelines-example do?

It gives an agent project-specific guidance on architecture, file layout, code patterns, and tests, using a Next.js and FastAPI app as its example.

Which stack does the skill describe?

The example uses Next.js 15, TypeScript, React, FastAPI, Pydantic, and Supabase. Its architecture is tied to that sample project.

Source text

SKILL.md · MIT
# 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 (!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)

```python
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)

```typescript
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)

```bash
# 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:**
```python
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)

```bash
# Run tests
npm run test

# Run with coverage
npm run test -- --coverage

# Run E2E tests
npm run test:e2e
```

**Test structure:**
```typescript
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

```bash
# 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

```bash
# 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

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

© Affaan Mustafa · MIT · WorldFlowAI/everything-claude-code

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set29

The whole set →
architect An opus-powered subagent for designing scalable software architecture, analyzing technical trade-offs, and drafting Architecture Decision Records. CX Codex ★ 6,739repo stars tdd-guide The tdd-guide subagent guides feature work, bug fixes, and refactoring through a test-first workflow. It also checks test coverage against an 80% target. CX Codex ★ 6,739repo stars refactor-cleaner refactor-cleaner is a Claude Code subagent that finds and removes unused code, duplicates, and dependencies. It runs knip, depcheck, and ts-prune during codebase cleanup. CX Codex ★ 6,739repo stars tdd tdd enforces a strict test-driven development cycle in Claude Code by writing failing tests first, implementing minimal code, and checking for 80%+ coverage. CX Codex +1 ★ 6,739repo stars tdd-workflow tdd-workflow makes the agent write tests before code and keep coverage at 80% or higher across unit, integration and Playwright E2E suites. CX Codex +1 ★ 6,739repo stars doc-updater doc-updater — a subagent that updates architecture codemaps and project guides from code. Helpful when repo structure evolves faster than manuals. CX Codex ★ 6,739repo stars build-error-resolver The build-error-resolver subagent diagnoses build and TypeScript failures, then applies small fixes without architectural changes. Use it when a build or type check breaks. CX Codex ★ 6,739repo stars security-reviewer The security-reviewer subagent for Claude Code scans code for SQL injections, hardcoded secrets, unsafe crypto, and OWASP Top 10 issues after work on user input, authentication, or API endpoints. CX Codex ★ 6,739repo stars

Project sponsors

Companies that keep this analytics open