document-haness/research/FOUNDATIONS.md

# ClariDoc 설계 근거: 독자가 이해하는 기술 문서의 논리 구조

> 조사 기준일: 2026-07-23  
> 적용 대상: 기술 블로그, 튜토리얼, 하우투, 설명, 참조, 트러블슈팅, 설계 문서

## 1. 이 연구가 답하려는 질문

이 하네스는 “문장을 유창하게 만드는 프롬프트”가 아니라 다음 질문에 답하도록 설계했다.

1. 독자는 왜 이 문서를 읽는가?
2. 그 목적에 맞는 문서 유형은 무엇인가?
3. 독자의 머릿속 질문은 어떤 순서로 생기는가?
4. 주장, 예시, 절차, 근거, 한계는 어디에 놓여야 하는가?
5. 모델이 논리적 구조를 빠뜨리거나 그럴듯한 사실을 발명했을 때 어떻게 탐지하는가?
6. 문서가 “좋아 보인다”는 인상 대신 재현 가능한 품질 기준으로 통과했는지 어떻게 남기는가?

결론은 다음과 같다.

> 이해하기 쉬운 기술 문서는 미문보다 **정보 구조**가 먼저다. 독자의 작업 또는 이해 목표를 고정하고, 문서 유형에 맞는 질문 순서를 정하며, 각 섹션을 하나의 질문과 하나의 기능에 대응시키고, 구체적인 예시·검증·근거·한계를 통해 이해를 누적해야 한다.

## 2. 조사 방법

자료를 네 층으로 나누어 검토했다.

### 2.1 편집·콘텐츠 설계 지침

Google, GitHub, Microsoft의 공식 기술 문서 작성 지침을 검토했다. 반복해서 나타난 원칙은 독자와 목적의 선행 정의, 핵심 결론의 조기 제시, 한 문단 한 생각, 의미 있는 제목, 논리적 우선순위, 점진적 상세화, 스캔 가능한 형식이다.

### 2.2 정보 유형과 문서 아키텍처

Diátaxis, OASIS DITA, Kubernetes의 콘텐츠 유형을 비교했다. 서로 용어는 다르지만, 학습·작업 수행·개념 이해·정확한 조회·문제 복구는 서로 다른 독자 상태와 구조를 요구한다는 점이 공통적이다.

### 2.3 학습과 이해에 관한 연구

완성된 해결 과정을 따라가는 worked example 연구와, 제목·요약·인과 연결어 같은 구조 신호가 이해와 전이를 돕는 signaling 연구를 참고했다. 이 결과를 기술 문서에 그대로 일반화한 것이 아니라, “예시는 시작 상태에서 결과까지 끊기지 않아야 한다”와 “구조와 인과관계를 표면에 드러내야 한다”는 설계 가설로 번역했다.

### 2.4 실제 엔지니어링 글 표본

Netflix, Cloudflare, Dropbox, AWS Builders’ Library의 글을 표본으로 읽었다. 좋은 글에서 반복적으로 관찰된 흐름은 대체로 다음과 같다.

```text
문제와 독자 약속
→ 실제 제약과 실패 양상
→ 선택 기준 또는 멘털 모델
→ 아키텍처·메커니즘
→ 구체적 사례나 데이터
→ 대안과 트레이드오프
→ 운영에서 드러난 한계·교훈
→ 적용 조건과 다음 행동
```

이 흐름은 보편 법칙이 아니라 표본 관찰에서 도출한 실무 패턴이다. 그래서 ClariDoc은 이를 `technical_blog`의 기본 구조로 사용하되, 브리프와 프로젝트별 스타일이 우선하도록 설계했다.

## 3. 핵심 원칙과 하네스 번역

### 원칙 1. 문서의 시작점은 주제가 아니라 독자의 변화다

“재시도에 대해 쓴다”는 주제만으로는 구조가 결정되지 않는다. 독자가 개념을 이해하려는지, 특정 작업을 끝내려는지, 장애를 복구하려는지에 따라 필요한 정보와 순서가 달라진다.

**하네스 적용**

