After experiencing how quickly documentation can drift from reality, we’ve implemented a Hybrid Automation System for CLAUDE.md that ensures it stays perfectly synchronized with our project’s current state. This system combines multiple automation layers to provide immediate, scheduled, and on-demand updates.

The Challenge

CLAUDE.md serves as the critical guidance document for Claude Code when working with our repository. However, maintaining it manually meant:

  • Outdated architecture diagrams when file structures changed
  • Stale dependency lists after pyproject.toml updates
  • Missing recent achievements and development focus areas
  • Manual effort required to keep everything current
  • Risk of forgetting to update it during active development

The Hybrid Solution

Our automation system uses four complementary layers:

1. Template-Based Foundation

  • CLAUDE.template.md provides structure with marked auto-generated sections
  • Static content remains editable while dynamic sections update automatically
  • Clear boundaries between manual and automated content

2. Intelligent Analysis Script

  • scripts/claude_md_updater.py (512 lines) analyzes the entire project
  • Dependencies: Extracts from pyproject.toml and detects tool usage
  • Architecture: Generates live ASCII file trees with descriptive comments
  • Commands: Discovers available tools and development workflows
  • Implementation Status: Detects completed phases based on file presence
  • Recent Development: Analyzes 30 days of commits for themes and achievements

3. GitHub Actions Automation

  • Scheduled updates: Weekly on Sundays at 6 AM UTC
  • Event-driven updates: Triggers on pushes affecting key files
  • Manual dispatch: Force updates when needed
  • Detailed summaries: Shows exactly what changed and why

4. Git Hooks for Immediate Updates

  • post-commit hook: Auto-updates CLAUDE.md after significant commits
  • pre-push hook: Validates sync status before pushing
  • Smart triggers: Only activates for changes affecting src/, tests/, pyproject.toml

What Gets Updated Automatically

The system maintains five key sections:

Dependencies Section

- **Core Dependencies**: Typer CLI framework, Rich progress indicators
- **Testing Framework**: pytest with PyYAML  
- **CI/CD**: GitHub Actions workflows
- **Documentation**: Jekyll with Just the Docs theme

Architecture Section

src/aditi/
├── cli.py                    # Main CLI with Typer
├── config.py                 # Configuration management with Pydantic
├── vale_container.py         # Container runtime management
└── commands/
    └── init.py               # Initialization command

Commands Section Discovers and categorizes all available tools:

  • Container Setup & Testing
  • Blog Post Management
  • GitHub Pages Development
  • Python Development workflows

Implementation Status Automatically detects completed features by analyzing file presence:

  • ✅ Vale container integration with Podman/Docker support
  • ✅ Complete CLI structure with Typer framework
  • ✅ Blog post validation test suite with regression prevention

Recent Development Focus Analyzes the last 30 days of commits to extract:

  • Latest Achievements: Key features and improvements
  • Current Focus Areas: Primary development themes
  • Key Lessons Learned: Insights from fixes and solutions

Real-World Impact

Before automation:

  • CLAUDE.md updated manually, often outdated
  • Architecture diagrams didn’t match current structure
  • Missing recent development context for Claude Code

After automation:

  • CLAUDE.md always reflects current project state
  • 156 insertions, 113 deletions in the first automated update
  • Multiple trigger mechanisms ensure nothing falls through cracks
  • Claude Code gets accurate, up-to-date guidance automatically

Technical Implementation

The system uses sophisticated project analysis:

def _analyze_completed_features(self) -> Dict[str, List[str]]:
    """Analyze project to determine completed features."""
    completed = {'Phase 0': [], 'Phase 1': [], 'Documentation & Quality Assurance': []}
    
    # Check for Phase 0 completions
    if (self.root / 'src' / 'aditi' / 'vale_container.py').exists():
        completed['Phase 0'].append('✅ Vale container integration with Podman/Docker support')

The updater intelligently categorizes dependencies, generates file trees, and even analyzes commit messages to understand development themes and extract lessons learned.

Management and Maintenance

Hook Management:

./scripts/manage-git-hooks.sh status   # Check installation
./scripts/manage-git-hooks.sh remove   # Remove hooks
./scripts/manage-git-hooks.sh install  # Reinstall hooks

Manual Updates:

python scripts/claude_md_updater.py        # Update all sections
python scripts/claude_md_updater.py --force # Force update

Monitoring:

  • GitHub Actions provide detailed summaries of changes
  • Git hooks give immediate feedback on updates
  • All automation is transparent with clear commit messages

Why This Matters

This hybrid approach ensures that CLAUDE.md remains a living document that accurately reflects our project’s current state. Whether Claude Code needs to understand our architecture, discover available tools, or learn about recent development focus, the documentation is always current and comprehensive.

The system eliminates documentation drift while preserving human control over strategic content. It’s automation that enhances rather than replaces human insight—exactly what modern development workflows need.

Next Steps

With CLAUDE.md automation in place, we can focus on core development knowing that our documentation infrastructure will keep pace automatically. The system is designed to evolve with the project, adding new auto-generated sections as needs arise.

This automation system ensures CLAUDE.md remains an accurate, up-to-date guide for Claude Code while minimizing manual maintenance overhead.

Copyright © 2025 Aditi. Distributed under the MIT License.