cc-skill-project-guidelines-example

Project Guidelines Skill - Full-Stack Project Development Standard Template

Skill Overview

This is a project-level Claude skill template built from the real production application Zenith. It provides a complete architecture design, code standards, testing requirements, and deployment workflow guidance for Next.js 15 + FastAPI full-stack projects.

Applicable Scenarios

1. New Project Kickoff and Architecture Design

When you start a new full-stack project, you can directly reference this battle-tested tech stack and architecture pattern. The skill provides complete service architecture diagrams, file structure templates, and code pattern examples to help you quickly set up the project foundation and avoid starting from scratch.

2. Establishing Team Development Standards

For projects that need unified team coding styles, this specification provides clear code patterns, testing requirements, and key rules. It includes standardized API response formats, front-end/back-end communication patterns, testing coverage requirements, etc., giving team members clear development standards to follow.

3. Claude AI Assisted Development Reference

When using Claude Code for project development, referencing this skill helps the AI better understand your project architecture and coding standards. The skill contains project-specific technology choices, file organization, and code patterns to help Claude generate code suggestions that better comply with project standards.

Core Features

1. Complete Technical Architecture Guide

The skill provides a production-verified full-stack technology stack: front end uses Next.js 15 (App Router), TypeScript, and React; back end uses FastAPI (Python 3.11) and Pydantic for data validation; the database is Supabase PostgreSQL; AI integration uses Claude API tool calls and structured outputs; deployment uses Google Cloud Run. Each technology includes concrete code examples and best practices.

2. Standardized Code Pattern Templates

The skill offers multiple directly reusable code pattern templates, including a common API response format for FastAPI, TypeScript front-end API call wrappers, Claude AI structured output integration examples, and React custom hooks patterns. These templates adhere to the principles of immutability, type safety, and robust error handling best practices.

3. Testing and Deployment Workflows

The skill specifies testing requirements: back end uses pytest, front end uses React Testing Library, and E2E tests use Playwright, with a required 80% test coverage. It also provides a complete pre-deployment checklist, Google Cloud Run deployment commands, and environment variable configuration examples to ensure smooth production rollout.

Frequently Asked Questions

What is a project-level Claude skill?

A project-level skill is a Claude capability extension tailored to a specific project, containing the project's architecture overview, file structure, code patterns, testing requirements, and deployment workflows. When using Claude Code to develop that project, referencing the project skill helps the AI better understand the project context and generate code and documentation that align with the project's standards.

How do I use this project standard template?

This skill can be used as a reference template for creating your own project skill. First copy the basic structure of the skill, then modify the tech stack, file structure, and code patterns according to your actual project. Save your project skill as a SKILL.md file, and when using Claude Code you can reference that skill to get AI assistance tailored to your project.

What types of projects is this template suitable for?

This template is especially suitable for full-stack web applications with separated front and back ends, particularly projects that require AI integration. If your tech stack includes Next.js, FastAPI, Supabase, and the Claude API, you can use this architecture directly. If your tech stack differs, you can still use this template's structure to create a specification document suited to your project.

What are the testing requirements in the skill?

The skill requires following Test-Driven Development (TDD) principles by writing tests before implementing features. Backend unit and integration tests use pytest; frontend component tests use React Testing Library; end-to-end tests use Playwright. A minimum of 80% code test coverage is required to ensure code quality and maintainability.

How do I integrate the Claude API for structured output?

The skill provides using Pydantic models to define structured output formats, then leveraging Claude API tool call features to have the AI return results that conform to those formats. This approach ensures AI responses are structured and verifiable, making them easier to process and store.

What are the advantages of deploying to Google Cloud Run?

Cloud Run is a fully managed container deployment platform that supports automatic scaling and pay-per-use billing. The skill provides complete commands and configuration examples for deploying front-end and back-end services separately to Cloud Run, including environment variable settings, build steps, and deployment processes. Compared to traditional server deployments, Cloud Run is better suited for modern containerized applications.