13 KiB
13 KiB
조사 출처와 ClariDoc 적용 매트릭스
이 문서는 조사 자료를 하네스 규칙으로 번역한 기록이다. 특정 조직의 글 몇 편을 공식 편집 규정으로 일반화하지 않는다. 공개 기술 글에서 반복 관찰한 패턴은 corpus-derived profile로 표시하고, 공식 문서·표준과 구분한다.
1. 프로젝트 내부 근거 구조
| ID | 자료 | 분류 | 관찰 | 하네스 적용 | 경계 |
|---|---|---|---|---|---|
| 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. 우아한형제들 기술 블로그 표본
| ID | 출처 | 분류 | 반복 관찰 | ClariDoc 적용 | 일반화 경계 |
|---|---|---|---|---|---|
| W01 | B마트 OMS의 물류주문관리를 통한 출고 최적화 | engineering case study | 고객·라이더·현장 작업자의 목표와 물리적 제약을 구체적인 주문 장면으로 제시하고, 문제/기획/기술/성과 순서로 전개 | problem_scene, stakeholder cost, mechanism, evidence verification |
단일 글의 section 명칭을 모든 글에 강제하지 않음 |
| W02 | Polars로 데이터 처리를 더 빠르고 가볍게 with 실무 적용기 | engineering case study | 팀의 데이터 처리 맥락과 예상 독자를 먼저 밝히고, 도구 선택의 조건을 구체화 | audience/prior knowledge, problem context, option criteria | 성능 수치와 도구 결론은 해당 사례에만 적용 |
| W03 | LLMOps로 확장하는 AI플랫폼 2.0 | platform case study | 운영 문제를 구체적인 실패로 분해하고 후보 솔루션의 장단점을 비교한 뒤 선택 이유를 설명 | options, decision_rationale, accepted cost, problem→solution mapping |
후보 평가를 보편적인 제품 순위로 사용하지 않음 |
| W04 | 배달의민족 안드로이드 7.27.0 장애 회고 | incident retrospective | 변경 맥락, 장애 증상, 해결 과정, 놓친 조건, 이후 개선을 시간 흐름으로 공개 | troubleshooting/retrospective chronology, failure condition, prevention | 오래된 사례의 구체 기술 결론은 현재 Android에 일반화하지 않음 |
| W05 | 누구나 할 수 있는 10배 더 빠른 배치 만들기 | performance case study | 평소에는 문제가 없던 배치가 배포와 충돌하면서 리스크가 된 장면, 병목 확인, 최적화, 운영 부작용, 완화까지 연결 | state-change opening, contrast transition, measurement→decision→remaining cost | 제목의 배수와 측정 결과는 해당 환경에만 적용 |
| W06 | 셀프서비스, 챗봇에게 물어보세요 | product engineering case study | 사용자 불편에서 기능 목적을 도출하고 질문형 heading으로 설계 판단을 전환하며, 선택 이유는 기준 목록과 대안 비교로 설명 | concrete actor/cost, immediate question-answer, criteria-before-choice | 친근한 종결어미와 독자 호명은 모든 글에 의무화하지 않음 |
| W07 | 우아한형제들 디자인 시스템에 시각적 회귀 테스트 적용하기 | frontend testing case study | 수동 확인 비용을 구체화한 뒤 도구와 테스트베드를 같은 기준으로 비교하고 제외 이유를 짧게 명시 | problem consequence, criteria list, concise rejection reason, question→answer | 도구 선정 결과는 당시 디자인 시스템 조건에 한정 |
| W08 | 회원시스템 이벤트기반 아키텍처 구축하기 | 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 | public learning corpus | 교육 자료, 미션, 학습 기록이 공개 repository로 축적됨 | 학습형 문서의 재현 가능한 입력과 단계, source corpus 후보 | 공개 repository 존재가 특정 글쓰기 방법론의 공식 증명은 아님 |
| T02 | Tecoble | learner-authored technical articles | 팀 프로젝트에서 겪은 문제, 처음 시도, 단계적 해결, 코드 예시를 중심으로 쓴 글이 반복됨 | tutorial/explanation의 problem-first opening, worked example, failed attempt | 개별 글의 품질과 사실성은 별도로 검토해야 함 |
4. 일반 기술 문서와 정보 구조
| ID | 출처 | 분류 | 핵심 원칙 | ClariDoc 적용 | 경계 |
|---|---|---|---|---|---|
| G01 | Google developer documentation style guide | official editorial guidance | 명확성, 일관성, 프로젝트 스타일 우선 | tone/style profile, consistency review | 정보 아키텍처 전체를 대신하지 않음 |
| G02 | Google Technical Writing: Documents | official training | 독자, 범위, 핵심 메시지, 논리적 조직 | Brief, opening contract, reader goal |
고위험 운영 절차의 안전 요구는 별도 보강 |
| G03 | Google Technical Writing: Organizing large documents | official training | outline, heading hierarchy, progressive disclosure | deterministic outline, heading lint | 짧은 글에는 계층을 과도하게 늘리지 않음 |
| G04 | GitHub Docs best practices | official content design | audience/purpose/type 선행, 결론 우선, 의미 있는 heading | one-question-per-section, answer-before-detail | GitHub product-specific 예시는 일반화 시 조정 |
| G05 | GitHub Docs content design principles | official content design | 사용자 목표, 필요한 만큼의 정보, 정확성·일관성 | reader goal, scope/non-scope, quality dimensions | 필요한 문서량은 위험도에 따라 다름 |
| G06 | Diátaxis | documentation framework | tutorial, how-to, explanation, reference는 서로 다른 과업 | 네 기본 document type | technical blog, troubleshooting, design doc은 별도 확장 |
| G07 | OASIS DITA technical content elements | standard | concept, task, reference, troubleshooting 분리 | task prerequisites/steps/result, troubleshooting flow | DITA XML 구현이 아니라 정보 유형만 참고 |
| G08 | Kubernetes 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_KOprofile의 이해도 검증
현재 프로필은 조사 표본과 프로젝트 요구를 바탕으로 한 설계 가설이다. 이를 공식 스타일이나 보편 법칙으로 주장하지 않는다.