Bra1nZ/evidence-first-docs

증거 우선 문서 (Evidence-First Docs)

문서는 시스템에 대한 이야기가 아닙니다. 이는 주장 원장(claim ledger)입니다: 각각의 중요한 주장은 메커니즘과 증거까지 추적 가능해야 하며, 그 한계는 주장과 같은 위치에 명시되어야 합니다.

자신감 있는 문장은 싸구려입니다. 독자가 무엇이 입증되었는지, 무엇이 테스트되었는지, 무엇이 검토만 되었는지, 무엇이 아직 미해결인지 알 수 있도록 하는 것이 작업입니다.

핵심 규칙

모든 중요한 주장은 네 가지를 수반합니다:

1. 메커니즘 — 주장이 참이 되도록 시스템에서 가정하는 것.
2. 증거 — 증명 아티팩트: 증명, 모델, 테스트, 분석 보고서, 추적, 벤치마크 또는 검토 기록.
3. 범위 — 주장이 적용되는 곳과 신뢰 경계 밖에 있는 것.
4. 상태 — 증거가 지원하는 가장 강력한 정직한 레이블.

네 가지 중 하나라도 빠지면 주장은 준비되지 않은 것입니다. 설계 의도, 계획 또는 미해결 질문으로 다시 작성하십시오. 결과로 포장하지 마십시오.

주장 원장

문서 내 또는 연결된 증거 파일에 테이블을 유지하십시오:

ID	주장	메커니즘	증거	범위 / TCB	상태	한계	최종 확인일
C-01	역할 X만이 테이블 T에 쓸 수 있음	권한 검사 + DB 정책	부정 테스트 T-04..T-11	PostgreSQL 14–17; 역할 Y, 역할 없는 세션	테스트됨	수퍼유저와 DBA는 위협 모델 외부	2026-11-02

규칙:

• 문서당 한 행이 아닌, 주장당 한 행.
• 주장은 반증 가능해야 합니다. "시스템은 안전하다"는 주장이 아닙니다. "역할 Y가 지원되는 모든 진입점을 통해 T에 쓸 수 없다"는 주장입니다.
• 도구 이름만이 아니라 아티팩트를 링크하십시오. "SARIF"는 형식입니다. 보고서 경로와 검토된 규칙 집합이 증거입니다.
• 아티팩트가 재실행될 때 최종 확인일을 업데이트하십시오. 오래된 증거는 형식적 문제가 아니라 결함입니다.
• 부정 결과를 유지하십시오. "X 때문에 깨뜨리려 했지만 실패했습니다"는 증거입니다. 숨기면 잘못된 안정감을 줍니다.

상태 계층

증거가 지원하는 가장 강력한 레이블을 사용하고, 그보다 강한 레이블은 절대 사용하지 마십시오:

상태	의미
proven	명시된 속성에 대한 기계 검증 증명, 가정 및 TCB 선언됨
model-checked	모델의 완전 또는 경계 탐색; 경계 및 모델-코드 간극 명시
tested	위반을 시도하는 실행된 테스트, 환경 및 결과 기록됨
static-refinement	정적 분석 또는 정제 검사; 도구, 규칙 및 미해결 발견 사항 명시
reviewed	인간 검토만; 실행 가능 또는 형식 증거 없음
open	주장은 존재하지만 증거는 없음; 결과가 아닌 위험

낮은 상태는 실패가 아닙니다. 부풀려진 상태는 실패입니다.

verified, proven, correct, secure, safe, complete, guaranteed, certified, 또는 compliant라는 단어를 인접한 상태와 범위 없이 작성하지 마십시오. 그 단어가 증거 없이도 살아남을 수 있다면 단어를 삭제하십시오.

증거 강도

올바른 이유로 실패할 수 있는 증거를 선호하십시오:

1. 명시적 가정 하에 명시된 속성에 대한 형식 증명.
2. 명시된 경계 내 완전 모델 검사.
3. 기록된 코퍼스 및 오라클을 사용한 속성 기반 또는 퍼즈 테스팅.
4. 메커니즘이 제거될 때 실패하는 대상 부정 테스트.
5. 검토된 규칙 집합 및 분류된 발견 사항이 있는 정적 분석.
6. 명명된 검토자 및 체크리스트가 있는 코드 검토.
7. 단정 또는 일화.

계층 구조는 절대적이지 않습니다: 잘못 적용된 증명보다 대상 테스트가 더 강력할 수 있습니다. 증거를 주장에 맞추십시오. 코드를 정제하지 않는 모델의 증명은 코드를 증명하지 않습니다. 플랫폼이 먼저 거부했기 때문에 통과하는 테스트는 가드를 증명하지 않습니다.

범위 및 신뢰 경계

경계를 문서 말미의 부록이 아닌 주장 옆에 명시하십시오:

• 적용되는 버전 및 플랫폼.
• 제외된 특권 사용자: 수퍼유저, DBA, 배포 관리자, 비밀 관리자, 빌드 시스템, 운영자.
• 가정: 암호화 프리미티브, 시계, 네트워크, 스토리지, 테넌트 격리, 구성.
• 기호적으로 모델링된 것과 실제로 실행된 것.
• 범위 밖의 것과 그 이유.

