chore: 문서를 작성할 때 한국어의 표현 작성 스킬 추가 및 1인칭 관점의 글 작성 검증 테스트 추가

This commit is contained in:
DongHyeonka
2026-07-29 16:48:03 +09:00
parent c39406bbdd
commit 41501b5d06
520 changed files with 95494 additions and 2231 deletions
+84 -44
View File
@@ -1,52 +1,92 @@
# 조사 출처와 하네스 적용 매트릭스
# 조사 출처와 ClariDoc 적용 매트릭스
> 조사·접근일: 2026-07-23
> 선택 기준: 공식 지침, 표준, 원 논문, 또는 실제 기술 조직이 발행한 엔지니어링 글
이 문서는 조사 자료를 하네스 규칙으로 번역한 기록이다. 특정 조직의 글 몇 편을 공식 편집 규정으로 일반화하지 않는다. 공개 기술 글에서 반복 관찰한 패턴은 `corpus-derived profile`로 표시하고, 공식 문서·표준과 구분한다.
이 표는 출처 내용을 그대로 규칙으로 복제한 것이 아니라, 반복되는 원칙을 ClariDoc의 계약·구조·검사로 번역한 기록이다.
## 1. 프로젝트 내부 근거 구조
| ID | 출처 | 유형 | 핵심 관찰 | ClariDoc 적용 | 주의점 |
| ID | 자료 | 분류 | 관찰 | 하네스 적용 | 경계 |
|---|---|---|---|---|---|
| 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 구조 | 시점과 서비스 맥락을 본문에 명시해야 한다. |
| P01 | `llm-wiki-private/README.md` | repository operating contract | raw 자료를 canonical로 승급한 뒤 외부 산출물을 만들고, 근거 없는 결정은 표시해야 한다 | local corpus source hierarchy, canonical 우선, status 보존 | raw를 공개 글의 현재 사실로 바로 사용하지 않 |
| P02 | `raw/branch-notes/feature-application-port-usecase-contract.md` | project decision record | Spring DI 허용 이유, 수용 비용, 금지 경계, TransactionPort와 검증 rule이 함께 기록됨 | decision-rationale retrieval fixture, golden example | SLF4J 선택 이유는 이 자료가 뒷받침하지 않음 |
| P03 | `wiki/projects/ca-tmpl/clean-architecture-package-layout.md` | canonical project state | module 경계, Gradle/ArchUnit 이중 검사, reflection 우회 한계, local verification 범위를 기록 | 현재 상태·검증·한계 근거 | branch-note의 과거 명칭보다 canonical 상태를 우선 |
| P04 | `raw/branch-notes/feature-log-management-contract.md` | project decision record | logging 정책은 있으나 application-core의 SLF4J 사용 이유는 명시하지 않음 | unsupported rationale를 추론하지 않는 negative fixture | 단어가 등장하는 것과 선택 이유가 있는 것은 다름 |
## 반복 패턴과 구현 위치
## 2. 우아한형제들 기술 블로그 표본
| 반복 패턴 | 구현 위치 |
|---|---|
| 독자와 과업을 먼저 정의 | `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` |
| ID | 출처 | 분류 | 반복 관찰 | ClariDoc 적용 | 일반화 경계 |
|---|---|---|---|---|---|
| W01 | [B마트 OMS의 물류주문관리를 통한 출고 최적화](https://techblog.woowahan.com/22263/) | engineering case study | 고객·라이더·현장 작업자의 목표와 물리적 제약을 구체적인 주문 장면으로 제시하고, 문제/기획/기술/성과 순서로 전개 | `problem_scene`, stakeholder cost, mechanism, evidence verification | 단일 글의 section 명칭을 모든 글에 강제하지 않음 |
| W02 | [Polars로 데이터 처리를 더 빠르고 가볍게 with 실무 적용기](https://techblog.woowahan.com/18632/) | engineering case study | 팀의 데이터 처리 맥락과 예상 독자를 먼저 밝히고, 도구 선택의 조건을 구체화 | audience/prior knowledge, problem context, option criteria | 성능 수치와 도구 결론은 해당 사례에만 적용 |
| W03 | [LLMOps로 확장하는 AI플랫폼 2.0](https://techblog.woowahan.com/22839/) | platform case study | 운영 문제를 구체적인 실패로 분해하고 후보 솔루션의 장단점을 비교한 뒤 선택 이유를 설명 | `options`, `decision_rationale`, accepted cost, problem→solution mapping | 후보 평가를 보편적인 제품 순위로 사용하지 않음 |
| W04 | [배달의민족 안드로이드 7.27.0 장애 회고](https://techblog.woowahan.com/2524/) | incident retrospective | 변경 맥락, 장애 증상, 해결 과정, 놓친 조건, 이후 개선을 시간 흐름으로 공개 | troubleshooting/retrospective chronology, failure condition, prevention | 오래된 사례의 구체 기술 결론은 현재 Android에 일반화하지 않음 |
| W05 | [누구나 할 수 있는 10배 더 빠른 배치 만들기](https://techblog.woowahan.com/13569/) | performance case study | 평소에는 문제가 없던 배치가 배포와 충돌하면서 리스크가 된 장면, 병목 확인, 최적화, 운영 부작용, 완화까지 연결 | state-change opening, contrast transition, measurement→decision→remaining cost | 제목의 배수와 측정 결과는 해당 환경에만 적용 |
| W06 | [셀프서비스, 챗봇에게 물어보세요](https://techblog.woowahan.com/16021/) | product engineering case study | 사용자 불편에서 기능 목적을 도출하고 질문형 heading으로 설계 판단을 전환하며, 선택 이유는 기준 목록과 대안 비교로 설명 | concrete actor/cost, immediate question-answer, criteria-before-choice | 친근한 종결어미와 독자 호명은 모든 글에 의무화하지 않음 |
| W07 | [우아한형제들 디자인 시스템에 시각적 회귀 테스트 적용하기](https://techblog.woowahan.com/17081/) | frontend testing case study | 수동 확인 비용을 구체화한 뒤 도구와 테스트베드를 같은 기준으로 비교하고 제외 이유를 짧게 명시 | problem consequence, criteria list, concise rejection reason, question→answer | 도구 선정 결과는 당시 디자인 시스템 조건에 한정 |
| W08 | [회원시스템 이벤트기반 아키텍처 구축하기](https://techblog.woowahan.com/7835/) | architecture case study | 트래픽 증가와 시스템 분리의 인과를 짧은 문단으로 전개하고, 질문형 heading 뒤 동기 HTTP·별도 스레드·메시징 대안을 차례로 검토 | short causal paragraphs, project voice, alternative mechanism comparison | 이벤트 아키텍처를 모든 시스템의 기본값으로 일반화하지 않음 |
## 해석 원칙
### 문장 형식 관찰
- 여러 출처에 반복되는 원칙은 기본값으로 채택했다.
- 특정 조직에만 해당하는 스타일은 계약이 아니라 예시로 남겼다.
- 인지 연구 결과는 직접적인 제품 품질 보증이 아니라 구조 설계의 근거로 제한했다.
- 실제 엔지니어링 글의 패턴은 관찰적 추론이며, 글의 목적에 따라 순서를 변경할 수 있다.
- 프로젝트별 스타일, 독자 조사, 실제 오류 데이터가 있으면 이 일반 매트릭스보다 우선한다.
8편의 도입, 문제 전환, 선택 이유, 구현 전환, 검증·결론 문단을 수동으로 비교했다. 이는 전체 게시물에 대한 빈도 분석이 아니라 제한된 목적 표본이다.
| ID | 관찰 | 근거 범위 | 하네스 적용 | 일반화 경계 |
|---|---|---|---|---|
| WS01 | 구체적인 팀·사용자·시스템 상태를 먼저 두고, 달라진 조건이 만든 비용으로 문제를 전환 | W01~W08 | writer opening/paragraph guidance, editor review | 모든 글이 같은 도입 길이나 어조를 쓰지는 않음 |
| WS02 | `하지만`, `문제는`, `다만`, `그 결과`, `그래서`, `이에`는 앞 문맥의 실제 역접·인과를 가리킬 때 사용 | W01~W08 | relation-bearing transition guidance | 특정 접속어의 사용 횟수를 품질 지표로 삼지 않음 |
| WS03 | 질문형 heading이나 짧은 질문 뒤에 바로 사례·설명·선택으로 답함 | W01, W02, W05, W06, W07, W08 | editor immediate-answer check | 모든 heading을 질문형으로 만들지 않음 |
| WS04 | 선택은 기준 목록, 후보의 제외 이유, 현재 조건을 거쳐 직접 서술 | W02, W03, W06, W07, W08 | decision sentence guidance | 각 글이 동일한 비교표 형식을 쓰지는 않음 |
| WS05 | 순서 표현은 실제 방법·단계·레이어·도표의 구분에 사용 | W03, W05, W06, W07 | ordinal-use boundary | 순서어 자체를 금지하지 않음 |
| WS06 | `첫 번째 제약은/두 번째 제약은/세 번째 제약은`처럼 추상 분류명을 연속 문단의 머리에 두는 형식은 표본에서 확인되지 않음 | W01~W08 | `STYLE001`, writer/editor/reviser guidance, golden regression | 0/8은 전체 우아한형제들 블로그에서 절대 사용되지 않는다는 뜻이 아님 |
| WS07 | `팀에서는`, `저희는`, `우리는`으로 선택 주체를 밝히되 판단 근거는 구체적인 상태와 비용에 둠 | W01, W02, W03, W05, W06, W07, W08 | project-local voice guidance | 1인칭 사용을 강제하지 않음 |
**적용 상태:** 위 8편에서 도출한 정보 전개와 문장 형식은 `WOOWAHAN_TECH_BLOG_KO`라는 corpus-derived profile이다. 우아한형제들의 공식 house style이라고 표기하지 않는다.
## 3. 우아한테크코스·학습형 개발 글
| ID | 출처 | 분류 | 관찰 | ClariDoc 적용 | 경계 |
|---|---|---|---|---|---|
| T01 | [woowacourse GitHub organization](https://github.com/woowacourse) | public learning corpus | 교육 자료, 미션, 학습 기록이 공개 repository로 축적됨 | 학습형 문서의 재현 가능한 입력과 단계, source corpus 후보 | 공개 repository 존재가 특정 글쓰기 방법론의 공식 증명은 아님 |
| T02 | [Tecoble](https://tecoble.techcourse.co.kr/) | learner-authored technical articles | 팀 프로젝트에서 겪은 문제, 처음 시도, 단계적 해결, 코드 예시를 중심으로 쓴 글이 반복됨 | tutorial/explanation의 problem-first opening, worked example, failed attempt | 개별 글의 품질과 사실성은 별도로 검토해야 함 |
## 4. 일반 기술 문서와 정보 구조
| ID | 출처 | 분류 | 핵심 원칙 | ClariDoc 적용 | 경계 |
|---|---|---|---|---|---|
| G01 | [Google developer documentation style guide](https://developers.google.com/style) | official editorial guidance | 명확성, 일관성, 프로젝트 스타일 우선 | tone/style profile, consistency review | 정보 아키텍처 전체를 대신하지 않음 |
| G02 | [Google Technical Writing: Documents](https://developers.google.com/tech-writing/one/documents) | official training | 독자, 범위, 핵심 메시지, 논리적 조직 | `Brief`, opening contract, reader goal | 고위험 운영 절차의 안전 요구는 별도 보강 |
| G03 | [Google Technical Writing: Organizing large documents](https://developers.google.com/tech-writing/two/large-docs) | official training | outline, heading hierarchy, progressive disclosure | deterministic outline, heading lint | 짧은 글에는 계층을 과도하게 늘리지 않음 |
| G04 | [GitHub Docs best practices](https://docs.github.com/en/contributing/writing-for-github-docs/best-practices-for-github-docs) | official content design | audience/purpose/type 선행, 결론 우선, 의미 있는 heading | one-question-per-section, answer-before-detail | GitHub product-specific 예시는 일반화 시 조정 |
| G05 | [GitHub Docs content design principles](https://docs.github.com/en/contributing/writing-for-github-docs/content-design-principles) | official content design | 사용자 목표, 필요한 만큼의 정보, 정확성·일관성 | reader goal, scope/non-scope, quality dimensions | 필요한 문서량은 위험도에 따라 다름 |
| G06 | [Diátaxis](https://diataxis.fr/) | documentation framework | tutorial, how-to, explanation, reference는 서로 다른 과업 | 네 기본 document type | technical blog, troubleshooting, design doc은 별도 확장 |
| G07 | [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) | standard | concept, task, reference, troubleshooting 분리 | task prerequisites/steps/result, troubleshooting flow | DITA XML 구현이 아니라 정보 유형만 참고 |
| G08 | [Kubernetes page content types](https://kubernetes.io/docs/contribute/style/page-content-types/) | official OSS guidance | concept/task/tutorial/reference의 목적과 page structure 구분 | document type-specific structure | Kubernetes의 기여 규칙을 그대로 복제하지 않음 |
## 5. 학습과 인지 구조
| ID | 출처 | 분류 | 핵심 관찰 | ClariDoc 적용 | 경계 |
|---|---|---|---|---|---|
| C01 | worked-example 연구 | learning science | 초보자는 완성된 해결 경로와 중간 상태를 볼 때 문제 해결 schema를 형성하기 쉽다 | end-to-end worked example, checkpoint, result | 모든 숙련자용 reference에 서사를 강제하지 않음 |
| C02 | signaling 연구 | multimedia/learning science | heading, 요약, 인과 신호가 구조 파악을 돕는다 | reader question, transition, causal connector review | 기술 문서 효과에 대한 직접 실험으로 과장하지 않음 |
## 6. 규칙으로 번역된 핵심 결정
| 하네스 규칙 | 근거 조합 | 구현 위치 |
|---|---|---|
| 독자용 글과 내부 근거 추적 분리 | P01 + G02/G04 + 사용자 피드백 | `prompts.py`, `provenance.py`, `lint.py` |
| source hierarchy와 status 보존 | P01~P04 | `corpus.py`, `models.py` |
| decision unit 강제 | P02/P03 + W02/W03 | `structures.py`, `prompts.py`, `lint.py` |
| problem-scene first 기술 블로그 | W01~W08 + T02 | `structures.py`, `WOOWAHAN_TECH_BLOG_KO` profile |
| 정보 구조를 문장 틀로 노출하지 않음 | WS01~WS07 + 사용자 피드백 | writer/editor/reviser prompt, `STYLE001`, golden regression |
| source ID/path/access date 누출 차단 | 사용자 피드백 + P01 | `META001`, `EVD007`, `META004`, `DATE001/2` |
| 이유가 없는 SLF4J 주장 제거 | P04 negative evidence boundary | golden example, review prompt |
| local vs production verification 분리 | P03 + engineering case-study discipline | evidence/operations reviewer |
| Mock score를 품질 증거로 금지 | test validity boundary | pipeline warning, report, README |
## 7. 미해결 연구 과제
- lexical retrieval이 동의어와 간접 표현을 놓치는 경우를 줄이는 방법
- canonical과 branch-note가 충돌할 때 자동으로 authority를 판정하는 규칙
- 한국어 decision-rationale lint의 precision/recall 측정 corpus
- 실제 Codex/Claude/Antigravity 조합별 writer/reviewer 편향 비교
- 독자 테스트를 통한 `WOOWAHAN_TECH_BLOG_KO` profile의 이해도 검증
현재 프로필은 조사 표본과 프로젝트 요구를 바탕으로 한 설계 가설이다. 이를 공식 스타일이나 보편 법칙으로 주장하지 않는다.