AI가 문서를 불필요하게 만든다는 주장은 두 가지 서로 다른 활동, 즉 산문을 생성하는 것과 운영 지식 (operational knowledge)을 보존하는 것을 혼동하고 있습니다.

에이전트는 산문을 저렴하게 생성할 수 있습니다. 하지만 누락된 배포 조건, 잊혀진 수정 사항 클릭 동작 (modifier-click behavior), 또는 아무도 기록하지 않은 테스트를 복구할 수는 없습니다. 증거가 부재할 때, 유창한 텍스트는 오히려 그 간극을 더 보기 어렵게 만들 수 있습니다.

Ben Halpern의 현재 DEV 토론은 이를 "포스트 문서화 시대 (post-documentation era)"라는 신화로 규정합니다. 저는 제품 결정을 측정 가능하게 만들고 싶습니다: 작업 항목 (work item)이 에이전트가 행동하고 인간이 이를 검토하기에 충분한 문서화된 증거를 포함하고 있는가?

다섯 가지 커버리지 차원 (Five coverage dimensions)

100점 만점의 스코어카드를 사용하세요:

각 차원은 문서화됨 (documented) (가중치의 100%), 부분적 (partial) (50%), 또는 누락됨 (missing) (0%)으로 분류됩니다. 이것은 보편적인 품질 점수가 아닙니다. 이는 선언된 작업 단위에 대한 **커버리지 경보 (coverage alarm)**입니다.

하나의 제한된 MonkeyCode 사례에 적용하기

저는 MonkeyCode 이슈 #824, 풀 리퀘스트 (pull request) #859, 그리고 커밋 c58bcd4의 관련 공개 코드에만 스코어카드를 적용했습니다. 이것은 프로젝트 전체나 프로젝트의 문서 전체에 대한 점수가 아닙니다.

해당 이슈는 앱 홈 페이지를 반환하는 /workspace/... Markdown 링크를 식별합니다. PR은 작업 파일 미리보기를 열어야 하는 일반적인 클릭과, 파일 관리자 딥 링크 (deep link)를 유지해야 하는 새 탭 및 링크 복사 동작을 구분합니다. 또한 린트 (lint), 온라인 빌드, 그리고 수동 Markdown 링크 체크 결과도 보고합니다.

저의 증거 파일은 해당 좁은 사례에 대해 다음과 같이 평가합니다:

{
  "name": "reproduction",
  "weight": 20,
...

결과는 80/100이며, reproduction과 limitations는 부분적(partial)으로 표시되었습니다. 이 수치는 수정 사항이 좋거나 나쁘다고 선언하지 않습니다. 대신 제품 팀에게 어떤 질문이나 테스트 기록을 추가해야 에이전트의 추측(guesswork)을 줄일 수 있는지 알려줍니다.

스코어카드를 감사 가능하게 만들기 (Make scoring auditable)

함께 제공되는 의존성 없는 (zero-dependency) 스크립트는 가중치(weights)의 합계가 100인지, 상태(statuses)가 정의된 척도를 사용하는지, 모든 차원(dimension)이 증거를 인용하고 있는지, 그리고 수정 사항이 고정(pinned)되었는지를 검증합니다.

node score-docs.mjs doc-coverage.json
node test-score.mjs

예상 출력:

coverage=80/100 gaps=reproduction,limitations
PASS score=80; rejected invalid weights and missing evidence

테스트는 의도적으로 가중치를 깨뜨리고 증거를 제거합니다. 스프레드시트도 동일한 수치를 계산할 수 있지만, 검증(validation)을 통해 잘 꾸며진 대시보드가 잘못된 루브릭(rubric)을 숨기는 것을 방지합니다.

스코어를 워크플로 게이트(workflow gate)로 사용하기

작업의 성격에 따라 서로 다른 임계값(thresholds)이 필요합니다:

• 탐색 (exploration): 낮은 커버리지를 허용하되, 에이전트에게 간극(gaps)을 표시합니다.
• 일상적인 구현 (routine implementation): 문제, 예상 동작, 그리고 검증(verification)을 요구합니다.
• 보안 또는 되돌릴 수 없는 변경 (security or irreversible changes): 모든 차원과 인간의 승인을 요구합니다.
• 장애 대응 (incident response): 필요한 경우 완화 조치(mitigation)를 먼저 배포한 다음, 누락된 증거를 담당자가 있는 명시적인 기술 부채(explicit debt)로 만듭니다.

유용한 제품 동작은 "90점 미만은 모두 차단한다"가 아닙니다. 에이전트가 할 수 있는 일을 변경하는 것입니다. 낮은 커버리지는 자동 병합(automatic merge)은 금지하면서도, 조사와 테스트 생성을 허용할 수 있습니다.

스코어카드가 도움이 되는지 측정하기

이를 교리(doctrine)가 아닌 제품 실험(product experiment)으로 실행하세요. 다음 사항을 추적합니다:

1. 구현 전 명확화 단계 (clarification rounds);
2. 검토자(reviewer)가 발견한 범위 불일치 (scope mismatches);
3. 누락된 부차적 동작으로 인해 재오픈된 이슈 (reopened issues);
4. 문서화에 소비된 시간 대비 재작업(rework)에서 절약된 시간;
5. 채점자 간의 불일치 (disagreement between scorers).

만약 팀들이 상태 라벨(status labels)을 조작한다면, 보정 세션(calibration sessions)에서 증거 URL과 샘플 채점 패킷을 요구하세요. 만약 스코어가 재작업이나 검토 품질을 예측하지 못한다면, 차원(dimensions)을 변경하십시오.

더 넓은 관점에서의 핵심은 간단합니다. 생성된 문서(generated documentation)는 지식을 형식화(formatting)하는 비용을 낮출 수는 있지만, 누락된 관찰(missing observations)을 만들어내지는 못합니다. 커버리지 스코어카드(coverage scorecard)는 에이전트(agent), 검토자(reviewer), 그리고 어느 정도의 자율성(autonomy)을 부여할지 결정하는 제품 관리자(product manager)에게 이러한 차이를 명확히 인지시켜 줍니다.

공개 사항: 저는 MonkeyCode 프로젝트에 기여하고 있습니다. 위의 점수는 연결된 이슈(issue), PR, 그리고 고정된 코드(pinned code)에 대한 제한적인 분석이며, 프로젝트 전체의 문서화 등급이 아닙니다. 채점 스크립트와 피스처(fixtures)는 로컬 환경에서 테스트되었습니다.