CLAUDE.md Maintenance Guide

Overview

GetCimple uses a distributed hub-and-spoke architecture for CLAUDE.md files. This guide explains how to maintain these files to ensure Claude Code always has the right context.

Architecture

Hub-and-Spoke Model

Root CLAUDE.md (hub) - High-level project context & navigation
├── docs-internal/CLAUDE.md - Internal documentation workflows
├── docs-customer/CLAUDE.md - Customer documentation guidelines
├── scripts/CLAUDE.md - Validation scripts & rules
├── ai-docs/CLAUDE-ai.md - AI development methodology
└── specs/CLAUDE-specs.md - Code style & tech stack

Design Principles

1. Slim root - Keep root CLAUDE.md under 120 lines
2. Domain-specific context - Each directory has targeted guidance
3. Single source of truth - No duplication across files
4. Clear navigation - Backlinks connect hub to spokes
5. Context efficiency - AI loads only relevant context

File Sizes & Scope

File	Target Size	Current	Scope
Root CLAUDE.md	<120 lines	111	Project identity, navigation
docs-internal/CLAUDE.md	<200 lines	272	MkDocs, validation, standards
docs-customer/CLAUDE.md	<200 lines	258	Customer docs, tone, guidelines
scripts/CLAUDE.md	<300 lines	429	Scripts, validation, rules (ok)
ai-docs/CLAUDE-ai.md	<200 lines	160	MCP tools, AI methodology
specs/CLAUDE-specs.md	<200 lines	131	Code style, tech stack, commands
Total distributed	-	1,361	Well-organized across 6 files
Original monolithic (backup)	-	186	All in one file (anti-pattern)

Maintenance Workflow

When to Update CLAUDE.md Files

Update CLAUDE.md files when:

• ✅ Adding new npm scripts or commands
• ✅ Changing validation rules or processes
• ✅ Adding new MCP tools or AI patterns
• ✅ Updating tech stack or coding standards
• ✅ Restructuring directories or files
• ✅ Adding new documentation standards
• ✅ Changing development workflows

Do NOT update for:

• ❌ Minor content edits in documentation
• ❌ Fixing typos in markdown files
• ❌ Adding individual feature docs
• ❌ Updating business process docs

Which File to Update

Change Type	Update File(s)
New npm command	Relevant domain file + root if critical
Documentation standard	docs-internal/CLAUDE.md
Customer content guideline	docs-customer/CLAUDE.md
Validation rule	scripts/CLAUDE.md
MCP tool or AI pattern	ai-docs/CLAUDE-ai.md
Code style or tech stack	specs/CLAUDE-specs.md
Critical instruction	Root CLAUDE.md
New domain directory	Create new CLAUDE.md + update root
Cross-cutting workflow change	Multiple files (ensure consistency)
Project phase change (e.g., "MVP	launching")

Update Process

1. Identify Impact

• What changed?
• Which domain(s) does it affect?
• Is it critical or domain-specific?

2. Update Relevant File(s)

# Edit the appropriate CLAUDE.md file
# For example, adding a new validation command:
vim scripts/CLAUDE.md

3. Check for Duplication

• Search other CLAUDE.md files for similar content
• Remove or consolidate duplicates
• Update cross-references if needed

4. Format and Validate

# Format the updated file
npm run format:docs

# Check for issues
npm run docs:check:all

5. Test Context

• Navigate to the directory
• Verify Claude Code would load correct context
• Check backlinks work

6. Commit with Clear Message

git add <changed-files>
git commit -m "docs: Update CLAUDE.md - <brief description>"

Anti-Patterns to Avoid

1. Context Duplication

❌ WRONG:

# In root CLAUDE.md
npm run docs:check:consistency  # Validation command

# In scripts/CLAUDE.md
npm run docs:check:consistency  # Same command duplicated

✅ RIGHT:

# In root CLAUDE.md
npm run docs:check:all  # Only most common command

# In scripts/CLAUDE.md
npm run docs:check:consistency      # Lenient mode
npm run docs:check:consistency:strict  # Strict mode
# ... detailed validation commands

2. Over-Fragmentation

❌ WRONG:

docs-internal/docs/04-business/CLAUDE.md
docs-internal/docs/05-architecture/CLAUDE.md
docs-internal/docs/06-features/CLAUDE.md
# Too many tiny context files

✅ RIGHT:

docs-internal/CLAUDE.md
# One file covers entire internal docs domain

3. Stale Context

❌ WRONG:

• Command changed 3 months ago
• CLAUDE.md still shows old command
• AI gets confused

✅ RIGHT:

• Include "Update CLAUDE.md" in PR checklist
• Quarterly review of all CLAUDE.md files
• Update immediately when commands change

4. Ambiguous Boundaries

❌ WRONG:

• Same information in specs/CLAUDE-specs.md and docs-internal/CLAUDE.md
• Unclear which one to update
• Content drifts out of sync

✅ RIGHT:

• Clear scope: specs = code, docs-internal = documentation
• Explicit boundaries documented
• Cross-references where needed

Quarterly Maintenance Checklist

Perform these checks every quarter:

1. Content Audit

• Review each CLAUDE.md file for accuracy
• Check commands are current
• Verify links work
• Remove outdated information
• Update examples if needed

2. Size Check