- `Brief.audience.roles`: 누가 읽는가
- `Brief.audience.prior_knowledge`: 무엇을 이미 아는가
- `Brief.audience.needs`: 어떤 판단 또는 행동이 필요한가
- `Brief.reader_goal`: 읽은 뒤 가능한 관측 가능한 변화
- `Brief.core_message`: 문서 전체가 증명해야 할 한 문장

### 원칙 2. 초안을 쓰기 전에 문서 유형을 고정한다

튜토리얼과 하우투는 모두 단계가 있지만 목적이 다르다. 튜토리얼은 안내받는 학습 경험이고, 하우투는 이미 목표가 있는 사용자가 과업을 끝내는 문서다. 설명 문서와 참조 문서도 각각 이해와 조회라는 다른 작업을 지원한다.

**하네스 적용**

`DocumentType`을 다음 일곱 유형으로 제한한다.

- `technical_blog`
- `tutorial`
- `how_to`
- `explanation`
- `reference`
- `troubleshooting`
- `design_doc`

각 유형은 `STRUCTURE_SPECS`에 필수 섹션 intent와 순서를 가진다. planner가 제목과 근거 배치를 개선할 수는 있지만 필수 intent를 삭제하거나 재배열할 수 없다.

### 원칙 3. 범위, 비범위, 선행지식, 버전을 초기에 노출한다

독자가 문서의 적용 가능성을 판단하지 못하면 세부 내용을 읽은 뒤에야 “내 상황과 다르다”는 사실을 알게 된다. 비범위와 버전 맥락은 내용 부족의 변명이 아니라 문서의 정확성 경계다.

**하네스 적용**

- `scope`, `non_scope`, `prerequisites`
- `constraints.version_context`
- 오프닝에서 이 정보가 드러나는지 린트
- 목표와 직접 관련 없는 섹션을 planner가 추가하지 못하도록 구조 병합 검증

### 원칙 4. 핵심 답을 먼저 주고 상세는 점진적으로 공개한다

복잡한 기술 글이 배경부터 길게 시작하면 독자는 무엇을 위해 정보를 유지해야 하는지 모른다. 먼저 결론 또는 독자 약속을 제시하고, 그 뒤에 필요한 맥락·원리·세부 구현을 확장한다.

**하네스 적용**

- `technical_blog`, `explanation`, `design_doc`의 첫 intent를 결론 또는 결정 요청으로 고정
- drafting prompt에서 “answer before detail” 요구
- 오프닝에 `reader_goal`과 `core_message`의 의미가 나타나는지 휴리스틱 검사

### 원칙 5. 한 섹션은 하나의 독자 질문에 답한다

제목은 장식이 아니라 독자가 현재 어디에 있고 다음에 무엇을 알게 되는지 보여 주는 구조 신호다. 섹션마다 질문과 목적이 명시되면, 모델이 관련된 사실을 무작위로 나열하기 어렵다.

**하네스 적용**

모든 `OutlineSection`은 다음 필드를 가진다.

- `intent`: 섹션의 논리 기능
- `reader_question`: 이 섹션이 답할 질문
- `purpose`: 답이 전체 논증에서 수행하는 역할
- `must_include`: 반드시 다룰 정보
- `evidence_ids`: 연결할 근거
- `transition_to_next`: 다음 질문으로 넘어가는 이유

린터는 의미 없는 제목, 중복 제목, heading level 건너뛰기, 유형별 H2 순서 위반을 검사한다.

### 원칙 6. 개념 설명은 정의가 아니라 인과 모델을 만든다

용어를 각각 정의해도 구성요소 사이의 관계가 드러나지 않으면 독자는 새 상황에 적용하지 못한다. 좋은 설명은 입력, 상태, 결정, 변화, 결과, 관측을 연결한다.

**하네스 적용**

설명·기술 블로그·설계 문서의 구조에 다음 요소를 강제한다.

```text
익숙한 기준점
→ 핵심 용어와 경계
→ 구성요소
→ 데이터/제어 흐름
→ 불변조건과 실패 조건
→ 관측 가능한 결과
```

논리 reviewer는 전제 누락, 인과 점프, 순환 설명, 결론과 근거의 불일치를 찾도록 지시받는다.

