donghyeon.kang/document-haness
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

init: document-haness 하네스 설계

Browse Source
This commit is contained in:
DongHyeonka
2026-07-24 13:58:08 +09:00
parent d6f78f92a0
commit c39406bbdd
219 changed files with 7010 additions and 20052 deletions
Download Patch File Download Diff File Expand all files Collapse all files
research/FOUNDATIONS.md
+385
View File
@@ -0,0 +1,385 @@
# 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)를 참조한다.
research/SOURCE_MATRIX.md
+52
View File
@@ -0,0 +1,52 @@
# 조사 출처와 하네스 적용 매트릭스
> 조사·접근일: 2026-07-23
> 선택 기준: 공식 지침, 표준, 원 논문, 또는 실제 기술 조직이 발행한 엔지니어링 글
이 표는 출처 내용을 그대로 규칙으로 복제한 것이 아니라, 반복되는 원칙을 ClariDoc의 계약·구조·검사로 번역한 기록이다.
| ID | 출처 | 유형 | 핵심 관찰 | ClariDoc 적용 | 주의점 |
|---|---|---|---|---|---|
| R01 | [Google developer documentation style guide](https://developers.google.com/style) | 공식 편집 지침 | 기술 독자에게 명확하고 일관되게 쓰되 프로젝트별 스타일을 우선하고, 규칙보다 실제 독자 명확성을 우선한다. | 브리프의 `tone`, 프로젝트 규칙 우선 원칙, 일관성 중심 lint | 스타일 지침은 정보 구조 전체를 대신하지 않는다. |
| R02 | [Google Technical Writing: Documents](https://developers.google.com/tech-writing/one/documents) | 공식 교육 자료 | 범위와 비범위, 대상 독자와 사전지식, 시작부 핵심 요약, 익숙한 것과의 연결, 독자 요구에 따른 조직을 권한다. | `scope`, `non_scope`, `audience`, `prior_knowledge`, `core_message`, `mental_model` | 입문 교육 자료이므로 고위험 운영 문서의 모든 요구를 다루지는 않는다. |
| R03 | [Google Technical Writing One summary](https://developers.google.com/tech-writing/one/summary) | 공식 교육 자료 | 문단 첫 문장에 중심점을 두고 한 문단은 한 주제에 집중하며, 문서 시작에서 범위·독자·핵심점을 제시한다. | 장문 문단/문장 lint, 오프닝 계약, one-question-per-section | 언어별 문장 길이 기준은 휴리스틱으로 조정해야 한다. |
| R04 | [Google Technical Writing: Organizing large documents](https://developers.google.com/tech-writing/two/large-docs) | 공식 교육 자료 | outline과 계층형 heading, 관련 주제의 묶음, 점진적 공개가 긴 문서 탐색과 이해를 돕는다. | outline 선행, heading 계층 검사, progressive disclosure prompt | 짧은 글에는 과도한 계층이 오히려 방해가 될 수 있다. |
| R05 | [GitHub Docs best practices](https://docs.github.com/en/contributing/writing-for-github-docs/best-practices-for-github-docs) | 공식 콘텐츠 설계 지침 | 독자·목적·콘텐츠 유형을 먼저 정하고, 중요도와 사용 순서로 조직하며, 한 문장/문단 한 생각, 결론 우선, 점진적 상세화, 의미 있는 소제목을 사용한다. | `Brief`, `DocumentType`, 구조 계약, 제목·문단 lint, answer-first prompt | GitHub 제품 문맥의 예시는 일반화할 때 조정이 필요하다. |
| R06 | [GitHub Docs content design principles](https://docs.github.com/en/contributing/writing-for-github-docs/content-design-principles) | 공식 콘텐츠 원칙 | 사용자 목표, 고가치 시나리오, “필요한 만큼만”, 명확성·의미·정확성·일관성을 우선한다. | `reader_goal`, scope/non-scope, 불필요 섹션 억제, quality gate | “충분한 문서량”은 조직과 위험도에 따라 달라진다. |
| R07 | [Diátaxis](https://diataxis.fr/) | 문서 아키텍처 프레임워크 | 튜토리얼, 하우투, 참조, 설명은 서로 다른 사용자 요구와 작성 방식을 가진다. | 네 기본 유형을 중심으로 `DocumentType` 설계 | 기술 블로그·트러블슈팅·설계 문서는 별도 실무 패턴을 추가했다. |
| R08 | [OASIS DITA technical content elements](https://docs.oasis-open.org/dita/dita/v1.3/errata02/os/complete/part2-tech-content/langRef/containers/technical-content-elements.html) | 표준 | Concept, Task, Reference, Troubleshooting을 분리한다. Task는 context, prerequisites, steps, expected result, example, next steps 구조를 가진다. | 절차형 구조와 트러블슈팅 유형, prerequisites/verification/next steps | DITA XML 요소를 구현한 것이 아니라 정보 유형만 참고했다. |
| R09 | [Kubernetes page content types](https://kubernetes.io/docs/contribute/style/page-content-types/) | 대규모 오픈소스 공식 지침 | Concept, Task, Tutorial, Reference별로 overview, prerequisites, steps, objectives, cleanup, examples 등의 권장 섹션이 다르다. | tutorial/how-to/reference 섹션 계약, cleanup/rollback, next steps | Kubernetes 사이트 템플릿 자체는 ClariDoc에 복제하지 않았다. |
| R10 | [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) | 공식 편집 지침 | 기술 내용을 단순하고 직접적이며 명확한 언어로 전달한다. | 전문적이고 직접적인 기본 tone, 간결성 lint/review | 브랜드 보이스는 프로젝트별로 달라질 수 있다. |
| R11 | [Microsoft: Writing for all abilities](https://learn.microsoft.com/en-us/style-guide/accessibility/writing-all-abilities) | 공식 접근성 지침 | heading level로 계층을 전달하고, 목록·표·제목으로 관계를 강화하며, 위치만 가리키는 표현을 피한다. | heading-level 검사, scan surface, 의미 있는 제목 | 접근성 전체 표준을 구현한 것은 아니다. |
| R12 | [Sweller & Cooper, 1985, worked examples](https://doi.org/10.1207/s1532690xci0201_3) | 원 연구 | 초보 학습에서 완성된 해결 과정을 연구 대상으로 삼아 worked example의 학습 효과를 보였다. | 시작 상태부터 결과까지 이어지는 `worked_example`, checkpoint | 대수 학습 결과를 모든 기술 문서에 직접 일반화하지 않는다. 설계 가설로 사용한다. |
| R13 | [Mautone & Mayer, 2001, signaling](https://doi.org/10.1037/0022-0663.93.2.377) | 원 연구 | 요약, section heading, 인과 연결어 등 구조 신호가 설명의 조직을 드러내고 전이 수행에 영향을 주었다. | reader question, meaningful heading, transition, causal chain | 멀티미디어 학습 실험이며 실제 개발자 문서와 독자군이 다르다. |
| R14 | [Netflix: In-House LLM Serving at Netflix](https://netflixtechblog.com/in-house-llm-serving-at-netflix-a5a8e799ea2c) | 실제 엔지니어링 글 | 글의 초점과 대안을 먼저 밝히고, 아키텍처 개요 뒤에 의존 순서의 설계 결정, 운영에서 드러난 문제를 설명한다. | 기술 블로그의 promise → architecture → decisions → operational evidence → lessons 흐름 | 단일 최신 표본이며 Netflix 전체 글의 대표라고 볼 수 없다. |
| R15 | [Cloudflare: Building Jetflow](https://blog.cloudflare.com/building-jetflow-a-framework-for-flexible-performant-data-pipelines-at-cloudflare/) | 실제 엔지니어링 글 | 문제와 프레임워크 구조, 구체적 데이터베이스 사례, 성능·편의성의 트레이드오프와 교훈을 연결한다. | mechanism, worked example, evidence, tradeoffs | 제품·워크로드 특화 선택을 일반 처방으로 사용하지 않는다. |
| R16 | [Dropbox: Feature store powering real-time AI](https://dropbox.tech/machine-learning/feature-store-powering-realtime-ai-in-dropbox-dash) | 실제 엔지니어링 글 | 왜 기존 해법이 맞지 않았는지, 목표·요구사항, 설계, 속도·규모·신선도, 트레이드오프와 교훈을 예고한다. | context/constraints → goals → mechanism → evidence → lessons | 회사 블로그는 논문식 검증이 아니라 실무 설명이다. |
| R17 | [AWS Builders’ Library: Making retries safe with idempotent APIs](https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/) | 실제 설계 설명 | 단순화된 가정을 먼저 드러내고, timeout으로 상태가 불명확해지는 구체적 시나리오를 통해 부작용과 설계 원리를 설명한다. | 가정·실패 조건·worked scenario·reconciliation을 기술 블로그 구조에 반영 | 특정 AWS 설계 경험이며 모든 API에 동일하게 적용되지 않는다. |
| R18 | [AWS Builders’ Library: Timeouts, retries, and backoff with jitter](https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/) | 실제 운영 설명 | 재시도·timeout의 위험, 멱등성, backoff/jitter, 부하 증폭과 같은 운영 메커니즘을 실패 관점에서 연결한다. | 예제 source pack, mechanism/failure/tradeoff/verification 구조 | 시점과 서비스 맥락을 본문에 명시해야 한다. |
## 반복 패턴과 구현 위치
| 반복 패턴 | 구현 위치 |
|---|---|
| 독자와 과업을 먼저 정의 | `src/claridoc/models.py`의 `Audience`, `Brief` |
| 유형별로 정보 요구를 분리 | `DocumentType`, `src/claridoc/structures.py` |
| 범위·비범위·버전·선행조건 | `Brief`, `Constraints`, opening lint |
| 결론 우선과 점진적 상세화 | `STRUCTURE_SPECS`, `src/claridoc/prompts.py` |
| 섹션별 질문·목적·전환 | `OutlineSection` |
| 예시와 체크포인트 | `worked_example`, `checkpoint`, type-specific lint |
| 절차의 검증·복구 | `verification`, `rollback`, `SAFE001` |
| 출처 단위 추적 | `SourcePack`, `EVD001`–`EVD006` |
| 대안·트레이드오프·한계 | 유형 계약, `TYPE006` |
| 작성자와 검토자 역할 분리 | `PipelineConfig.reviewers`, provider adapters |
| 결정적 검사 + 모델 판단 | `lint_document`, composite quality gate |
| 재현과 감사 | raw responses, events, rounds, `manifest.json` |
## 해석 원칙
- 여러 출처에 반복되는 원칙은 기본값으로 채택했다.
- 특정 조직에만 해당하는 스타일은 계약이 아니라 예시로 남겼다.
- 인지 연구 결과는 직접적인 제품 품질 보증이 아니라 구조 설계의 근거로 제한했다.
- 실제 엔지니어링 글의 패턴은 관찰적 추론이며, 글의 목적에 따라 순서를 변경할 수 있다.
- 프로젝트별 스타일, 독자 조사, 실제 오류 데이터가 있으면 이 일반 매트릭스보다 우선한다.