Enforcing Team Architecture with .claude/rules in Claude Code (FastAPI Practical Guide)

When you introduce AI code generation tools into a real-world project, the first problem you hit is consistency.

• Business logic leaks into the API layer
• Repositories are accessed directly from everywhere
• Team-agreed architecture slowly breaks down

Claude Code addresses this problem with a concept called .claude/rules. In this article, we’ll walk through how to design and use .claude/rules in a FastAPI project, focusing on practical, enforceable rules rather than abstract theory.

What is .claude/rules?

.claude/rules is a repository of team rules that Claude Code can reference when generating, refactoring, or reviewing code.

A few important clarifications:

1. Rules are not applied automatically: They are not globally enforced by default.
2. Explicit Reference: Rules are applied only when a Skill or Agent explicitly references them.

In other words, .claude/rules is not a simple configuration file; it’s a collection of explicit judgment criteria for your codebase.

The Execution Flow:

.claude/rules → Skill → Agent****Rules: Architectural and coding constraints.Skill: Logic that applies those constraints.Agent: The execution unit that runs skills.

Example .claude/rules Structure for a FastAPI Project

Here’s a real-world directory structure used in a production-ready FastAPI service:

.claude/rules
├── architecture
│   ├── api_layer.md
│   ├── repository_layer.md
│   └── service_layer.md
├── coding_standards
│   └── no_hardcoding.md
├── data_structures
│   ├── models.md
│   └── schemas.md
├── database
│   └── postgresql.md
└── infrastructure
    ├── config.md
    ├── core.md
    ├── exceptions.md
    ├── prompts.md
    └── tasks.md

Key Responsibilities:

• Architecture: Layer boundaries and dependencies.
• Coding Standards: Non-negotiable coding rules.
• Data Structures: Pydantic and ORM conventions.
• Database: Database access rules.
• Infrastructure: Shared configuration and core logic.

Example: architecture/api_layer.md

Below is a practical version of an api_layer.md rule file. This defines hard boundaries for Claude to follow.

📎 api_layer

Closing Thoughts

The real value of .claude/rules is making implicit team knowledge explicit for AI. Rules that humans might overlook during reviews can be enforced consistently by Claude Code.

In the next article, we’ll look at Refactoring Skills and Agents that actively apply these rules to automate architectural integrity.

Writing rules is easy. Making them consistently enforced is what actually matters.