CLAUDE.md Structure Standards

Beginner

Enforce consistent CLAUDE.md file structure with required sections, length limits, and formatting rules so Claude Code receives optimal project context in every interaction.

File Patterns

**/CLAUDE.md**/.claude/**

This rule applies to files matching the patterns above.

Rule Content

rule-content.md

# CLAUDE.md Structure Standards

## Rule
Every project using Claude Code MUST have a CLAUDE.md at the repository root following this structure. Maximum 500 lines.

## Required Sections

### 1. Project Overview (Required)
```markdown
# Project Name

## Overview
One paragraph describing what the project does, its tech stack, and key architecture decisions.

## Tech Stack
- Framework: [name + version]
- Language: [name + version]
- Database: [name]
- Styling: [approach]
```

### 2. Directory Structure (Required)
```markdown
## Directory Structure
\`\`\`
src/
  components/   # React components
  lib/          # Utilities and services
  types/        # TypeScript type definitions
\`\`\`
```

### 3. Conventions (Required)
```markdown
## Conventions
- Naming: PascalCase components, camelCase functions
- Imports: use @/ alias, group by category
- State: Zustand for client, React Query for server
```

### 4. Anti-Patterns (Required)
```markdown
## NEVER Do
- NEVER use \`any\` type
- NEVER use default exports (except pages)
- NEVER hardcode secrets
```

### 5. Commands (Recommended)
```markdown
## Commands
- \`npm run dev\` — development server
- \`npm run build\` — production build
- \`npm run test\` — run tests
```

## Good Example
A complete, scannable CLAUDE.md with bullet points, code blocks, and clear sections under 300 lines.

## Bad Example
- A 2000-line CLAUDE.md with full file contents pasted in
- A CLAUDE.md with only "This is a Next.js project"
- A CLAUDE.md that contradicts itself between sections
- No CLAUDE.md at all

## Enforcement
Review CLAUDE.md in code review. Ensure it stays under 500 lines and includes all required sections. Update when conventions change.

FAQ

Discussion

Loading comments...

# CLAUDE.md Structure Standards ## Rule Every project using Claude Code MUST have a CLAUDE.md at the repository root following this structure. Maximum 500 lines. ## Required Sections ### 1. Project Overview (Required) ```markdown # Project Name ## Overview One paragraph describing what the project does, its tech stack, and key architecture decisions. ## Tech Stack - Framework: [name + version] - Language: [name + version] - Database: [name] - Styling: [approach] ``` ### 2. Directory Structure (Required) ```markdown ## Directory Structure \`\`\` src/ components/ # React components lib/ # Utilities and services types/ # TypeScript type definitions \`\`\` ``` ### 3. Conventions (Required) ```markdown ## Conventions - Naming: PascalCase components, camelCase functions - Imports: use @/ alias, group by category - State: Zustand for client, React Query for server ``` ### 4. Anti-Patterns (Required) ```markdown ## NEVER Do - NEVER use \`any\` type - NEVER use default exports (except pages) - NEVER hardcode secrets ``` ### 5. Commands (Recommended) ```markdown ## Commands - \`npm run dev\` — development server - \`npm run build\` — production build - \`npm run test\` — run tests ``` ## Good Example A complete, scannable CLAUDE.md with bullet points, code blocks, and clear sections under 300 lines. ## Bad Example - A 2000-line CLAUDE.md with full file contents pasted in - A CLAUDE.md with only "This is a Next.js project" - A CLAUDE.md that contradicts itself between sections - No CLAUDE.md at all ## Enforcement Review CLAUDE.md in code review. Ensure it stays under 500 lines and includes all required sections. Update when conventions change.