claude-md

name	claude-md
description	Create or update CLAUDE.md files following best practices for optimal AI agent onboarding

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty). User may specify:

• create - Create new CLAUDE.md from scratch
• update - Improve existing CLAUDE.md
• audit - Analyze and report on current CLAUDE.md quality
• A specific path to create/update (e.g., src/api/CLAUDE.md for directory-specific instructions)

Core Principles

LLMs are stateless: CLAUDE.md is the only file automatically included in every conversation. It serves as the primary onboarding document for AI agents into your codebase.

The Golden Rules

1. Less is More: Frontier LLMs can follow ~150-200 instructions. Claude Code's system prompt already uses ~50. Keep your CLAUDE.md focused and concise.

2. Universal Applicability: Only include information relevant to EVERY session. Task-specific instructions belong in separate files.

3. Don't Use Claude as a Linter: Style guidelines bloat context and degrade instruction-following. Use deterministic tools (prettier, eslint, etc.) instead.

4. Never Auto-Generate: CLAUDE.md is the highest leverage point of the AI harness. Craft it manually with careful consideration.

Execution Flow

1. Project Analysis

First, analyze the current project state:

1. Check for existing CLAUDE.md files:

   • Root level: ./CLAUDE.md or .claude/CLAUDE.md