cc-skill-project-guidelines-example

Project Guidelines Skill - 全栈项目开发规范模板

技能概述

这是一个基于真实生产应用 Zenith 打造的项目级 Claude 技能模板，为 Next.js 15 + FastAPI 全栈项目提供完整的架构设计、代码规范、测试要求和部署工作流指南。

适用场景

1. 新项目启动与架构设计

当你开始一个新的全栈项目时，可以直接参考这套经过实战验证的技术栈和架构模式。技能提供了完整的服务架构图、文件结构模板和代码模式示例，帮助你快速搭建项目基础框架，避免从零开始摸索。

2. 团队开发规范制定

对于需要统一团队编码风格的项目，这套规范提供了清晰的代码模式、测试要求和关键规则。包括 API 响应格式标准化、前后端通信模式、测试覆盖要求等，让团队成员有明确的开发标准可以遵循。

3. Claude AI 辅助开发参考

在使用 Claude Code 进行项目开发时，引用这个技能可以让 AI 更好地理解你的项目架构和编码规范。技能包含了项目特定的技术选型、文件组织方式和代码模式，帮助 Claude 生成更符合项目规范的代码建议。

核心功能

1. 完整的技术架构指南

技能提供了经过生产验证的全栈技术栈组合：前端使用 Next.js 15（App Router）、TypeScript 和 React；后端采用 FastAPI（Python 3.11）和 Pydantic 数据验证；数据库使用 Supabase PostgreSQL；AI 集成 Claude API 的工具调用和结构化输出；部署使用 Google Cloud Run。每种技术都配有具体的代码示例和最佳实践。

2. 标准化代码模式模板

技能提供了多个可直接复用的代码模式模板，包括 FastAPI 的通用 API 响应格式、TypeScript 的前端 API 调用封装、Claude AI 结构化输出集成示例、React 自定义 Hooks 模式等。这些模板遵循不可变性原则、类型安全和错误处理最佳实践。

3. 测试与部署工作流

技能明确了测试要求：后端使用 pytest，前端使用 React Testing Library，E2E 测试使用 Playwright，要求 80% 的测试覆盖率。同时提供了完整的预部署检查清单、Google Cloud Run 部署命令和环境变量配置示例，确保项目能够顺利上线。

常见问题

什么是项目级 Claude 技能？

项目级技能是针对特定项目定制的 Claude 能力扩展，包含该项目的架构概览、文件结构、代码模式、测试要求和部署工作流。当你在使用 Claude Code 开发该项目时，引用项目技能可以让 AI 更好地理解项目上下文，生成更符合项目规范的代码和文档。

如何使用这个项目规范模板？

这个技能可以作为创建你自己项目技能的参考模板。首先复制技能的基本结构，然后根据你的实际项目修改技术栈、文件结构和代码模式。将你的项目技能保存为 SKILL.md 文件后，在使用 Claude Code 时就可以通过引用该技能来获得针对你项目的 AI 辅助。

这个模板适合什么类型的项目？

这个模板特别适合需要前后端分离的全栈 Web 应用，尤其是那些需要集成 AI 能力的项目。如果你的技术栈包含 Next.js、FastAPI、Supabase 和 Claude API，那么可以直接使用这套架构。如果你的技术栈不同，也可以参考这个模板的结构来创建适合你项目的规范文档。

技能中的测试要求有哪些？

技能要求遵循测试驱动开发（TDD）原则，在实现功能之前先编写测试。后端使用 pytest 进行单元测试和集成测试，前端使用 React Testing Library 进行组件测试，同时使用 Playwright 进行端到端测试。要求最低 80% 的代码测试覆盖率，确保代码质量和可维护性。

如何集成 Claude API 进行结构化输出？

技能提供了使用 Pydantic 模型定义结构化输出格式，然后通过 Claude API 的工具调用功能让 AI 返回符合该格式的结果。这种方式可以确保 AI 返回的数据结构化、可验证，便于后续处理和存储。

Google Cloud Run 部署有哪些优势？

Cloud Run 是完全托管的容器化部署平台，支持自动扩缩容，按实际使用量计费。技能提供了前后端分别部署到 Cloud Run 的完整命令和配置示例，包括环境变量设置、构建步骤和部署流程。相比传统服务器部署，Cloud Run 更适合现代容器化应用。