SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场project-guidelines-example

project-guidelines-example

编程与开发

查看项目

更新于 10-15 08:39

技能介绍

用途

这是一个项目专属技能（project-specific skill）的示例模板，供用户作为自己项目模板使用。它基于一个真实的生产应用 Zenith（AI 驱动的客户发现平台）编写，用于在开发该特定项目时提供参考。项目技能通常包含：架构概览、文件结构、代码模式、测试要求、部署工作流。

架构概览

技术栈：

  • 前端：Next.js 15（App Router）、TypeScript、React
  • 后端：FastAPI（Python）、Pydantic 模型
  • 数据库：Supabase（PostgreSQL）
  • AI：Claude 工具调用与结构化输出 API
  • 部署：Google Cloud Run
  • 测试：Playwright（E2E）、pytest（后端）、React Testing Library

服务结构：前端（Next.js 15 + TypeScript + TailwindCSS，部署于 Vercel / Cloud Run）调用后端（FastAPI + Python 3.11 + Pydantic，部署于 Cloud Run），后端再连接 Supabase 数据库、Claude API 与 Redis 缓存。

文件结构

project/ 下包含：

  • frontend/src/：app（Next.js app router 页面，含 api、认证保护路由 (auth)、主应用工作区 workspace）、components（ui、forms、layouts）、hooks、lib、types、config
  • backend/：routers（FastAPI 路由处理器）、models.py（Pydantic 模型）、main.py（FastAPI 应用入口）、auth_system.py（认证）、database.py（数据库操作）、services（业务逻辑）、tests（pytest 测试）
  • deploy/（部署配置）、docs/（文档）、scripts/（工具脚本）

代码模式

  • API 响应格式（FastAPI）：使用 Pydantic 泛型模型 ApiResponse，含 success、data、error 字段，并提供 ok 与 fail 类方法。
  • 前端 API 调用（TypeScript）：定义 ApiResponse 接口与 fetchApi 泛型函数，统一处理请求头、HTTP 错误与异常。
  • Claude AI 集成（结构化输出）：使用 Anthropic 客户端，定义 AnalysisResult（summary、key_points、confidence），通过 tools 与 tool_choice 强制工具调用，从响应中提取 tool_use 结果并构造 AnalysisResult。
  • 自定义 Hook（React）：useApi 封装 data、loading、error 状态与 execute 方法。

测试要求

后端（pytest）：

  • 运行全部测试：poetry run pytest tests/
  • 带覆盖率：poetry run pytest tests/ --cov=. --cov-report=html
  • 运行特定文件：poetry run pytest tests/test_auth.py -v
  • 测试结构示例使用 pytest fixture 与 AsyncClient，包含健康检查测试。

前端（React Testing Library）：

  • 运行测试：npm run test
  • 带覆盖率：npm run test -- --coverage
  • 运行 E2E：npm run test:e2e
  • 测试结构示例使用 render、screen、fireEvent，包含渲染与创建会话测试。

部署工作流

部署前检查清单：所有测试本地通过、npm run build 成功（前端）、poetry run pytest 成功（后端）、无硬编码密钥、环境变量已文档化、数据库迁移已准备。

部署命令：

  • 前端：cd frontend && npm run build，然后 gcloud run deploy frontend --source .
  • 后端：cd backend，然后 gcloud run deploy backend --source .

环境变量：

  • 前端（.env.local）：NEXT_PUBLIC_API_URL、NEXT_PUBLIC_SUPABASE_URL、NEXT_PUBLIC_SUPABASE_ANON_KEY
  • 后端（.env）：DATABASE_URL、ANTHROPIC_API_KEY、SUPABASE_URL、SUPABASE_KEY

重要规则

  • 不使用 emoji（代码、注释、文档中）
  • 不可变性（不修改对象或数组）
  • TDD（实现前先写测试）
  • 80% 覆盖率（最低标准）
  • 小文件多数量（通常 200-400 行，最大 800 行）
  • 禁止 console.log（生产代码中）
  • 适当的错误处理（使用 try/catch）
  • 输入验证（使用 Pydantic/Zod）

相关技能

  • coding-standards.md：通用编码最佳实践
  • backend-patterns.md：API 与数据库模式
  • frontend-patterns.md：React 与 Next.js 模式
  • tdd-workflow/：测试驱动开发方法论

限制

本资料为示例模板，具体项目的实际架构、命令与配置需按自身情况调整。资料未提供收费、价格、平台支持范围等信息。