증거 기반 문서화
주장(claim)은 그것을 확인할 수단을 가지고 있을 때만 문서(documentation)입니다. 이 스킬은 표준이자 지도(map)입니다: 10개의 표준(canons)과 각각이 정의되고 시행되며 시드(seed)되는 위치입니다.
이는 내비게이터(navigator) 이지, 두 번째 사본이 아닙니다. 아래의 모든 법칙은 정확히 하나의 고유한 장소를 가집니다 — 이것이 표준 3이며, 교리를 다시 서술하는 내비게이터는 자신이 인덱싱하는 규칙을 어기게 됩니다.
각 표준의 전체 진술문, 그 근거 및 시행은 documentation.md → The canons에 있습니다.
10가지 표준
- 주장은 자신의 주소(address)를 가진다 —
file:line, 명령어와 그 출력, 테스트 이름; 교훈(lesson)은 자신의 커밋을 명명한다. - 숫자는 계산되며, 다시 서술되지 않는다.
- 모든 사실은 정확히 하나의 고유한 장소를 가진다 — 다른 곳에서는 링크만 하고 다시 서술하지 않는다.
- 참조(reference)는 문서가 읽히는 위치에서 해결된다 — 문서가 있는 위치에서 해결되는 것이 아니다.
- 아무도 보지 않았는데 초록색이었다가 빨간색으로 변한 것은 증거가 아니다.
- 검사(check)는 자신의 범위와 그 이상을 증명한다.
- 침묵은 통과(pass)가 아니다 — 어떤 메커니즘이 보지 않았을 때 무엇을 출력하는지 물어보라.
- 추정(estimate)은 절대 측정(measurement)으로 발표되지 않는다 — 규칙은 자신의 증거 조건을 명시한다.
- 확인되지 않은 것은 확인된 것 옆에 출력된다.
- 문서는 자신을 사실로 만든 변경과 함께 출하(shipped)된다 — 수정은 추가되며, 덮어쓰여지지 않는다.
이것들은 인식론적(epistemic) 입니다: 무엇이 주장을 문서로 만드는지에 관한 것입니다. 주어진 트리거, 검사 및 종료 기준에 대해 무엇을 해야 하는지에 대한 운영 계층은 learned.md에 있습니다. 두 가지가 같은 것을 말하는 것처럼 보일 때, 표준은 *이유(why)*이고 규칙은 *방법(how)*입니다.
다음 단계
| 당신이 하려는 것… | 읽을 문서 | 이유 |
|---|---|---|
| 프로젝트의 문서를 처음부터 설정하기 | documentation.md → The inventory | 첫 작업 전에 답해야 할 네 가지 질문 |
| 결정을 기록하여 작성자가 사라져도 유지되게 하기 | Registers and ids + templates/decisions.md | 추가 전용(append-only) id, 에지 마커(edge markers), 하나의 결정 고유 장소 |
| 무언가를 변경하고 문서를 고아로 만들지 않기 | The Doc Loop + The propagation matrix | 변경이 요구하는 문서들, 메타 행(meta-row)부터 시작 |
| 사실이 속할 위치 결정하기 | Single source of truth | 두 개의 고유 장소는 그중 하나가 업데이트된 날 서로 불일치함 |
| 거짓말할 수 없는 검사 구축하기 | gates.md | 세 가지 축, 시행 사다리(enforcement ladder), 점진적 무장(progressive arming), 프로빙(probing) |
| 성공을 보고하는 메커니즘 신뢰하기 | gates.md → False success | 확인할 이유를 제거하는 실패 |
| 에이전트 자체 도구에 검사 연결하기 | hooks.md | 훅 계약(hook contract), 그리고 충돌한 가드(guard)가 액션을 허용하는 이유 |
| 프로젝트가 이미 가지고 있는 문서 감사하기 | setup.md | 일곱 번의 패스, 가장 저렴한 것부터, 출력은 수정 계획 |
| 교훈을 다음 실행으로 전달하기 | retrospective.md | 먼저 스탬프(찬 트리거가 읽음), 그런 다음 최대 10개로 가지치기; 모든 교훈은 자신의 커밋을 명명함 |
| 게이트를 호스트 프로젝트에 시드하기 | templates/docgate.sh | 초록색으로 시드: 아직 입력이 없으면 휴면 상태 |
| 에이전트가 행동한다고 주장하기 | tdd.md → When the thing under test is an agent — 링크 대신 이름으로 참조 (이 내비게이터의 디렉터리 외부 링크는 패키저가 이 스킬만 단독으로 제공할 때 깨지므로) | 주소는 추적 id와 실행된 어설션(assertion) (표준 1); 아무도 보지 않았는데 불일치하는 판사는 아무도 보지 않았는데 초록색이 빨간색으로 변한 것 (표준 5) |
| 전체 변경을 승인까지 가져가기 | task-pipeline | 이 스킬은 표준입니다; 저 스킬은 변경이 저장소에 도달하는 방법입니다 |
적용 시점
경계는 "그것이 사실로 읽힐 것이다"입니다. 결정 기록, README, 승인 보고서, 런북(runbook), 사용자를 위한 변경 로그, 감사 결과, 무언가가 확인되었다는 주장.
이 스킬을 통과하지 않는 것: 초안, 생각을 말로 표현하는 것, 채팅에서의 답변, 커밋 메시지, 코드 주석. "그것을 확인해보겠습니다"에 file:line을 요구하는 것은 에이전트가 규칙이 실제로 무언가를 보호하는 곳에서 우회하도록 가르치는 가장 빠른 방법입니다.
거절 표현 — "без доков" / "on my word". 원래 이곳을 통과해야 할 작업에서 직접 수행하고, 추정을 측정으로 제시하지 않고(표준 8) 주장이 뒷받침되지 않는다는 것을 명시적으로 말하십시오.
하나의 테스트
문서가 출하되기 전에, 누군가 "어떻게 알았습니까?"라고 물었을 때 당황하게 만드는 문장을 읽어보고, 그 문장에 주소를 부여하거나 삭제하십시오. 위의 모든 것은 그 질문을 기계적으로 만든 것입니다.