### 원칙 7. 예시는 전체 경로를 따라가야 한다

조각난 코드 블록이나 단편적인 명령은 문법을 보여 줄 수 있지만, 입력이 어떤 판단과 상태 변화를 거쳐 결과가 되는지 보여 주지 못한다. 학습 목적의 예시는 시작 상태, 실행, 중간 체크포인트, 결과, 실패 경계가 이어져야 한다.

**하네스 적용**

- `worked_example` 또는 대응 intent를 유형 계약에 포함
- 예시 또는 코드 존재 검사
- 튜토리얼에는 중간 checkpoint와 최종 verification 요구
- 명령 블록은 언어 태그, 사전 조건, 예상 결과와 연결하도록 prompt에 명시

### 원칙 8. 절차는 행동뿐 아니라 안전 경계를 포함한다

작업 문서는 “무엇을 입력하라”만 알려 주면 부족하다. 시작 조건, 정상 결과, 중단 조건, 검증, 롤백을 함께 제공해야 실제 시스템에서 사용할 수 있다.

**하네스 적용**

절차형 문서에서 다음을 검사한다.

- 사전 조건
- 번호가 있는 단계
- 관측 가능한 검증
- 롤백 또는 복구
- 파괴적 명령 주변의 경고·백업·복구 경로

### 원칙 9. 참조 문서는 서술보다 조회 계약이 우선이다

참조 문서는 처음부터 끝까지 읽는 글이 아니라 정확한 값을 찾는 인터페이스다. 범위와 버전, 구문, 필드, 기본값, 동작, 오류, 최소 예시가 안정적으로 배치되어야 한다.

**하네스 적용**

`reference` 구조를 다음 순서로 고정한다.

```text
범위/버전 → 구문 → 파라미터/필드 → 동작 → 오류 → 최소 예시 → 관련 항목
```

테이블형 조회 표면이 없는 경우 경고하고, 버전 맥락과 미해결 placeholder를 검사한다.

### 원칙 10. 주장은 출처 단위와 연결되어야 한다

URL 목록만 주면 모델은 출처가 실제로 무엇을 지지하는지 추정하게 된다. 따라서 출처별로 사용할 수 있는 사실을 분리하고, 본문의 주장에 ID를 붙이는 편이 감사 가능하다.

**하네스 적용**

`SourcePack`의 각 항목은 `facts`와 `notes`를 가진다. 모델은 `[S1]` 같은 ID를 사용한다. 린터는 다음을 탐지한다.

- 존재하지 않는 출처 ID
- 인용이 필수인데 source pack이 비어 있음
- 출처가 있는데 아무 ID도 사용하지 않음
- 숫자·버전형 주장에 표식이 없음
- 사용되지 않은 출처

중요한 한계: 이 버전은 문장이 `facts`의 의미와 실제로 일치하는지 논리적으로 증명하지 않는다. evidence reviewer와 도메인 검토가 여전히 필요하다.

### 원칙 11. 선택은 대안, 기준, 비용, 실패 조건을 함께 설명한다

“우리는 X를 사용했다”만으로는 독자가 자신의 상황에서 같은 결정을 내려야 하는지 판단할 수 없다. 선택 기준과 제약, 버린 대안, 받아들인 비용, 운영에서 드러난 실패 조건이 있어야 판단이 전이된다.

**하네스 적용**

- 기술 블로그·설명·설계 문서에 alternatives/tradeoffs/limits intent 포함
- `design_doc`에는 목표/비목표, 제약, 대안, 결정, failure mode, rollout, observability, open risks 포함
- trade-off 또는 한계 신호가 없으면 lint error

### 원칙 12. 작성자와 검토자의 관점을 분리한다

하나의 모델이 작성과 자기검토를 모두 수행하면 같은 전제와 누락을 반복할 수 있다. 완전한 독립성을 보장하지는 못해도, 역할과 가능하면 제공자를 분리하면 오류 표면을 넓힐 수 있다.

**하네스 적용**

기본 멀티 에이전트 배치는 다음과 같다.

