# Cc Skill Project Guidelines Example > 项目指南技能（示例）。当用户要求'项目指南'、'项目规范'或'项目技能模板'时使用。 - Skill: `kscz0000/cc-skill-project-guidelines-example` (Agent Skill) - Install (CLI): `npx skillmds@latest add kscz0000/cc-skill-project-guidelines-example` - Raw SKILL.md: https://api.skillmd.com/api/skills/kscz0000/cc-skill-project-guidelines-example/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: kscz0000 (https://skillmd.com/u/kscz0000) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/kscz0000/cc-skill-project-guidelines-example --- # 项目指南技能（示例） 这是一个项目特定技能的示例。可作为你自己项目的模板使用。 基于真实生产应用：[Zenith](https://zenith.chat) - AI 驱动的客户发现平台。 --- ## 使用时机 在为其设计的特定项目上工作时参考此技能。项目技能包含： - 架构概览 - 文件结构 - 代码模式 - 测试要求 - 部署工作流 --- ## 架构概览 **技术栈：** - **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 **服务架构：** ``` ┌─────────────────────────────────────────────────────────────┐ │ Frontend │ │ Next.js 15 + TypeScript + TailwindCSS │ │ 部署于: Vercel / Cloud Run │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Backend │ │ FastAPI + Python 3.11 + Pydantic │ │ 部署于: Cloud Run │ └─────────────────────────────────────────────────────────────┘ │ ┌───────────────┼───────────────┐ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Supabase │ │ Claude │ │ Redis │ │ Database │ │ API │ │ Cache │ └──────────┘ └──────────┘ └──────────┘ ``` --- ## 文件结构 ``` 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) ```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) ``` ### 前端 API 调用 (TypeScript) ```typescript interface ApiResponse { success: boolean data?: T error?: string } async function fetchApi( endpoint: string, options?: RequestInit ): Promise> { 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 集成（结构化输出） ```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": "提供结构化分析", "input_schema": AnalysisResult.model_json_schema() }], tool_choice={"type": "tool", "name": "provide_analysis"} ) # 提取工具调用结果 tool_use = next( block for block in response.content if block.type == "tool_use" ) return AnalysisResult(**tool_use.input) ``` ### 自定义 Hooks (React) ```typescript import { useState, useCallback } from 'react' interface UseApiState { data: T | null loading: boolean error: string | null } export function useApi( fetchFn: () => Promise> ) { const [state, setState] = useState>({ 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) ```bash # 运行所有测试 poetry run pytest tests/ # 运行并生成覆盖率报告 poetry run pytest tests/ --cov=. --cov-report=html # 运行指定测试文件 poetry run pytest tests/test_auth.py -v ``` **测试结构：** ```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" ``` ### 前端 (React Testing Library) ```bash # 运行测试 npm run test # 运行并生成覆盖率报告 npm run test -- --coverage # 运行 E2E 测试 npm run test:e2e ``` **测试结构：** ```typescript import { render, screen, fireEvent } from '@testing-library/react' import { WorkspacePanel } from './WorkspacePanel' describe('WorkspacePanel', () => { it('正确渲染工作区', () => { render() expect(screen.getByRole('main')).toBeInTheDocument() }) it('处理会话创建', async () => { render() fireEvent.click(screen.getByText('New Session')) expect(await screen.findByText('Session created')).toBeInTheDocument() }) }) ``` --- ## 部署工作流 ### 部署前检查清单 - [ ] 本地所有测试通过 - [ ] `npm run build` 成功（前端） - [ ] `poetry run pytest` 通过（后端） - [ ] 无硬编码密钥 - [ ] 环境变量已文档化 - [ ] 数据库迁移已准备 ### 部署命令 ```bash # 构建并部署前端 cd frontend && npm run build gcloud run deploy frontend --source . # 构建并部署后端 cd backend gcloud run deploy backend --source . ``` ### 环境变量 ```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... ``` --- ## 关键规则 1. **禁止表情符号** - 代码、注释或文档中不得使用表情符号 2. **不可变性** - 永远不要直接修改对象或数组 3. **TDD** - 实现前先写测试 4. **80% 覆盖率** - 最低要求 5. **小文件原则** - 典型 200-400 行，最大 800 行 6. **禁止 console.log** - 生产代码中不得使用 7. **正确错误处理** - 使用 try/catch 8. **输入验证** - 使用 Pydantic/Zod --- ## 相关技能 - `coding-standards.md` - 通用编码最佳实践 - `backend-patterns.md` - API 和数据库模式 - `frontend-patterns.md` - React 和 Next.js 模式 - `tdd-workflow/` - 测试驱动开发方法论 ## 局限性 - 仅在任务明确匹配上述描述范围时使用此技能。 - 输出内容不能替代特定环境的验证、测试或专家审查。 - 如果缺少必要的输入、权限、安全边界或成功标准，请停止并请求澄清。