Claude Code project rules: how to use the .claude/rules directory for organized configs

Your CLAUDE.md started simple. A few lines about the stack, a test command, some naming rules. Now it is 300 lines long and growing every time you add a new convention. Different sections apply to different parts of the codebase. Finding and editing specific rules means scrolling through everything.

Claude Code has a built-in solution: the .claude/rules/ directory.

How it works

Create a .claude/rules/ directory in your project root. Put markdown files in it. Each file contains a focused set of rules. Claude Code loads all of them at session start, alongside your main CLAUDE.md.

your-project/
  CLAUDE.md                    # Core project config
  .claude/
    rules/
      frontend.md              # React conventions, component patterns
      backend.md               # API routes, database rules
      testing.md               # Test framework, mocking strategy
      guardrails.md            # Safety rules, destructive action blocks
      deployment.md            # Build, deploy, CI/CD rules

Every .md file in that directory is read automatically. No imports, no configuration, no registration. Just create the files and they work.

When to split vs when to keep everything in CLAUDE.md

Not every project needs the rules directory. Here is a simple decision framework:

• CLAUDE.md under 100 lines: Keep everything in one file. Splitting creates complexity with no benefit.
• CLAUDE.md between 100-200 lines: Consider splitting if you have clearly distinct sections (frontend vs backend, testing vs deployment).
• CLAUDE.md over 200 lines: Split. A 300-line config is hard to maintain and harder for Claude to prioritize. Focused files are easier to maintain and review.

Other reasons to split:

• Multiple team members contribute rules. Each person maintains their own rule file. Merge conflicts are less likely when changes happen in separate files.
• Monorepos with different stacks in different directories. The frontend team adds to frontend.md; the backend team adds to backend.md.
• Rules you want to toggle. Temporarily rename a file to .bak to disable it. Easier than commenting out sections in a large CLAUDE.md.

What goes where

The main CLAUDE.md keeps the essentials: project overview, tech stack, file structure. These are the things every Claude Code session needs regardless of what part of the codebase you are working on.

Rule files handle everything else. Here is a practical split:

CLAUDE.md (project core)

# Project: Inventory Manager
Stack: Next.js 14, Prisma, PostgreSQL, Tailwind CSS

# File Structure
- src/app/ — Next.js app router pages
- src/components/ — Shared React components
- src/lib/ — Utilities, database client, auth helpers
- prisma/ — Schema and migrations
- tests/ — Test files mirroring src/ structure

.claude/rules/frontend.md

# Frontend Conventions

- Functional components only. No class components.
- Props: define as interface, name as ComponentNameProps.
- State: prefer server components. Client components only when interactivity is required.
- Styling: Tailwind utility classes. No CSS modules, no styled-components.
- New components go in src/components/. Page-specific components go in the page directory.
- Images: use next/image with explicit width/height. No unoptimized images.

.claude/rules/backend.md

# Backend Conventions

- API routes in src/app/api/. One directory per resource.
- Use Prisma for all database operations. No raw SQL.
- Validate request bodies with Zod schemas defined in src/lib/schemas/.
- Error responses: { error: string, code: string } format. Always include HTTP status code.
- Auth: check session in every API route. Use the auth() helper from src/lib/auth.ts.

.claude/rules/testing.md

# Testing

- Framework: Vitest
- Run all: npm test
- Run single: npx vitest run tests/path/to/test.ts
- Write tests for every new API route and every component with logic.
- Mock external services with msw. Never mock Prisma — tests hit the test database.
- Test files: same name as source file with .test.ts suffix.
- Assertions: use expect().toBe() for primitives, expect().toEqual() for objects.

.claude/rules/guardrails.md

# Guardrails

- Never delete files with rm. Move to .trash/ directory.
- Never modify prisma/migrations/ files after they have been applied.
- Never push to main directly. All changes go through feature branches.
- Never install new dependencies without asking first.
- Never modify .env files. Environment variables are managed externally.
- Do not create files outside of src/, tests/, or prisma/ without confirmation.

How Claude loads everything together

At session start, Claude Code reads three things:

1. ~/.claude/CLAUDE.md — Your global config (personal preferences that apply everywhere)
2. CLAUDE.md — Your project config (the core file in the repo root)
3. .claude/rules/*.md — All rule files in the directory

These combine into one context. There is no hierarchy; rules from all sources apply equally. If two files contradict each other, Claude uses the more specific instruction, but it is better to avoid contradictions entirely.

Naming conventions for rule files

Name files by what they cover, not by when they were created. Good names:

• frontend.md, backend.md, testing.md
• react-components.md, api-routes.md, database.md
• guardrails.md, deployment.md, git-workflow.md

Bad names: rules-v2.md, new-rules.md, temp.md. These tell Claude nothing about what is inside.

Team workflows

The rules directory works well for teams because:

• Separate ownership. The frontend lead maintains frontend.md. The backend lead maintains backend.md. No stepping on each other.
• Easier code review. When someone changes a rule, the diff is in a focused file, not buried in a 300-line config.
• Composable. A new team member can add their own rule file without touching existing ones.

Commit the rules directory to your repo. These are project conventions; they should be versioned alongside the code they describe.

Generate your starting point

If you are starting from scratch, the ContextKit Generator builds a complete CLAUDE.md that covers all five key categories: structure, architecture, conventions, testing, and guardrails. From there you can split sections into separate rule files as your project grows.

Already have a config? The ContextKit Analyzer scores your existing setup and tells you exactly which categories are missing. It works with both standalone CLAUDE.md files and combined configs from the rules directory.

The best time to organize your Claude Code config is when it starts slowing you down. If you are scrolling through a long file looking for the testing section, or if different parts of your codebase need different rules, the rules directory is the solution that is already built into the tool.