- planner: Codex
- writer: Claude
- logic reviewer: Codex
- reader reviewer: Claude
- evidence reviewer: Antigravity
- operations reviewer: Antigravity
- reviser: Claude

리뷰는 자유 서술이 아니라 점수, 차원별 점수, severity, 문제, 영향, 수정안이 있는 JSON 계약으로 받는다.

### 원칙 13. 유창성 평가와 결정적 검사를 결합한다

LLM은 문맥과 논리를 평가하는 데 유용하지만 동일 입력에서도 판단이 달라질 수 있다. 반대로 정규식과 구조 검사는 참·거짓을 이해하지 못하지만 재현 가능하다. 두 종류를 결합해야 한다.

**하네스 적용**

```text
composite = deterministic_lint × weight + model_review_mean × weight
```

점수 외에도 blocker와 error 개수 한도를 동시에 적용한다. 점수가 높아도 파괴적 명령 안전 경계나 금지 주장이 blocker이면 통과할 수 없다.

### 원칙 14. 결과뿐 아니라 과정도 감사 가능해야 한다

좋은 문서가 한 번 생성되었다는 사실보다 어떤 브리프, 근거, 구성, 모델 응답, 리뷰, 수정으로 만들어졌는지 재현 가능한지가 중요하다.

**하네스 적용**

- 정규화된 입력 저장
- planner/writer/reviewer/reviser 원문 응답 보존
- 라운드별 초안·lint·review·gate 저장
- provider 이벤트와 실행시간 기록
- 최종 산출물의 SHA-256 manifest 생성
- Mock 실행은 합성 평가임을 자동 경고

## 4. 문서 유형별 질문 사슬

### 4.1 기술 블로그

```text
무엇을 해결하는가?
→ 왜 어려운가?
→ 어떤 판단 모델이 필요한가?
→ 해결 방식은 어떻게 동작하는가?
→ 구체적 입력이 결과로 어떻게 변하는가?
→ 어떤 근거로 효과와 정확성을 판단하는가?
→ 무엇을 포기했고 언제 쓰지 말아야 하는가?
→ 독자는 다음에 무엇을 해야 하는가?
```

### 4.2 튜토리얼

```text
무엇을 완성하는가?
→ 무엇이 필요한가?
→ 전체 여정은 어떤 모습인가?
→ 어떤 순서로 따라가는가?
→ 각 단계가 맞는지 어떻게 확인하는가?
→ 최종 결과를 어떻게 검증하는가?
→ 무엇을 정리하고 다음에 무엇을 배우는가?
```

### 4.3 하우투

```text
이 작업은 언제 적용하는가?
→ 시작 조건은 무엇인가?
→ 최소 절차는 무엇인가?
→ 성공을 어떻게 확인하는가?
→ 실패하면 어떻게 되돌리는가?
→ 대표적인 문제는 어떻게 진단하는가?
```

### 4.4 설명

```text
핵심 질문과 답은 무엇인가?
→ 무엇에 빗대어 이해할 수 있는가?
→ 핵심 모델은 무엇인가?
→ 원인과 결과는 어떻게 이어지는가?
→ 구체적인 사례는 무엇인가?
→ 대안과 다른 관점은 무엇인가?
→ 모델의 한계는 무엇인가?
→ 실무 판단에는 어떤 의미가 있는가?
```

### 4.5 참조

```text
어떤 버전과 범위를 다루는가?
→ 정확한 구문은 무엇인가?
→ 필드와 기본값은 무엇인가?
→ 정상 동작과 부작용은 무엇인가?
→ 어떤 오류가 발생하는가?
→ 최소 예시는 무엇인가?
→ 관련 항목은 무엇인가?
```

### 4.6 트러블슈팅

```text
정확한 증상은 무엇인가?
→ 영향 범위는 어디까지인가?
→ 증거와 복구점을 어떻게 보존하는가?
→ 가장 싼 비파괴 진단은 무엇인가?
→ 관측 결과에 따라 원인이 어떻게 갈리는가?
→ 확인된 원인에 어떤 최소 조치를 하는가?
→ 복구를 어떻게 검증하는가?
→ 재발을 어떻게 막고 언제 에스컬레이션하는가?
```

