coalledger

CoalLedger는 AI 코딩 에이전트를 대상으로 하는 문서 품질 도구로, 저자는 이를 "문서를 위한 CoalMine"이라고 설명합니다. 이 도구는 zero-dependency 훅, 단일 소스 설정 스키마, 동의 기반 지출, 자동 수정 금지라는 원칙을 공유하는 소규모 애드온 제품군인 TheColliery(CoalMine, CoalTipple, CoalBoard, CoalHearth, CoalFace, CoalWash)의 일부입니다. CoalLedger는 단독으로 설치하거나 다른 도구들과 함께 사용할 수 있습니다. 이 도구의 전제는 코드는 린터, 테스트, CI가 있지만, 문서는 대부분 '희망'에 의존한다는 점입니다. 코드와 동떨어진 README, 일치하지 않는 번역, 끊어진 설치 링크, 오래된 버전 배지 등은 독자가 여전히 신뢰하지만 실제로는 실패한 상태인 '침묵의 오류'입니다. CoalLedger는 README, 사양서, 보고서, 번역본 등 모든 문서를 스캔하여 렌더링된 내용이 주장하는 바와 일치하는지 비교합니다. 각각 하나의 실패 모드를 담당하는 7가지 카나리 기능은 다음과 같습니다: 1. doc-grounding — 소스(코드, 데이터, 원문, 실제 상황)와 일치하지 않는 주장을 포착합니다. 여러 소스를 통해 실시간으로 검증하며, 오프라인 상태에서는 "미검증"으로 표시됩니다. 2. doc-standard — 해당 문서 유형의 표준 대비 미비한 점(필수 섹션 누락, 문서화되지 않은 공개 인터페이스 등)을 포착합니다. 3. doc-rot — 오래된 버전, 날짜, 배지, 해결되지 않은 TODO, 대체된 지침 등을 포착합니다. 4. doc-consistency — 문서 간의 모순, 용어의 변화, 언어 간의 불일치를 포착합니다. 5. doc-structure — 깨진 링크, 앵커, 헤더, 표, 참조 및 이미지 대체 텍스트를 포착합니다. 6. doc-quality — 불필요한 내용, 불분명한 문장, 오타, 문법 및 철자 오류와 같은 언어적 결함을 포착합니다. 7. doc-leak (설정 기반) — 공개 문서 내의 텍스트 수준 민감 정보를 플래그합니다. 토큰 형태의 비밀값은 다른 도구에 맡기며, 의심되는 결과만 보고합니다. 스캔은 두 단계로 실행됩니다. 'Quick' 단계는 결정론적이고 비용이 거의 들지 않는 기계적 레이어를 다루며 보고만 수행합니다. 'Full' 단계는 모델의 판단을 사용하는 시맨틱 레이어를 추가하며, 유료이며 항상 별도의 동의가 필요합니다. 7가지 카나리 중 4개는 기계적 레이어와 시맨틱 레이어를 결합하며, doc-consistency와 doc-leak은 시맨틱 전용입니다. 번들로 제공되는 zero-dependency CommonMark+GFM AST 엔진이 구조 검사를 수행하여 올바르게 렌더링되는 콘텐츠가 잘못 표시되지 않도록 합니다. 저자는 이 엔진의 충실도가 픽셀 단위의 GitHub 렌더링이 아닌 사양 수준(spec-level)임을 명시하며, 호스트별 특이사항은 추측하지 않고 제한 사항으로 보고합니다. 심각도는 기계적으로 판단하지 않고 항상 문맥에 따라 판단합니다. 예를 들어, 아카이브의 깨진 링크는 '낮음'이지만, 설치 단계의 깨진 링크는 '치명적'으로 분류됩니다. 확정된 결과는 의심되는 결과와 분리되어 보고됩니다. 수정 사항은 절대 자동으로 적용되지 않으며, 모든 보고서는 안전한 수정, 사용자 선택 수정, 또는 보고만 하기 중 하나를 선택하는 메뉴로 끝납니다. 기계적 레이어는 설계상 언어에 구애받지 않으며(영어 키워드가 아닌 구조, 위치, 의미를 기준으로 작동), 시맨틱 레이어는 해당 문서의 언어로 작동합니다. 별도의 선택 사항으로 '문서 메모리 드리프트(memory-drift) 알림' 기능이 있습니다. 이 기능은 스캔이나 보고를 수행하지 않습니다. 문서 파일(.md, .mdx, .markdown, .rst, .txt, .adoc, .asciidoc, .org)이 수정되었으나 세션 내에서 MEMORY.md가 업데이트되지 않았고 프로젝트가 MEMORY.md 컨벤션을 사용하는 경우, 에이전트가 응답을 마칠 때 조용한 시스템 메시지를 한 번 출력하며, MEMORY.md가 업데이트되면 다시 침묵합니다. 이 기능은 비활성화할 수 있으며, 코드 수정을 위한 CoalMine의 알림 기능을 보완합니다. 두 도구는 서로 겹치지 않는 파일 확장자를 감시합니다. 호환성은 플랫폼 표가 아닌 기능 기반으로 결정됩니다. 라이프사이클 훅이 있는 플랫폼은 적절한 시점에 적절한 카나리를 제공하는 세션 시작 컨덕터를 갖게 되며, 훅이 없는 플랫폼은 에이전트 주도의 최선 노력(best-effort) 호출 방식을 사용합니다. 모든 경우에 카나리는 이름으로 수동 호출할 수 있습니다. 저자는 지원 단계를 솔직하게 표시합니다. Claude Code는 라이브 플러그인과 도그푸딩을 통해 검증된 것으로 설명되며, 그 외 플랫폼(Antigravity, Cursor, Codex, Gemini CLI, Cline, Copilot, claude.ai)은 "works with"(개발되었으나 엔드-투-엔드 검증 전)로 표시됩니다. Antigravity 설정의 경우 업데이트 후 hooks.json 위치가 변경되었으므로 Antigravity 공식 문서를 통해 다시 확인해야 한다는 주의 사항이 있습니다. 잘못된 경로의 설정은 작동하지 않지만 무해합니다. Claude Code 설치는 마켓플레이스 추가와 플러그인 설치라는 두 가지 명령어로 이루어지며, 컨덕터와 메모리 드리프트 알림도 함께 설정됩니다. 다른 에이전트들은 독립형 스킬 폴더를 복사하여 사용합니다(AST 엔진은 doc-structure 폴더 내에 포함됨). claude.ai 사용자의 경우, 프런트매터 설명이 플랫폼의 목록 제한을 초과하므로 스킬을 직접 압축하지 말고, 설명이 다듬어지고 SHA256 체크섬이 포함된 카나리별 ZIP 파일을 Releases 페이지에서 다운로드할 것을 권장합니다. 명령어로는 각 카나리별 명령어와 /coalledger:stats(세션 로컬 스캔 및 결과 통계), /coalledger:update(버전 확인 및 업데이트 처리)가 있습니다. 설정은 글로벌 파일과 여러 알려진 에이전트 디렉토리에서 확인되는 프로젝트별 파일을 지원하며, 레거시 루트 경로도 여전히 읽어옵니다. 설정 키로는 온/오프 모드, 보고 언어, 비활성화할 카나리, 심각도 하한선, 전체 스캔 오버라이드, Quick/Full 기본 단계, doc-leak 게이트, 공개 문서 플래그, 메모리 드리프트 알림, 선택적 em-dash 타이포그래피 규칙, 업데이트 확인 동작 등이 포함됩니다. 프로젝트 전체를 꺼서 해당 프로젝트에서 스킬이 로드되지 않게 할 수도 있습니다. 권한은 엄격하게 제한됩니다. 지정된 문서와 해당 문서의 링크가 가리키는 파일만 읽고, 자체 스크래치 파일과 업데이트 스탬프만 씁니다. 로컬에서는 최대 세 가지(읽기 전용 AST 엔진, 수정 전 git stash 체크포인트, 그리고 동의 하에 문서가 작동한다고 주장하는 예제 실행)만 실행하며, 문서를 스스로 수정하지 않습니다. 네트워크 사용은 선택 사항입니다. 유료 Full 단계의 소스 검증과 자체 업데이트 확인은 각각 별도의 동의가 필요하며, 훅과 엔진은 절대 온라인으로 연결되지 않습니다. API 키나 npm install은 필요하지 않습니다. 벤치마킹에 대해 이 프로젝트는 정직합니다. 가공의 숫자 대신 벤치마킹되지 않은 상태로 출시되었습니다. 기계적 레이어는 저장소 내의 픽스처(심어진 결함은 발견하고, 깨끗한 미끼는 침묵하는 방식)를 통해 검증 스크립트로 확인되며, 향후 버전별 실행을 통해 카나리별 재현율(recall)을 측정한 결과 요약본을 제공할 계획입니다. Apache 2.0 라이선스로 제공됩니다.