Skip to content
LiveNew tools this week
Submit
AIMarketly
claude-md-editor logo

CLAUDE.md Writing Guidelines

claude-md-editor

Edit and maintain CLAUDE.md and project documentation files. Use when modifying documentation, asking about best practices, or performing documentation maintenance tasks.

diegosouzapw/awesome-omni-skill0installs62starsDevOps & CI/CD

SKILL.md

Full skill instructions

CLAUDE.md Writing Guidelines

Guidelines for writing effective CLAUDE.md files, based on Anthropic's official best practices.

Purpose of CLAUDE.md

CLAUDE.md is automatically pulled into context. Document:

  • Common bash commands - Build, test, lint, deploy
  • Core files and utilities - Key files Claude should know
  • Code style guidelines - Formatting, patterns, conventions
  • Testing instructions - How to run tests, patterns
  • Repository etiquette - Branch naming, PR conventions
  • Unexpected behaviors - Known gotchas, things that cause problems

Core Principles

1. Keep It Concise

"You're writing for Claude, not onboarding a junior dev."

CLAUDE.md consumes tokens on every prompt. Every line should earn its place.

DO:

  • Write for Claude, not humans
  • Use bullet points and tables over prose
  • Link to detailed docs instead of duplicating
  • Regularly audit and remove outdated content

DON'T:

  • Include verbose explanations
  • Duplicate information from code/​comments
  • Add documentation that's rarely referenced
  • Include Table of Contents (Claude doesn't need navigation)

2. Use Emphasis Markers

Claude follows instructions better with explicit emphasis:

  • IMPORTANT: - Rules that need attention
  • CRITICAL: - Rules that must never be violated
  • NEVER: - Absolute prohibitions
  • ALWAYS: - Absolute requirements

3. Use Tables for Quick Reference

Tables are scannable and token-efficient:

| Client Context | Import From | Notes |
|----------------|-------------|-------|
| Server Components | `@/​lib/​server` | Must await |
| Client Components | `@/​lib/​client` | No await |

4. Use DO/​DON'T Examples

// DON'T: Use raw color values
<p className="text-gray-500">Text</​p>

// DO: Use semantic tokens
<p className="text-muted">Text</​p>

5. Create a "Danger Zone" Section

Group actions that cause problems:

## Danger Zone

| Action | Consequence |
|--------|-------------|
| `npm run dev` automatically | Dev server already running |
| `as any` casts | Defeats TypeScript |

Structure Recommendation

# CLAUDE.md

## Project Overview
## Quick Start
## Architecture
## Danger Zone
## Critical Rules
## Common Patterns
## Environment Setup
## Troubleshooting
## Additional Documentation

What to Include vs. Link

Include Directly

  • Commands Claude runs frequently
  • Critical rules that must never be violated
  • Quick reference tables
  • Brief DO/​DON'T examples
  • Danger Zone items

Link to External Docs

  • Detailed setup guides
  • Comprehensive code examples
  • Full API documentation
  • Any content > 50 lines on a single topic

Anti-Patterns to Avoid

Verbose Explanations

# Too verbose
The middleware handles authentication by using the server-side
utilities. It's critically important that you understand...

# Concise
**Middleware:** Return exact response from `updateSession()`.

Table of Contents

Claude doesn't need navigation aids. ToCs waste tokens.

Obvious Instructions

# Claude already knows this
Use proper types. Write clean code.

# Project-specific
Use `Tables<'table_name'>` helpers, never verbose syntax.

Duplicated Rules

Audit for rules stated multiple times. Consolidate into one location.

Modular Rules Architecture

For larger projects, use modular rules in .claude/​rules/:

# CLAUDE.md (lean hub)

## Rules Reference

| Rule File | Contents |
|-----------|----------|
| `architecture.md` | Route structure, data flow |
| `patterns.md` | Common code patterns |
| `danger-zone.md` | All "never do" rules |

Benefits:

  • Agents can include specific rule bundles
  • Easier maintenance
  • Reduces main CLAUDE.md size

Tuning Your CLAUDE.md

Iterate Like a Prompt

  1. Observe - Notice when Claude doesn't follow instructions
  2. Strengthen - Add emphasis markers (IMPORTANT, NEVER)
  3. Simplify - Remove content Claude doesn't reference
  4. Test - Try different phrasings

Regular Audits

  • Remove rules Claude consistently follows without prompting
  • Strengthen rules Claude frequently ignores
  • Update after major codebase changes
  • Remove references to deleted files/​patterns

Review Checklist

  • Can each section be shorter?
  • Is every instruction necessary?
  • Are critical rules emphasized?
  • Is verbose content moved to linked docs?
  • Are there redundant sections?
  • Is there a Table of Contents? (Remove it)

Resources