### 4.7 설계 문서

```text
어떤 결정을 요청하는가?
→ 해결할 문제는 무엇인가?
→ 목표와 비목표는 무엇인가?
→ 요구와 제약은 무엇인가?
→ 가능한 대안은 무엇인가?
→ 무엇을 선택하며 왜인가?
→ 아키텍처와 상태 흐름은 무엇인가?
→ 실패·보안·운영 위험은 무엇인가?
→ 어떻게 점진 배포하고 되돌리는가?
→ 성공을 무엇으로 관측하는가?
→ 열린 위험과 가정은 무엇인가?
```

## 5. 모델별 역할을 나눈 이유

모델 이름 자체가 품질을 보장하지는 않는다. 이 하네스는 제공자별 “성격”을 전제로 하지 않고, 역할 계약과 출력 검증으로 책임을 분리한다.

- Codex 어댑터는 반복 가능한 CLI 파이프라인에 적합한 `codex exec` 표면을 사용한다.
- Claude 어댑터는 stdin으로 긴 작업을 넘길 수 있는 `claude -p` print mode를 사용한다.
- Antigravity 어댑터는 Python SDK의 `Agent`와 `LocalAgentConfig`를 사용한다.
- 실제 모델 ID는 구성에 명시할 수 있지만 기본 예제는 계정·조직별 가용성이 달라 빈 값으로 둔다.
- provider가 반환한 JSON은 내부 dataclass 계약으로 다시 파싱하며, 구조가 틀리면 폴백 또는 실패 정책을 적용한다.

## 6. 품질 평가가 의미하는 것

### PASS가 의미하는 것

- 문서 유형별 필수 구조가 존재한다.
- 설정한 lint와 독립 리뷰의 복합 기준을 만족한다.
- blocker/error 한도를 넘지 않았다.
- 실행 과정과 결과가 저장되었다.

### PASS가 의미하지 않는 것

- 모든 사실이 참이라는 보증
- 코드 예제가 실제 환경에서 동작한다는 보증
- 보안, 법률, 규제, 의료, 재무 적합성
- 독자 연구나 사용성 테스트를 대체한다는 의미
- Mock provider 점수가 실제 모델 또는 실제 문서 품질을 증명한다는 의미

## 7. 설계상 의도적인 한계

1. **웹 수집기는 포함하지 않았다.** URL을 자동 방문해 진실로 취급하는 대신, 작성자가 출처별 fact를 명시하게 했다.
2. **자연어 의미 검증은 완전하지 않다.** 인용 ID가 있어도 출처가 그 문장을 지지하는지는 reviewer와 사람이 확인해야 한다.
3. **휴리스틱은 언어별 오차가 있다.** 한국어와 영어의 길이·문장 분리·표현 차이를 완전히 모델링하지 않는다.
4. **다중 모델 합의는 진실의 증명이 아니다.** 서로 다른 모델이 같은 잘못된 전제를 공유할 수 있다.
5. **문서 유형은 시작점이다.** 큰 문서 세트는 여러 유형으로 분리하거나 명시적으로 조합해야 한다.
6. **실제 독자 검증이 최종 기준이다.** 검색 성공률, 과업 완료율, 오류율, 읽기 중 이탈, 지원 문의 감소 같은 운영 지표로 개선해야 한다.

## 8. 결론

ClariDoc의 핵심은 모델에게 “논리적으로 써 달라”고 부탁하는 것이 아니다. 논리의 구성요소를 계약으로 만들고, 독자 질문의 순서를 문서 유형별로 고정하며, 작성·검토·수정·감사의 경계를 코드로 분리하는 것이다.

이 구조는 문체를 획일화하기 위한 것이 아니라, 문체보다 먼저 충족되어야 할 이해 가능성의 최소 골격을 제공한다. 프로젝트별 용어, 브랜드 보이스, 실제 독자 데이터가 있으면 그 정보가 일반 규칙보다 우선한다.

전체 출처와 코드 대응표는 [`SOURCE_MATRIX.md`](SOURCE_MATRIX.md)를 참조한다.