CLAUDE.md Synthesis Tool

Overview

The CLAUDE.md synthesis tool automatically extracts and structures key operational information from the CLAUDE.md operating instructions file. This creates quick reference documents for developers and operators who need rapid access to critical information.

What It Does

The synthesis script (scripts/synthesize-claude-md.js) parses CLAUDE.md and extracts:

• Environments: Azure PROD, Azure DDE, and AWS environment details
• AWS Accounts: All 7 AWS accounts with IDs and purposes
• Repositories: Infrastructure and documentation repos
• Security Hard Rules: Critical never-violate rules
• Architecture Principles: Core design principles
• Current Priorities: Active work items in priority order
• Break-Glass Accounts: Critical accounts that must never be suppressed
• Key People: Team members and their responsibilities
• Technical Gotchas: Known issues and workarounds

Usage

Running the Synthesis

npm run synthesize

This generates two output files in the docs/ directory:

1. docs/claude-synthesis.md — Human-readable markdown reference
2. docs/claude-synthesis.json — Machine-readable structured data

Output Files

claude-synthesis.md

A formatted markdown document with all extracted information, suitable for:

• Quick reference during incident response
• Onboarding new team members
• Sharing operational context without exposing the full CLAUDE.md

claude-synthesis.json

Structured JSON data containing the same information, suitable for:

• Programmatic access to operational data
• Integration with other tools
• Building dashboards or automation

When to Run

The synthesis tool runs automatically via GitHub Actions whenever CLAUDE.md is pushed to main. Manual runs are available via:

npm run synthesize

Run manually when:

• Testing CLAUDE.md format changes locally
• Verifying extraction logic before committing
• Generating synthesis output in a branch before PR

Example Output Structure

{
  "environments": [
    { "name": "Azure PROD", "details": "..." }
  ],
  "awsAccounts": [
    { "name": "Management", "id": "206820231356", "purpose": "Org root" }
  ],
  "hardRules": [
    "Never terraform apply locally...",
    "Never push directly to main..."
  ],
  "currentPriorities": [
    { "order": 1, "task": "Cloud PC migration..." }
  ],
  "breakGlassAccounts": [
    "cirius-breakglass@ciriusgroup.com"
  ],
  "keyPeople": [
    { "name": "Rory", "role": "Sole IT/security, architect", "notes": "..." }
  ],
  "gotchas": [
    "Palo Alto marketplace images don't support encryption_at_host..."
  ]
}

Integration Ideas

The structured JSON output enables:

1. Dashboard Integration: Display current priorities on the SecOps dashboard
2. Alerting: Reference break-glass accounts in alert suppression logic
3. Onboarding Automation: Generate personalized onboarding checklists
4. Documentation Generation: Auto-populate architecture diagrams with environment data
5. Compliance Reporting: Extract key people and responsibilities for audit evidence

Maintenance

The script uses regex patterns to extract information from CLAUDE.md. If the format of CLAUDE.md changes significantly, update the patterns in scripts/synthesize-claude-md.js:

• envMatch: Environment table extraction
• awsMatch: AWS accounts table
• hardRulesSection: Security hard rules section
• prioritiesSection: Current priorities section
• etc.

Technical Details

• Language: JavaScript (Node.js)
• Dependencies: Node.js built-ins only (fs, path)
• Input: /workspace/bedrock-docs/CLAUDE.md
• Output: /workspace/bedrock-docs/docs/claude-synthesis.{md,json}
• Execution time: < 1 second

Features

The synthesis tool includes:

Automatic CI/CD Integration ✅

• GitHub Actions workflow auto-runs on CLAUDE.md changes
• Commits updated synthesis output automatically
• No manual intervention required

Diff Detection ✅

• Compares current extraction with previous output
• Shows detailed diffs with specific items added/removed
• Highlights changes in critical sections:
  • Security hard rules (with full text of changes)
  • Current priorities (with task details)
  • Break-glass accounts (with account names)
  • AWS accounts (with account names and IDs)
  • Key people (with names and roles)
  • Repositories (with repo names)
  • Technical gotchas (with gotcha summaries)

Validation ✅

• Verifies all critical sections are present
• Errors if hard rules or break-glass accounts are missing
• Warns if other sections are empty
• Prevents incomplete synthesis from being committed

Output Summary

• Clear statistics on what was extracted
• Change detection summary
• Validation warnings and errors

Changelog

v1.1 - 2026-06-28

• ✅ Detailed Diff: Now shows specific items added/removed, not just counts
  • When hard rules change, see exactly which rule was added or removed
  • When priorities change, see the full task description
  • When AWS accounts change, see account name and ID
  • Summaries are truncated to 60-80 characters for readability
• Enhanced markdown output with better "About This Document" section

Future Enhancements

Potential improvements:

1. Detailed Diff: Show specific items added/removed, not just counts ✅ DONE (v1.1)
2. Notification: Telegram/Slack alert when critical sections change
3. Multi-format Output: Generate HTML, PDF, or other formats
4. Historical Tracking: Store synthesis history for trend analysis
5. Content Validation: Verify specific expected values (e.g., known account IDs)