edit-claude

name	edit-claude
description	Creates, updates, or optimizes CLAUDE.md files following Anthropic best practices. Use when user requests creating, updating, improving, or optimizing CLAUDE.md files for project context, coding standards, or persistent memory.

Instructions for Managing CLAUDE.md Files

Determine Action Type

CREATE: New CLAUDE.md file requested UPDATE: Modify existing CLAUDE.md (keywords: "update", "add", "modify", "change") OPTIMIZE: Improve token efficiency (keywords: "optimize", "reduce tokens", "improve")

Updating Existing CLAUDE.md Files

1. Read current file: Always read before editing
2. Identify section: Locate relevant section or create new heading
3. Make surgical edits: Use Edit tool for precise changes
4. Preserve structure: Maintain existing organization patterns
5. Validate: Ensure markdown is valid and clear

Optimizing CLAUDE.md Files

1. Audit current content:

   • Identify verbose prose that can become bullets
   • Find repetitive information
   • Locate outdated or irrelevant content

2. Apply compression techniques:

   • Convert paragraphs → bullets or tables
   • Remove unnecessary words and filler
   • Use abbreviations where context is clear
   • Group similar items together

3. Remove anti-patterns:

   • Delete sensitive information (credentials, tokens)
   • Remove frequently changing data
   • Extract verbose documentation to separate files
   • Remove duplicate information

4. Validate token efficiency: Aim for maximum signal, minimum tokens

See reference.md for optimization strategies and examples.

Creating New CLAUDE.md Files

1. Gather context: Ask user for project details if missing:

   • Coding standards (indentation, naming conventions)
   • Build/test/deployment commands
   • Architectural patterns
   • Security requirements

2. Organize around WHAT/WHY/HOW:

   • WHAT: Tech stack, codebase map, key packages
   • WHY: Project purpose, component responsibilities
   • HOW: Build/test/deploy commands, verification methods

3. Determine organization strategy (memory hierarchy):

   Main CLAUDE.md (universal, <200 tokens ideal, <500 acceptable):

   • Build/test/deploy commands
   • Universal code style applying to all files
   • Critical patterns used everywhere
   • Cohesive project-wide conventions (Git, Security, Planning, Style)
   • CLAUDE.md in project root (shared via git)

   .claude/rules/ (modular, 100-300 tokens each):

   • Path/language-specific files (auto-loaded): python.md, javascript.md
   • Domain-specific patterns: frontend/, backend/
   • Path-specific rules with frontmatter (see reference.md)

   CLAUDE.local.md (personal, auto-gitignored):

   • Personal preferences not shared with team
   • Local dev shortcuts, experimental rules

   ~/.claude/CLAUDE.md (cross-project personal):

   • Universal personal preferences across all projects

   @imports (lazy-loaded reference):

   • External docs: @README, @docs/architecture.md
   • Home directory: @~/.claude/my-prefs.md

   Memory load order (later overrides earlier):

   1. Enterprise policy → 2. Project memory → 3. Project rules (.claude/rules/) → 4. User memory (~/.claude/) → 5. Project local (CLAUDE.local.md)

4. File Zones (if project uses ref/wip pattern):

   • Detect folder names: ref/ or reference/ (read-only), wip/ or work-in-progress/ (workspace). Use whichever name the project already has.
   • Add to CLAUDE.md:

     ## File Zones
     - 🔒 ref/ (or reference/) — READ-ONLY. Never edit unless user explicitly says "update ref". Show diff and ask first.
     - ✏️ wip/ (or work-in-progress/) — Default workspace. All new files and edits go here.
     - 🔒 .in/ — READ-ONLY archive. Never modify.
     

   • Include this section in main CLAUDE.md for all projects using ref/wip (non-technical users especially benefit from visual clarity)

5. Organization decision tree:

   • Universal + cohesive (Git/Security/Planning/File Zones)? → Main CLAUDE.md (even if 200-500 tokens)
   • Path/language-specific (Python/JS/Bash rules)? → .claude/rules/lang.md with frontmatter
   • Domain-specific (frontend/backend patterns)? → .claude/rules/domain/
   • Topic >300 tokens standalone? → Consider .claude/rules/topic.md
   • Personal preferences? → CLAUDE.local.md or ~/.claude/
   • Detailed reference docs? → @import external docs

6. Universal vs Path-Specific Decision:

   Keep in main CLAUDE.md:

   • Universal conventions applying to ALL files/operations
   • Cohesive conceptual units (Git workflow, Security policies, Style guides)
   • Even if combined total is 200-500 tokens
   • Examples: commit format, pre-commit flow, security exclusions, output formatting

   Extract to .claude/rules/:

   • Path/language-specific rules (Python for *.py, React for *.tsx)
   • Domain-specific patterns (frontend/, backend/, infra/)
   • When single topic exceeds ~300 tokens standalone
   • Examples: python.md with paths: "**/*.py", bash-scripting.md with paths: "**/*.sh"

   Key principle: Cohesion and semantic grouping matter more than strict token limits. A well-organized 430-token CLAUDE.md with universal sections (Git 90 + Security 50 + Planning 45 + Style 200 = 385 tokens) is better than fragmenting conceptually related content across multiple files.

