project-guidelines-example

基于真实生产应用程序的项目特定技能（Skill）模板示例。

Quality

32%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/project-guidelines-example/SKILL.md

项目指南技能（Skill）示例

这是一个项目特定技能（Skill）的示例。请将其作为你自己项目的模板。

基于真实生产应用程序：Zenith - AI 驱动的客户挖掘平台。

何时使用

在处理其设计的特定项目时参考此技能。项目技能包含：

架构概览
文件结构
代码模式
测试要求
部署工作流

架构概览

技术栈：

前端（Frontend）: Next.js 15 (App Router), TypeScript, React
后端（Backend）: FastAPI (Python), Pydantic 模型
数据库（Database）: Supabase (PostgreSQL)
AI: 支持工具调用（tool calling）和结构化输出（structured output）的 Claude API
部署（Deployment）: Google Cloud Run
测试（Testing）: Playwright (E2E), pytest (后端), React Testing Library

服务：

┌─────────────────────────────────────────────────────────────┐
│                         前端（Frontend）                    │
│  Next.js 15 + TypeScript + TailwindCSS                     │
│  部署于（Deployed）: Vercel / Cloud Run                    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                         后端（Backend）                     │
│  FastAPI + Python 3.11 + Pydantic                          │
│  部署于（Deployed）: Cloud Run                             │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
        ┌──────────┐   ┌──────────┐   ┌──────────┐
        │ Supabase │   │  Claude  │   │  Redis   │
        │ 数据库   │   │   API    │   │  缓存    │
        └──────────┘   └──────────┘   └──────────┘

文件结构

project/
├── frontend/
│   └── src/
│       ├── app/              # Next.js App Router 页面
│       │   ├── api/          # API 路由
│       │   ├── (auth)/       # 身份验证保护的路由
│       │   └── workspace/    # 主应用程序工作区
│       ├── components/       # React 组件
│       │   ├── ui/           # 基础 UI 组件
│       │   ├── forms/        # 表单组件
│       │   └── layouts/      # 布局组件
│       ├── hooks/            # 自定义 React Hooks
│       ├── lib/              # 实用工具
│       ├── types/            # TypeScript 定义
│       └── config/           # 配置
│
├── backend/
│   ├── routers/              # FastAPI 路由处理器
│   ├── models.py             # Pydantic 模型
│   ├── main.py               # FastAPI 应用程序入口
│   ├── auth_system.py        # 身份验证
│   ├── database.py           # 数据库操作
│   ├── services/             # 业务逻辑
│   └── tests/                # pytest 测试
│
├── deploy/                   # 部署配置
├── docs/                     # 文档
└── scripts/                  # 实用脚本

代码模式

API 响应格式 (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)

前端 API 调用 (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 集成 (结构化输出)

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"}
    )

    # 提取工具使用（tool_use）结果
    tool_use = next(
        block for block in response.content
        if block.type == "tool_use"
    )

    return AnalysisResult(**tool_use.input)

自定义 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 }
}

测试要求

后端 (pytest)

# 运行所有测试
poetry run pytest tests/

# 运行并生成覆盖率报告
poetry run pytest tests/ --cov=. --cov-report=html

# 运行特定测试文件
poetry run pytest tests/test_auth.py -v

测试结构：

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"

前端 (React Testing Library)

# 运行测试
npm run test

# 运行并生成覆盖率报告
npm run test -- --coverage

# 运行 E2E 测试
npm run test:e2e