한정되지 않은 주장은 거의 항상 거짓인 모든 것에 대한 주장입니다. "PostgreSQL 14–17에서 문서화된 구성으로 역할 Y에 대해 안전함; DBA는 모델 외부"는 정직하고 유용합니다.

워크플로우

1. 주장을 목록화하십시오. 텍스트를 읽고 속성, 결과, 보장 또는 규정 준수 상태를 주장하는 모든 문장에 표시하십시오.
2. 각 주장을 분류하십시오. 설계 의도, 요구 사항, 구현 사실, 테스트 결과, 형식 결과 또는 릴리스 주장입니까?
3. ID와 상태를 할당하십시오. 메커니즘, 증거, 범위, 한계 및 최종 확인일을 추가하십시오.
4. 아티팩트에 대해 주장을 테스트하십시오. 보고서를 열고, 명령을 재실행하고, 누락된 아티팩트를 요청하십시오. 파일 이름을 증거로 받아들이지 마십시오.
5. 지원되지 않는 주장을 다시 작성하십시오. "설계 의도", "계획됨", "아직 확인되지 않음" 또는 미해결 질문으로 변환하십시오. 야망은 유지하고 잘못된 확신은 제거하십시오.
6. 부정을 확인하십시오. 모든 보안 또는 정확성 주장에 대해 위반을 시도한 테스트 또는 분석의 이름을 지정하십시오. 없으면 주장을 open으로 표시하십시오.
7. 언어를 검토하십시오. 금지된 단어, 모호한 수량자 및 한정되지 않은 절대어를 제거하십시오. references/banned-words.md를 참조하십시오.
8. 증거를 고정하십시오. 명령, 커밋, 환경, 날짜 및 아티팩트 경로를 기록하여 검토자가 결과를 재현할 수 있도록 하십시오.
9. 릴리스를 게이트하십시오. 릴리스 노트는 원장이 지원하는 것만 주장할 수 있습니다. 잔여 위험과 미해결 주장을 명시적으로 나열하십시오.

검토 체크리스트

• 모든 중요한 주장에는 ID, 메커니즘, 증거, 범위, 상태 및 한계가 있습니다.
• 모든 tested 주장은 메커니즘이 제거될 때 실패할 수 있는 테스트의 이름을 지정합니다.
• 모든 model-checked 주장은 경계와 모델-코드 간극을 명시합니다.
• 모든 proven 주장은 가정과 TCB를 명시합니다.
• 부정 결과와 알려진 실패는 포함되어 있고 걸러지지 않았습니다.
• 날짜와 버전은 최신입니다. 오래된 증거는 오래된 것으로 표시됩니다.
• 특권 사용자와 범위 밖 경로의 이름이 지정됩니다.
• 인접한 증거와 범위 없이 금지된 단어가 나타나지 않습니다.
• README, 아키텍처 문서, API 계약 및 릴리스 노트가 서로 모순되지 않습니다.
• 독자는 문서만으로 증거를 재현할 수 있습니다.

안티패턴

1. 야망적인 현재 시제. "시스템이 시행합니다..." 실제로는 계획일 때.
2. 파일 이름으로 증거 대체. 결과, 범위 또는 날짜 없이 "report.pdf 참조".
3. 도구 이름을 증거로 사용. 규칙, 발견 사항 및 분류 없이 "정적 분석으로 검증됨".
4. 범위 세탁. 좁은 테스트 결과를 제품 전체 보장으로 제시.
5. 초록 스위트 절대주의. 어떤 테스트인지, 어떤 플랫폼에서, 무엇을 위반하려 했는지 말하지 않고 "모든 테스트 통과".
6. 규정 준수 코스프레. 표준 이름을 인증서로 사용; 매핑은 감사가 아님.
7. 매장된 한계. 주의 사항이 존재하지만 주장과 멀리 떨어져 있음.
8. 오래된 확신. 오래된 커밋의 결과를 현재로 제시.
9. 부정 증거 없음. 성공만 문서화되고 실패와 거부는 사라짐.

출력 형태

기술 문서를 작성하거나 검토하라는 요청을 받으면 다음을 생성하십시오:

1. 상태별 개수가 포함된 간단한 주장 요약.
2. 주장 원장 (인라인 또는 링크).
3. 결과와 명시적으로 분리된 미해결 주장 및 잔여 위험.
4. 제약하는 주장 옆에 있는 범위 및 가정.
5. 경로, 명령, 날짜 및 버전이 포함된 증거 인덱스.

원장 및 릴리스 노트 형태에는 references/evidence-template.md를 사용하십시오. 게시하기 전에 references/banned-words.md를 사용하십시오. 저장소에 표준 매핑이 포함된 경우 references/standards-map.md에 있습니다. 이 스킬 자체는 표준에 의존하지 않습니다.

출력을 문서 규모에 맞추십시오. 짧은 릴리스 노트는 전체 감사 패키지가 아닌 간결한 주장 테이블과 짧은 잔여 위험 섹션이 필요합니다. 인증 증거 파일은 전체 원장, 증거 인덱스 및 범위가 필요합니다. 철저함과 길이를 혼동하지 마십시오. 모든 행은 독자가 필요한 정보를 담고 있어야 합니다.