document-haness/research/SOURCE_MATRIX.md

# 조사 출처와 하네스 적용 매트릭스

> 조사·접근일: 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` |

## 해석 원칙

- 여러 출처에 반복되는 원칙은 기본값으로 채택했다.
- 특정 조직에만 해당하는 스타일은 계약이 아니라 예시로 남겼다.
- 인지 연구 결과는 직접적인 제품 품질 보증이 아니라 구조 설계의 근거로 제한했다.
- 실제 엔지니어링 글의 패턴은 관찰적 추론이며, 글의 목적에 따라 순서를 변경할 수 있다.
- 프로젝트별 스타일, 독자 조사, 실제 오류 데이터가 있으면 이 일반 매트릭스보다 우선한다.