Self-Maintaining Documentation System Using Fenced Blocks for Zero Drift

A developer on r/ClaudeAI shared a solution for maintaining accurate documentation in multi-project workspaces where AI coding agents like Claude Code forget context between sessions. The system addresses problems with 8 projects, 20 Lambda functions, 42 API keys, 12 API endpoints, and 19 environment variables where the agent would guess at function names, edit wrong files, and lose context.

The Fence System

Instead of asking Claude to update docs after implementation, the developer built a 740-line bash script that extracts structured data directly from source files and injects it into CLAUDE.md through fenced HTML comment blocks. Each CLAUDE.md has fences marking auto-generated sections:

## Serverless Functions <!-- auto:lambdas generated="2026-03-26" source="infrastructure/lib/api-stack.ts" -->
| Function | Route | Memory | Timeout |
|----------|-------|--------|---------|
| quote-save | /quotes/save | 256MB | 15s |
| quote-get | /quotes/get | 256MB | 15s |
...20 rows extracted from CDK config...
<!-- /auto:lambdas -->

## Architecture <-- hand-written, never touched by the script

How It Works

The script:

• Parses actual source files (CDK TypeScript, FastAPI Python, package.json, etc.)
• Extracts structured data (function names, routes, env vars, dependency versions)
• Replaces everything between the fences
• Updates the generated date to show freshness
• Validates: checks that every Lambda name has a matching handler file, every env var exists in .env

Hand-written sections (architecture descriptions, gotchas, business logic context) live outside fences and are never touched.

Auto-Generated Content

• Quoting tool (20 Lambdas): Lambda inventory, CDK stacks, env vars, test counts, deps from CDK TypeScript and package.json
• Sales dashboard (12 endpoints): API routes, theme list, deps from FastAPI decorators, TypeScript types, and requirements.txt
• Data parsing (42 Users): User data, deps from Python credential file and requirements.txt
• 5 other projects: Dependency versions from package.json/requirements.txt

Staleness Warning System

A doc-sync hook (fires after every code edit) checks the generated date on each fence. If any section is older than 7 days:

Warning: 3 auto-generated sections in agent-quoting-tool/CLAUDE.md are stale (oldest: 2026-03-19).
Run: ./scripts/generate-inventory.sh quoting

This is non-blocking — warns but never stops you from working. The staleness check rides alongside existing hooks with the same 10-minute throttle window, zero extra overhead.

Implementation Details

The setup uses pure bash with grep/sed/awk/jq, zero dependencies. Commands:

scripts/generate-inventory.sh all # Refresh everything
scripts/generate-inventory.sh quoting # Just one project

The script backs up each CLAUDE.md first (one backup per day, per project). The developer notes not to parse ASTs from bash — their TypeScript parser is a line-by-line grep/sed loop that works for controlled files but would be fragile for arbitrary TypeScript.

Key Insights

The fences allow auto-generated and hand-written content to coexist in the same file. Claude reads the whole CLAUDE.md at session start and gets both: accurate extracted data AND human context it can't infer from code. The developer recommends starting with highest-value extractions (Lambda inventories and env var tables that cause bugs when they drift) and notes that the staleness warning is more valuable than auto-running.

The entire system took about 3 hours to build (design, implementation, testing, first run).