Authoring Claude Md

CLAUDE.md and Rules Authoring

Create effective CLAUDE.md files and .claude/rules/ rule files that serve as project-specific memory for AI coding agents.

Purpose

CLAUDE.md files and rule files provide AI agents with:

• Non-obvious conventions, architectural patterns and gotchas
• Confirmed solutions to recurring issues
• Project-specific context not found in standard documentation
• Path-scoped instructions that only load when relevant files are touched

Not for: obvious patterns, duplicating documentation, or generic coding advice.

Core Principles

• Signal over noise: Every sentence must add non-obvious value. If an AI agent could infer it from reading the codebase, omit it.
• Actionable context: Focus on "what to do" and "why it matters", not descriptions of what exists.
• Solve real friction, not theoretical concerns: Add to CLAUDE.md based on actual problems encountered, not hypothetical scenarios. If you repeatedly explain the same thing to Claude, document it. If you haven't hit the problem yet, don't pre-emptively solve it.

Structure

Use headings for clear organisation. Common sections: Architecture, Conventions, Gotchas, Testing. Use 2-4 sections and only include what adds value.

When to Use .claude/rules/ Instead

For larger projects, break instructions into separate files under .claude/rules/. Each .md file covers one topic. Prefer rules over a single CLAUDE.md when:

• Instructions are growing beyond 200 lines
• Different rules apply to different parts of the codebase (frontend vs backend, API vs CLI)
• Multiple team members maintain different sections
• Some instructions only matter when working with specific file types

Rule File Basics

your-project/
├── .claude/
│   ├── CLAUDE.md           # Main project instructions
│   └── rules/
│       ├── code-style.md   # Always loaded
│       ├── testing.md      # Always loaded
│       └── security.md     # Always loaded

Files are discovered recursively, so subdirectories like frontend/ and backend/ work. Rules without paths frontmatter load at launch with the same priority as .claude/CLAUDE.md.

The same authoring principles apply to rule files: signal over noise, actionable context, no obvious information.

Path-Specific Rules

Scope rules to specific files using YAML frontmatter with the paths field. These only load when Claude reads files matching the glob patterns, reducing noise and saving context.

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

Rules without a paths field apply unconditionally. Path-scoped rules trigger on file read, not on every tool use.

User-Level Rules

Personal rules that apply across all your projects live at ~/.claude/rules/. These load before project rules, giving project rules higher priority.

~/.claude/rules/
├── preferences.md    # Personal coding preferences
└── workflows.md      # Preferred workflows

Rules vs Skills

Rules load every session (or when matching files are opened). For task-specific instructions that don't need constant context, use skills instead. Skills load only when invoked or when Claude determines they're relevant.

What to Include

Architectural decisions: Why microservices over monolith, event-driven patterns, state management

Non-obvious conventions:

• "Use _internal suffix for private APIs not caught by linter"
• "Date fields always UTC, formatting happens client-side"
• "Avoid ORM for reports, use raw SQL in /queries"

Recurring issues:

• "TypeError in auth: ensure verify() uses Buffer.from(secret, 'base64')"
• "Cache race condition: acquire lock before checking status"

Project patterns: Error handling, logging, API versioning, migrations

What to Exclude

• Line numbers: files change and references break. Use descriptive paths: "in src/auth/middleware.ts" not "line 42"
• Obvious information: "We use React" (visible in package.json). LLMs are in-context learners and pick up patterns from codebase exploration.
• Code style guidelines: formatting rules, naming conventions, or patterns that linters enforce. Use ESLint, Prettier, Black, golangci-lint or similar, and Claude Code Hooks to run formatters.
• Generic advice: "Write good tests" adds no project-specific value.
• Setup steps: belong in README unless highly non-standard.
• Duplicate content: if it's in the README or existing docs, link to it rather than repeat it.
• Task-specific minutiae: database schemas, API specifications, deployment procedures belong in their own docs. Link to them rather than duplicating.
• Temporary notes: TODOs, one-off bug fixes, and temporary workarounds belong in code comments.
• Verbose descriptions: keep entries terse, drop long explanations.
• Kitchen sink entries: not every gotcha belongs here. Ask "Is this relevant across most coding sessions?" If no, it belongs in code comments or specific docs.
• Formatting over-emphasis: don't bold the start of every sentence or bullet, reserve emphasis for warnings that truly warrant it.