7. H1 = Project Name (required):

   • First line MUST be # Project Name — used by /switch, /save-context, /load-context for project identification
   • Examples: # Praxis, # NanoVC — Control Repo, # GTD-PCM Control Plane

8. Structure content (token-efficient):

   • Use markdown headings for organization
   • Use tables and bullets over prose
   • Be specific (e.g., "Use 2-space indentation" not "Format code properly")
   • Group related items logically

9. Include sanity marker (optional but recommended):

   sanity check: [random-number]
   

10. Write file with appropriate sections based on user context

See reference.md § Templates for starter examples and § Modular Rules for .claude/rules/ patterns.

⚠️ Hard Char Limits (from Claude Code source)

Claude Code enforces hard character limits on instruction files. Content beyond these limits is silently truncated with [truncated] appended — no warning to the user.

Limit	Value	Source
Per file	4,000 chars	MAX_INSTRUCTION_FILE_CHARS
Total across all files	12,000 chars	MAX_TOTAL_INSTRUCTION_CHARS

Loading order: Files are loaded walking from filesystem root to CWD. Once total budget is exhausted: "Additional instruction content omitted after reaching the prompt budget." — deeper files (closer to CWD) are the ones that get dropped.

Implications:

• A CLAUDE.md chain of 4 files (e.g., ~/.claude/ → praxis root → repo → subfolder) shares the 12K budget
• Files with identical content (after whitespace normalization) are auto-deduped
• Run claude --dump-system-prompt to verify what actually loads
• Run wc -c on each file in the chain to check headroom

When creating/updating: Always check current chain total. Warn user if any file is >3,500 chars or chain total >10,000 chars.

Key Principles

• Specific over generic: "Run npm test" not "Test the code"
• Persistent not temporary: Coding standards yes, current bug no
• Concise not verbose: Bullets and tables over paragraphs
• Modular organization: Main CLAUDE.md + .claude/rules/ + @imports
• Path-specific when needed: Frontmatter with paths: glob patterns
• Secure: Never include credentials or sensitive data

MANDATORY Validation (CREATE only)

STOP: Before creating new CLAUDE.md, answer YES/NO for each:

• Q1: Persistent (not temporary)? [YES/NO]
• Q2: Frequently referenced (coding standards, workflows)? [YES/NO]
• Q3: Concise (avoid verbose docs)? [YES/NO]
• Q4: Non-sensitive (no credentials/tokens)? [YES/NO]

If ANY answer is NO: → STOP. Explain why inappropriate. → Recommend alternatives: README.md (docs), environment variables (secrets), direct request (one-time), .claude/rules/ (detailed guidelines) → EXIT immediately.

If ALL answers are YES: → Proceed to "Creating New CLAUDE.md Files" section above.

---

Progressive Disclosure

Keep main CLAUDE.md lean (<200 tokens). Distribute content:

Modular rules (.claude/rules/ - auto-loaded):

.claude/rules/
  |- code-style.md
  |- security.md
  |- frontend/react.md
  |- backend/api.md

Imports (lazy-loaded when referenced):

@README
@docs/architecture.md
@~/.claude/my-project-prefs.md

Reference docs (external):

reference/
  |- runbooks/building.md
  |- standards/conventions.md

Use /memory command during session to view/edit loaded memories.

Constraints

• Hard char limits: 4,000 chars/file, 12,000 chars total chain (see ⚠️ Hard Char Limits above)
• Instruction budget: LLMs follow ~150-200 instructions reliably. Claude Code's system prompt uses ~50, leaving ~100 for CLAUDE.md
• Token target: Main CLAUDE.md <200 tokens ideal, <500 acceptable for universal cohesive content
• Universal relevance: Every line should apply to most sessions, not task-specific work
• Modular distribution: Use .claude/rules/ for path/language/domain-specific content, not to fragment universal cohesive sections
• Cohesion over tokens: Keep conceptually related universal sections together (Git, Security, Planning, Style) even if combined total is 200-500 tokens

See reference.md § Content Guidelines for inclusion/exclusion rules and anti-patterns.

Validation Checklist

• Information is persistent and frequently referenced
• No sensitive credentials or tokens included
• Content is concise and token-efficient (<200 tokens for main CLAUDE.md)
• Markdown structure is clear with headings
• Specific guidelines (not generic advice)
• Appropriate organization: main vs .claude/rules/ vs @imports
• Path-specific rules use frontmatter (if applicable)
• Sanity marker included (optional)

See reference.md § Templates, § Modular Rules, and § Import Syntax for detailed examples.