Crafting the CLAUDE.md for a FastAPI-React Template

Hello! Welcome to the final module of our course. Over the past few weeks, you've mastered advanced Claude Code features, from custom commands and hooks to complex MCP server integrations. You've built powerful, isolated workflows. Now, it's time to bring it all together.

This capstone module is where we transition from using advanced features to architecting them into a reusable, professional project template. You'll create a starter kit for your future FastAPI and React projects that has all your best practices and automations built in from day one.

Our first step is to create the "brain" of this template. In this lesson, you will define a comprehensive CLAUDE.md file for a reusable FastAPI + React project template. This file will serve as the central instruction manual for Claude, ensuring it understands your project's architecture, conventions, and workflows, making your development process faster and more consistent.

1. From a File to an Architecture

You're already familiar with using CLAUDE.md to provide project-specific context. For a reusable, professional-grade template, we need to elevate our thinking from a single, flat file to a structured knowledge architecture. The goal is to provide Claude with the right context at the right time, without overwhelming its attention.

A well-architected CLAUDE.md system enables Claude to perform complex tasks with high fidelity, as demonstrated in the following video where a detailed CLAUDE.md guides the construction of an entire FastAPI application.

To achieve this without creating a bloated, unmanageable file, we'll adopt a professional pattern: a 3-tier architecture for agent context.

This architecture organizes knowledge progressively:

1. Tier 1: Root CLAUDE.md: The main entry point. Contains universal rules and a high-level map of the project. It acts as a table of contents.
2. Tier 2: Subdirectory CLAUDE.md Files: Specific rules for different parts of your monorepo (e.g., frontend/ vs. backend/).
3. Tier 3: Skills & Agent Guides: Deep, task-specific instructions (e.g., how to create a database migration) or reference material that Claude can be directed to read on-demand. We'll touch on these as they relate to CLAUDE.md and explore them fully in later lessons.

The following reading provides an excellent, in-depth guide to this powerful structure.

2. Crafting the Root CLAUDE.md

As the article suggests, the root CLAUDE.md is the highest-leverage file for AI-assisted development. We'll use the recommended Why / What / How / Progressive Disclosure structure.

This structure provides a clear, logical flow for Claude:

• # Why: The project's purpose. A one-sentence mission statement.
• # What: A high-level project map, including the tech stack and key directories.
• # How: Universal, non-negotiable rules that apply everywhere in the project.
• # Progressive Disclosure: Pointers to more detailed rules in subdirectories.

Here's how this structure applies to your FastAPI + React template:

# Reusable Full-Stack AI Project Template




## Why
This template provides a production-ready foundation for building full-stack applications with a FastAPI backend, React frontend, and integrated AI capabilities.




## What (Project Map)
- **Backend**: Python, FastAPI, Pydantic, PostgreSQL (via SQLAlchemy & Alembic), Pytest. Managed with `uv`.
  - `backend/app/`: Core application code.
- **Frontend**: TypeScript, React, Next.js, Tailwind CSS. Managed with `npm`.
  - `frontend/`: All frontend code.
- **AI Integration**: Custom MCP servers for tools, Claude Code for development.
  - `.claude/`: Contains project-level Claude Code configuration, commands, and hooks.




## How (Always Apply)
- **MUST**: You MUST run `pytest` in the `backend/` directory after making any changes to Python files.
- **MUST**: You MUST run `npm run lint` in the `frontend/` directory after any changes to TypeScript or React files.
- **MUST**: Plan your work in phases before writing code.
- **Convention**: All database schema changes MUST be handled through Alembic migrations. Do not write raw `ALTER TABLE` statements.




## Progressive Disclosure
- For backend-specific rules (API structure, DB models), refer to `backend/CLAUDE.md`.
- For frontend-specific rules (component structure, state management), refer to `frontend/CLAUDE.md`.
- For available custom commands, review the files in `.claude/skills/`.

3. Specializing with Subdirectory CLAUDE.md Files

The real power of this approach comes from delegating context. Your FastAPI backend has very different conventions from your React frontend. Subdirectory CLAUDE.md files allow you to provide focused instructions.

Backend Rules (backend/CLAUDE.md)

This file contains rules specific to your FastAPI application.

# Backend Rules (FastAPI)




## Architecture
- All API endpoints are defined in `backend/app/api/endpoints/`.
- Business logic is separated into service functions in `backend/app/services/`.
- Database models (SQLAlchemy) are in `backend/app/models/`.
- Pydantic schemas for API contracts are in `backend/app/schemas/`.




## Conventions
- **MUST**: Use async/await for all database operations and external API calls.
- **MUST**: All API endpoints must have explicit Pydantic models for request bodies and responses. Do not use generic `dict` or `Any`.
- **MUST**: Use FastAPI's dependency injection system for accessing services and database sessions.
- **Style**: Follow PEP 8, formatted with `ruff format` and linted with `ruff check`.

Frontend Rules (frontend/CLAUDE.md)

This file defines the conventions for your React/Next.js frontend.

# Frontend Rules (React/Next.js)




## Architecture
- Reusable components are located in `frontend/src/components/`.
- Page routes are defined in `frontend/src/app/`.
- API client functions for calling the FastAPI backend are in `frontend/src/lib/api.ts`.
- State management uses Zustand (or your preferred library).




## Conventions
- **MUST**: Use TypeScript for all new components and logic. Avoid `any`.
- **Style**: Components should be styled using Tailwind CSS utility classes. Avoid inline styles or separate CSS files.
- **Convention**: All components must be functional components using React Hooks. Class components are forbidden.

4. Your Turn: Define Your Template's CLAUDE.md

Now it's time for you to formalize the CLAUDE.md structure for your capstone project.

1. Create the File Structure: In your project's root, create the following files:

   • CLAUDE.md (the root file)
   • backend/CLAUDE.md
   • frontend/CLAUDE.md

2. Populate the Files: Use the examples above as a starting point. Customize them to fit the precise architecture and conventions you want to enforce in your reusable template. Think about the common instructions you give Claude and the mistakes it tends to make. This is your chance to codify the solutions.

For more inspiration and a solid foundation, the claude-md-templates repository is an invaluable resource. It contains well-thought-out templates for various stacks.

This exercise is the foundation for the rest of the capstone. A well-defined CLAUDE.md architecture will make building custom commands, hooks, and automated workflows significantly more reliable.

Conclusion

In this lesson, you've designed the intelligent core of your reusable project template. By moving from a single file to a tiered architecture, you're building a system that can provide precise, relevant context to Claude for any task, anywhere in your codebase.

Key Takeaways:

• CLAUDE.md as Architecture: For professional projects, treat your CLAUDE.md files as a structured knowledge base, not just a list of rules.
• Progressive Disclosure is Key: The 3-tier structure (Root -> Subdirectory -> Skills/Guides) prevents context overload and ensures Claude gets the right information at the right time.
• The Why/What/How Framework: This simple structure for your root CLAUDE.md makes it highly effective and easy for both humans and AI to understand.
• Specialize with Subdirectory Files: Monorepos with distinct parts (like a backend and frontend) benefit immensely from localized CLAUDE.md files that define specific conventions.

Next Up:

With the "brain" of our template in place, our next step is to give it "hands." In the next lesson, you will develop a set of reusable project-level slash commands for the template, such as /new-component or /new-endpoint. These commands will read the rules you've just defined to generate code that is perfectly consistent with your project's architecture.