Teaching Claude Code your standards with rule files

I use CLAUDE.md for facts that matter in every session and .claude/rules/ for detailed instructions on one topic. Rules without a paths field load when the session starts. Path-scoped rules load when Claude reads a matching file.

Rules vs. CLAUDE.md

• CLAUDE.md: What the project is and which facts apply to all work.
• Rule files: How the project handles one topic, with optional path scope.

Where Rules Live

my-website/
  .claude/
    rules/
      design.md
      content.md
      structure.md
  CLAUDE.md
  index.html
  ...

Each .md file in .claude/rules/ is one rule file. Unscoped rules are available from the start. A path-scoped rule waits until Claude reads a matching file.

Your First Rule File

Let's say you have specific design standards for your website. Create .claude/rules/design.md:

# Design Standards

## Colors
- Background: #1a1a1a (almost black)
- Text: #f0f0f0 (off-white)
- Accent: #00ff88 (bright green)
- Muted text: #888888 (gray)

## Typography
- Headings: bold, uppercase
- Body text: regular weight, 1.6 line height
- Font: Inter for everything

## Layout
- Maximum content width: 800px
- Sections separated by a thin gray line
- No rounded corners anywhere
- Consistent spacing: 20px between elements, 60px between sections

## Don'ts
- No gradients
- No shadows
- No animations that take more than 0.3 seconds
- No light backgrounds

Claude now has the design standards in its project context. You do not need to paste them into every prompt, but you still need to review the result because rules guide behavior rather than enforce it.

Keep Rules Short

I keep each rule file under 100 lines because shorter files are easier for me to review and less likely to contain conflicting instructions. Many of mine are 20 to 30 lines.

What makes a rule file short:

• Bullet points, not paragraphs. "Use 2-space indentation" beats a paragraph explaining why.
• Use examples only when needed. A project-specific code example can be clearer than a sentence.
• One topic per file. If you're covering two unrelated things, make two files.

If a rule file is getting long, ask Claude to help trim it: "Read my design.md rule file and make it more concise. Keep the essential rules, remove redundancy, no code examples."

Path-Specific Rules

Use path scope when an instruction only applies to certain files or folders.

Say you have API-specific standards that only matter when working in your api/ folder. You can scope rules using a paths field at the top of the file:

---
paths:
  - "api/**/*.js"
---

# API Rules

- All endpoints return JSON
- Include error handling for every route
- Log all incoming requests

This rule only loads when Claude is working with JavaScript files in the api/ folder. When Claude is editing your CSS or HTML, these rules stay out of the way.

The paths field supports patterns:

• **/*.css: All CSS files anywhere
• src/**/*: Everything in the src folder
• *.html: HTML files in the root only
• components/**/*.js: JavaScript files in components

Use path-specific rules when:

• Different folders have different conventions
• You want to keep unrelated rules from cluttering context
• You have language-specific or area-specific standards

Most projects don't need this. But it's useful to know it exists.

When to Use Rules (Not CLAUDE.md)

Create a rule file when:

• The topic needs more than 5 lines. If your design standards are 30 lines, they belong in a rule file, not crammed into CLAUDE.md.
• The instructions are topic-specific. CSS rules don't need to load when Claude is writing content. Separate topics, separate files.
• You keep correcting the same mistake. If Claude keeps using the wrong font or putting files in the wrong folder, write a rule that prevents it.

Stick with CLAUDE.md when:

• It's a general project fact (name, purpose, tech stack)
• It's short (one or two lines)
• It applies to everything, not just one topic

Example Rule Files

A content.md for writing standards:

# Content Rules

## Tone
- Professional but conversational
- No jargon unless explained
- Short paragraphs (3-4 sentences max)

## Formatting
- Every page needs an H1 heading
- Use H2 for sections, H3 for subsections
- Lists are preferred over long paragraphs

## SEO
- Every page needs a title tag (under 60 characters)
- Every page needs a meta description (under 160 characters)
- Use descriptive link text, never "click here"

And a structure.md for project organization:

# Project Structure

## Folders
- pages/ - All HTML pages
- css/ - Stylesheets
- images/ - All images (photos, icons, logos)
- docs/ - Planning documents (not part of the website)

## File Naming
- Lowercase only
- Dashes instead of spaces: about-me.html not about me.html
- Descriptive names: team-photo.jpg not IMG_4523.jpg

## Rules
- New pages go in pages/
- New images go in images/
- Never create files in the project root (except index.html)

How I Use Rules

I have 16 rule files for my website. One covers CSS conventions, including where existing components live and when Claude should reuse them instead of adding another style. Others cover database patterns, security practices, and controller structure.

Sounds like a lot. But each one grew from a real problem. The CSS rules file exists because Claude kept creating duplicate styles. The security file exists because I wanted consistent escaping patterns. Every rule traces back to something Claude got wrong that I never wanted to correct again.

You probably won't need 13 rule files for a personal website. One or two is plenty to start. Design standards and content rules cover most cases.

A Simple Workflow

Here's how rules develop naturally:

1. You start a project with just CLAUDE.md
2. Claude does something wrong (uses the wrong color, puts a file in the wrong place)
3. You correct Claude in the conversation
4. It happens again in a later session (Claude forgot, new session)
5. After the same correction appears twice, you create a rule for the next session

The rule gives the next session the same instruction. I still check whether the result follows it.

For the complete reference on rule files, see the official documentation.

Next up: how I organize a larger project so Claude can find the right file and instruction.