wc -l /home/vic/projects/vichong/getcimple/CLAUDE.md \
      /home/vic/projects/vichong/getcimple/docs-internal/CLAUDE.md \
      /home/vic/projects/vichong/getcimple/docs-customer/CLAUDE.md \
      /home/vic/projects/vichong/getcimple/scripts/CLAUDE.md \
      /home/vic/projects/vichong/getcimple/ai-docs/CLAUDE-ai.md \
      /home/vic/projects/vichong/getcimple/specs/CLAUDE-specs.md

• Root CLAUDE.md under 120 lines?
• Domain files under 200 lines (scripts ok at <300)?
• If over limit, consider splitting or trimming

3. Duplication Scan

# Search for duplicated content across files
grep -r "npm run docs:check" CLAUDE.md */CLAUDE.md

• No duplicate commands
• No duplicate instructions
• Single source of truth maintained

4. Navigation Verification

• All backlinks work (../CLAUDE.md)
• Hub links to all spoke files
• Related context files linked correctly

5. Scope Validation

• Each file has clear, distinct scope
• No overlap or ambiguity
• Boundaries well-defined

Adding New Domain Files

When adding a new CLAUDE.md file:

1. Determine Need

Only create new CLAUDE.md if:

• ✅ New major domain emerges (e.g., /tests, /src)
• ✅ Domain has unique context (different from existing files)
• ✅ Domain will have 5+ unique instructions/patterns
• ✅ Content would exceed 50 lines

Don't create if:

• ❌ Subdirectory of existing domain
• ❌ Only 1-2 unique points
• ❌ Already covered in parent CLAUDE.md

2. Template

# CLAUDE.md - [Domain Name]

_Parent context: [Root CLAUDE.md](../CLAUDE.md)_

This file provides context-specific guidance for [domain description].

## Overview

[Brief description of the domain]

## Quick Command Reference

[Commands specific to this domain]

## [Domain-Specific Sections]

[Content relevant to this domain only]

## Related Context Files

- [Root CLAUDE.md](../CLAUDE.md) - Project overview, critical instructions
- [Other Domain 1](../path/CLAUDE.md) - Description
- [Other Domain 2](../path/CLAUDE.md) - Description

3. Update Root CLAUDE.md

Add to the "Domain-Specific Context" section:

- **[New Domain](./path/CLAUDE.md)** - Brief description

4. Test and Validate

# Format new file
npm run format:docs

# Test context loading
cd [new-domain-directory]
# Verify Claude would load correct context

# Check for issues
npm run docs:check:all

Troubleshooting

Problem: Context Not Loading

Symptom: Claude doesn't seem to have domain-specific context

Solution:

1. Check file exists: ls [domain]/CLAUDE.md
2. Verify backlink: head -n 5 [domain]/CLAUDE.md
3. Ensure file is formatted: npm run format:docs
4. Check Claude Code is reading from correct directory

Problem: Duplicate Information

Symptom: Same instruction appears in multiple files

Solution:

1. Identify canonical location (single source of truth)
2. Remove from other locations
3. Add cross-reference if needed
4. Document in this guide which file owns that content

Problem: File Too Large

Symptom: CLAUDE.md file exceeds recommended size

Solution:

1. Review for unnecessary detail
2. Move examples to separate docs
3. Use references instead of full content
4. Consider if subdomain should split out
5. Ensure no duplication with other files

Problem: Unclear Which File to Update

Symptom: Change could go in multiple files

Solution:

1. Consult "Which File to Update" table above
2. Choose most specific domain
3. If truly cross-cutting, update all relevant files
4. Ensure consistency across updates
5. Consider if abstraction needed

Best Practices

Writing Style

• Be concise - Every line should add value
• Be specific - Use exact commands, not generalities
• Be current - Update immediately when things change
• Be clear - Avoid ambiguity
• Be actionable - Provide commands, not just descriptions

Organization

• Most common first - Put frequent operations at top
• Group related items - Keep similar content together
• Use clear headings - Make sections easy to scan
• Include examples - Show, don't just tell
• Link related context - Help Claude navigate

Maintenance

• Update with changes - Don't let context drift
• Review quarterly - Catch stale information
• Remove duplication - Maintain single source of truth
• Test context - Verify Claude loads correctly
• Document decisions - Why this goes here, not there

Related Documentation

• Documentation Guide - Overall documentation standards
• Context Separation Guide - Internal vs customer context
• Scripts CLAUDE.md - Validation rules and scripts

Backup & Recovery

Backup Location

Original monolithic CLAUDE.md backed up at: CLAUDE.md.backup (186 lines)

Rollback Process

If restructure causes issues:

# Restore original
cp CLAUDE.md.backup CLAUDE.md

# Remove domain files
rm docs-internal/CLAUDE.md docs-customer/CLAUDE.md scripts/CLAUDE.md

# Restore backlinks in existing files
# (manual edit of ai-docs/CLAUDE-ai.md and specs/CLAUDE-specs.md)

Note: Only rollback if critical issue. Distributed model is best practice.

Change Log

2025-01-13: Initial Restructure

• Slimmed root CLAUDE.md from 186 → 111 lines
• Created docs-internal/CLAUDE.md (272 lines)
• Created docs-customer/CLAUDE.md (258 lines)
• Created scripts/CLAUDE.md (429 lines)
• Added backlinks to ai-docs/CLAUDE-ai.md and specs/CLAUDE-specs.md
• Created this maintenance guide

---

Remember: The goal is context efficiency. Each CLAUDE.md file should give Claude exactly what it needs for that domain, nothing more, nothing less.