제로 드리프트를 위한 펜스드 블록을 활용한 자체 유지 문서 시스템

r/ClaudeAI에서 한 개발자가 Claude Code와 같은 AI 코딩 에이전트가 세션 간에 컨텍스트를 잊어버리는 다중 프로젝트 작업 공간에서 정확한 문서를 유지하는 솔루션을 공유했습니다. 이 시스템은 에이전트가 함수 이름을 추측하고, 잘못된 파일을 편집하며, 컨텍스트를 잃는 문제가 있는 8개의 프로젝트, 20개의 Lambda 함수, 42개의 API 키, 12개의 API 엔드포인트, 19개의 환경 변수를 해결합니다.

펜스 시스템

구현 후 Claude에게 문서를 업데이트하라고 요청하는 대신, 개발자는 740줄의 bash 스크립트를 만들어 소스 파일에서 직접 구조화된 데이터를 추출하고 HTML 주석 블록을 통해 CLAUDE.md에 주입합니다. 각 CLAUDE.md에는 자동 생성 섹션을 표시하는 펜스가 있습니다:

## 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

작동 방식

스크립트는:

• 실제 소스 파일(CDK TypeScript, FastAPI Python, package.json 등)을 파싱합니다
• 구조화된 데이터(함수 이름, 경로, 환경 변수, 종속성 버전)를 추출합니다
• 펜스 사이의 모든 내용을 교체합니다
• 생성 날짜를 업데이트하여 최신 상태를 표시합니다
• 검증: 모든 Lambda 이름에 일치하는 핸들러 파일이 있는지, 모든 환경 변수가 .env에 존재하는지 확인합니다

수동 작성 섹션(아키텍처 설명, 주의사항, 비즈니스 로직 컨텍스트)은 펜스 외부에 있으며 절대 건드리지 않습니다.

자동 생성 콘텐츠

• 인용 도구(20개 Lambda): Lambda 인벤토리, CDK 스택, 환경 변수, 테스트 횟수, CDK TypeScript 및 package.json의 종속성
• 판매 대시보드(12개 엔드포인트): API 경로, 테마 목록, FastAPI 데코레이터, TypeScript 타입, requirements.txt의 종속성
• 데이터 파싱(42명 사용자): 사용자 데이터, Python 자격 증명 파일 및 requirements.txt의 종속성
• 기타 5개 프로젝트: package.json/requirements.txt의 종속성 버전

부실 경고 시스템

문서 동기화 훅(모든 코드 편집 후 실행)은 각 펜스의 생성 날짜를 확인합니다. 어떤 섹션이 7일보다 오래된 경우:

Warning: agent-quoting-tool/CLAUDE.md의 3개 자동 생성 섹션이 부실합니다(가장 오래된: 2026-03-19).
Run: ./scripts/generate-inventory.sh quoting

이는 비차단적입니다 — 경고하지만 작업을 멈추지 않습니다. 부실 확인은 기존 훅과 함께 동일한 10분 제한 창을 타고 실행되며 추가 오버헤드가 전혀 없습니다.

구현 세부사항

설정은 grep/sed/awk/jq를 사용한 순수 bash로, 종속성이 없습니다. 명령어:

scripts/generate-inventory.sh all # 모든 것 새로 고침
scripts/generate-inventory.sh quoting # 단일 프로젝트만

스크립트는 먼저 각 CLAUDE.md를 백업합니다(하루에 한 번, 프로젝트당). 개발자는 bash에서 AST를 파싱하지 말라고 언급합니다 — 그들의 TypeScript 파서는 제어된 파일에는 작동하지만 임의의 TypeScript에는 취약할 수 있는 줄별 grep/sed 루프입니다.

핵심 통찰

펜스를 통해 자동 생성 콘텐츠와 수동 작성 콘텐츠가 동일한 파일에 공존할 수 있습니다. Claude는 세션 시작 시 전체 CLAUDE.md를 읽고 둘 다 얻습니다: 정확한 추출 데이터와 코드에서 추론할 수 없는 인간의 컨텍스트. 개발자는 가장 가치가 높은 추출(Lambda 인벤토리와 환경 변수 테이블처럼 차이가 발생하면 버그를 일으키는 것)부터 시작할 것을 권장하며, 부실 경고가 자동 실행보다 더 가치 있다고 언급합니다.

전체 시스템은 약 3시간이 걸렸습니다(설계, 구현, 테스트, 첫 실행).