chore: 문서를 작성할 때 한국어의 표현 작성 스킬 추가 및 1인칭 관점의 글 작성 검증 테스트 추가
This commit is contained in:
DongHyeonka
+273
-332
@@ -1,385 +1,326 @@
|
||||
# ClariDoc 설계 근거: 독자가 이해하는 기술 문서의 논리 구조
|
||||
# ClariDoc 설계 근거: 근거를 숨기지 않되, 글쓰기 과정을 독자에게 노출하지 않는 방법
|
||||
|
||||
> 조사 기준일: 2026-07-23
|
||||
> 적용 대상: 기술 블로그, 튜토리얼, 하우투, 설명, 참조, 트러블슈팅, 설계 문서
|
||||
ClariDoc은 문장을 매끄럽게 생성하는 프롬프트 모음이 아니다. 기술 블로그와 기술 문서를 만들 때 다음 세 문제를 동시에 다루는 하네스다.
|
||||
|
||||
## 1. 이 연구가 답하려는 질문
|
||||
1. 독자가 문제, 선택, 구현, 검증을 끊기지 않고 따라갈 수 있어야 한다.
|
||||
2. 프로젝트의 선택 이유와 경계를 실제 근거 문서에서 회수해야 한다.
|
||||
3. 출처 ID, 저장소 경로, 접근일, 작성 지시문 같은 내부 정보는 독자용 글에 섞이지 않아야 한다.
|
||||
|
||||
이 하네스는 “문장을 유창하게 만드는 프롬프트”가 아니라 다음 질문에 답하도록 설계했다.
|
||||
## 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의 글을 표본으로 읽었다. 좋은 글에서 반복적으로 관찰된 흐름은 대체로 다음과 같다.
|
||||
초기 버전은 근거 추적 가능성을 높이기 위해 본문에 source ID를 직접 쓰도록 했다. 그 결과 다음과 같은 문장이 최종 문서에 나타날 수 있었다.
|
||||
|
||||
```text
|
||||
문제와 독자 약속
|
||||
→ 실제 제약과 실패 양상
|
||||
→ 선택 기준 또는 멘털 모델
|
||||
→ 아키텍처·메커니즘
|
||||
→ 구체적 사례나 데이터
|
||||
→ 대안과 트레이드오프
|
||||
→ 운영에서 드러난 한계·교훈
|
||||
→ 적용 조건과 다음 행동
|
||||
Retries can increase load on a dependency that is already failing. [S1]
|
||||
제공된 근거 팩은 다음 사실을 확인 대상으로 제시한다.
|
||||
예시는 특정 날짜 기준이다.
|
||||
```
|
||||
|
||||
이 흐름은 보편 법칙이 아니라 표본 관찰에서 도출한 실무 패턴이다. 그래서 ClariDoc은 이를 `technical_blog`의 기본 구조로 사용하되, 브리프와 프로젝트별 스타일이 우선하도록 설계했다.
|
||||
이 문장들은 사실 검증 과정에는 유용할 수 있지만 독자에게는 불필요하다. 독자는 source-pack의 형식이나 모델이 받은 지시를 알고 싶은 것이 아니라, 문제가 무엇이고 왜 그 선택을 했으며 어떤 비용을 감수했는지 알고 싶다.
|
||||
|
||||
## 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
|
||||
익숙한 기준점
|
||||
→ 핵심 용어와 경계
|
||||
→ 구성요소
|
||||
→ 데이터/제어 흐름
|
||||
→ 불변조건과 실패 조건
|
||||
→ 관측 가능한 결과
|
||||
application-core는 Spring DI를 의도적으로 사용한다.
|
||||
```
|
||||
|
||||
논리 reviewer는 전제 누락, 인과 점프, 순환 설명, 결론과 근거의 불일치를 찾도록 지시받는다.
|
||||
이 문장은 현재 상태만 말한다. 다음 질문에는 답하지 않는다.
|
||||
|
||||
### 원칙 7. 예시는 전체 경로를 따라가야 한다
|
||||
- 어떤 문제가 있었는가?
|
||||
- Spring을 완전히 제거하는 대안은 왜 선택하지 않았는가?
|
||||
- Spring DI를 허용하면서 어떤 비용을 받아들였는가?
|
||||
- 허용 범위가 transaction, transport, persistence까지 번지지 않도록 무엇을 막았는가?
|
||||
- 그 경계가 실제로 지켜지는지는 어떻게 확인하는가?
|
||||
|
||||
조각난 코드 블록이나 단편적인 명령은 문법을 보여 줄 수 있지만, 입력이 어떤 판단과 상태 변화를 거쳐 결과가 되는지 보여 주지 못한다. 학습 목적의 예시는 시작 상태, 실행, 중간 체크포인트, 결과, 실패 경계가 이어져야 한다.
|
||||
ClariDoc 0.2.0은 이 두 결함을 각각 **출력 경계**와 **결정 근거 회수** 문제로 다룬다.
|
||||
|
||||
**하네스 적용**
|
||||
## 2. 독자용 글과 내부 provenance를 분리한다
|
||||
|
||||
- `worked_example` 또는 대응 intent를 유형 계약에 포함
|
||||
- 예시 또는 코드 존재 검사
|
||||
- 튜토리얼에는 중간 checkpoint와 최종 verification 요구
|
||||
- 명령 블록은 언어 태그, 사전 조건, 예상 결과와 연결하도록 prompt에 명시
|
||||
작성 과정에는 출처 식별자가 필요하다. source chunk가 어느 문서의 어느 heading과 line range에서 왔는지 남겨야 이후 검토와 재현이 가능하다. 그러나 그 정보가 최종 글에 그대로 나타날 이유는 없다.
|
||||
|
||||
### 원칙 8. 절차는 행동뿐 아니라 안전 경계를 포함한다
|
||||
|
||||
작업 문서는 “무엇을 입력하라”만 알려 주면 부족하다. 시작 조건, 정상 결과, 중단 조건, 검증, 롤백을 함께 제공해야 실제 시스템에서 사용할 수 있다.
|
||||
|
||||
**하네스 적용**
|
||||
|
||||
절차형 문서에서 다음을 검사한다.
|
||||
|
||||
- 사전 조건
|
||||
- 번호가 있는 단계
|
||||
- 관측 가능한 검증
|
||||
- 롤백 또는 복구
|
||||
- 파괴적 명령 주변의 경고·백업·복구 경로
|
||||
|
||||
### 원칙 9. 참조 문서는 서술보다 조회 계약이 우선이다
|
||||
|
||||
참조 문서는 처음부터 끝까지 읽는 글이 아니라 정확한 값을 찾는 인터페이스다. 범위와 버전, 구문, 필드, 기본값, 동작, 오류, 최소 예시가 안정적으로 배치되어야 한다.
|
||||
|
||||
**하네스 적용**
|
||||
|
||||
`reference` 구조를 다음 순서로 고정한다.
|
||||
따라서 산출물을 두 층으로 나눈다.
|
||||
|
||||
```text
|
||||
범위/버전 → 구문 → 파라미터/필드 → 동작 → 오류 → 최소 예시 → 관련 항목
|
||||
reader-facing layer
|
||||
└─ document.md
|
||||
문제, 제약, 대안, 선택 이유, 메커니즘, 검증, 한계만 노출
|
||||
|
||||
internal audit layer
|
||||
├─ provenance.md
|
||||
├─ evidence-map.json
|
||||
├─ normalized inputs
|
||||
├─ raw model responses
|
||||
└─ manifest.json
|
||||
source ID, relative path, heading, line range, status, hash 보존
|
||||
```
|
||||
|
||||
테이블형 조회 표면이 없는 경우 경고하고, 버전 맥락과 미해결 placeholder를 검사한다.
|
||||
기술 블로그의 기본 `citation_style`은 `hidden`이다. 이 모드에서 다음 항목은 독자용 문서에 나타나면 오류다.
|
||||
|
||||
### 원칙 10. 주장은 출처 단위와 연결되어야 한다
|
||||
- `[S1]` 같은 내부 source marker
|
||||
- `raw/branch-notes/...` 같은 repository path
|
||||
- source access date
|
||||
- “제공된 근거”, “근거 팩”, “확인 대상으로 제시” 같은 작성 과정 설명
|
||||
- planner가 만든 section intent나 prompt tag
|
||||
|
||||
URL 목록만 주면 모델은 출처가 실제로 무엇을 지지하는지 추정하게 된다. 따라서 출처별로 사용할 수 있는 사실을 분리하고, 본문의 주장에 ID를 붙이는 편이 감사 가능하다.
|
||||
공개 링크나 각주가 필요한 문서는 `footnote` 또는 `inline_link`를 명시적으로 선택한다. 숨김 정책은 출처를 없애는 것이 아니라 **독자용 표현과 감사용 추적을 분리하는 것**이다.
|
||||
|
||||
**하네스 적용**
|
||||
## 3. 프로젝트 문서를 같은 무게로 취급하지 않는다
|
||||
|
||||
`SourcePack`의 각 항목은 `facts`와 `notes`를 가진다. 모델은 `[S1]` 같은 ID를 사용한다. 린터는 다음을 탐지한다.
|
||||
로컬 저장소에는 현재 상태, 결정 과정, 외부 동작, 선례가 함께 존재할 수 있다. 단어가 겹친다는 이유만으로 모두 같은 근거로 사용하면 현재 구현과 과거 메모가 섞이고, 외부 사례가 프로젝트의 선택 이유로 둔갑한다.
|
||||
|
||||
- 존재하지 않는 출처 ID
|
||||
- 인용이 필수인데 source pack이 비어 있음
|
||||
- 출처가 있는데 아무 ID도 사용하지 않음
|
||||
- 숫자·버전형 주장에 표식이 없음
|
||||
- 사용되지 않은 출처
|
||||
ClariDoc은 source type을 다음처럼 구분한다.
|
||||
|
||||
중요한 한계: 이 버전은 문장이 `facts`의 의미와 실제로 일치하는지 논리적으로 증명하지 않는다. evidence reviewer와 도메인 검토가 여전히 필요하다.
|
||||
| source type | 답할 수 있는 질문 | 답할 수 없는 질문 |
|
||||
|---|---|---|
|
||||
| `canonical-project` | 현재 프로젝트에서 실제로 구현·검증된 것은 무엇인가 | 왜 최초에 그 선택을 했는가가 항상 기록돼 있지는 않다 |
|
||||
| `canonical-concept` | 재사용 가능한 기술 개념과 일반 동작은 무엇인가 | 특정 프로젝트가 실제 채택했는가 |
|
||||
| `branch-note` | 어떤 제약, 대안, 이유, 비용으로 결정을 내렸는가 | 최신 canonical과 충돌할 때 현재 상태의 최종 권위가 되지는 않는다 |
|
||||
| `official-doc` | 프레임워크·프로토콜·제품이 어떻게 동작하는가 | 프로젝트의 의도와 채택 이유 |
|
||||
| `company-tech-blog` | 다른 조직이 어떤 조건에서 무엇을 시도했는가 | 보편적인 표준 또는 현재 프로젝트의 사실 |
|
||||
|
||||
### 원칙 11. 선택은 대안, 기준, 비용, 실패 조건을 함께 설명한다
|
||||
이 계층은 `llm-wiki-private`의 `raw → canonical → external output` 흐름과 맞물린다. 공개 글은 canonical의 검증된 현재 상태를 중심으로 삼고, branch-note에서 선택 배경을 회수하며, official docs와 company tech blog는 동작 설명과 선례를 보조한다.
|
||||
|
||||
“우리는 X를 사용했다”만으로는 독자가 자신의 상황에서 같은 결정을 내려야 하는지 판단할 수 없다. 선택 기준과 제약, 버린 대안, 받아들인 비용, 운영에서 드러난 실패 조건이 있어야 판단이 전이된다.
|
||||
## 4. 검색의 목표는 관련 문서가 아니라 결정 단위를 찾는 것이다
|
||||
|
||||
**하네스 적용**
|
||||
|
||||
- 기술 블로그·설명·설계 문서에 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은 문맥과 논리를 평가하는 데 유용하지만 동일 입력에서도 판단이 달라질 수 있다. 반대로 정규식과 구조 검사는 참·거짓을 이해하지 못하지만 재현 가능하다. 두 종류를 결합해야 한다.
|
||||
|
||||
**하네스 적용**
|
||||
일반적인 lexical search는 `application-core`, `Spring`, `DI`가 많이 등장하는 문서를 위로 올린다. 하지만 기술 글에 필요한 것은 이름의 공기(共起)가 아니라 다음 요소를 가진 문단이다.
|
||||
|
||||
```text
|
||||
composite = deterministic_lint × weight + model_review_mean × weight
|
||||
constraint
|
||||
→ choice
|
||||
→ reason
|
||||
→ alternative
|
||||
→ accepted cost
|
||||
→ guardrail
|
||||
→ verification
|
||||
```
|
||||
|
||||
점수 외에도 blocker와 error 개수 한도를 동시에 적용한다. 점수가 높아도 파괴적 명령 안전 경계나 금지 주장이 blocker이면 통과할 수 없다.
|
||||
ClariDoc의 local corpus collector는 Markdown heading 단위로 문서를 나누고 BM25 계열 점수에 다음 가중치를 더한다.
|
||||
|
||||
### 원칙 14. 결과뿐 아니라 과정도 감사 가능해야 한다
|
||||
- canonical/project status
|
||||
- decision, reason, alternative, trade-off, forbidden, verification 같은 용어
|
||||
- brief의 required topic과 core message
|
||||
- 한 파일이 결과 전체를 점유하지 않도록 하는 file diversity
|
||||
|
||||
좋은 문서가 한 번 생성되었다는 사실보다 어떤 브리프, 근거, 구성, 모델 응답, 리뷰, 수정으로 만들어졌는지 재현 가능한지가 중요하다.
|
||||
검색 결과는 절대 경로가 아닌 repository-relative path와 line range를 가진다. 선택 이유가 없는 chunk는 기술 이름이 일치해도 decision section의 주요 근거로 사용하지 않는다.
|
||||
|
||||
**하네스 적용**
|
||||
### `application-core` 사례
|
||||
|
||||
- 정규화된 입력 저장
|
||||
- planner/writer/reviewer/reviser 원문 응답 보존
|
||||
- 라운드별 초안·lint·review·gate 저장
|
||||
- provider 이벤트와 실행시간 기록
|
||||
- 최종 산출물의 SHA-256 manifest 생성
|
||||
- Mock 실행은 합성 평가임을 자동 경고
|
||||
프로젝트의 branch-note에는 다음 결정이 함께 기록돼 있었다.
|
||||
|
||||
## 4. 문서 유형별 질문 사슬
|
||||
- `@Service`, `@Component`는 DI 등록 목적으로 허용한다.
|
||||
- Spring DI까지 제거하면 use case마다 `@Configuration`에서 bean을 수동 등록해야 해 조립 코드가 늘어난다.
|
||||
- 이 편의를 위해 `spring-context`, `spring-beans` 의존 비용은 수용한다.
|
||||
- 대신 `spring-tx`, Spring Web, JPA annotation은 금지한다.
|
||||
- transaction 의미는 `TransactionPort`로 표현한다.
|
||||
- Gradle과 ArchUnit으로 build graph와 source dependency를 각각 검사한다.
|
||||
|
||||
### 4.1 기술 블로그
|
||||
따라서 독자용 설명은 “Spring을 의도적으로 쓴다”에서 멈추지 않고, 수동 조립 비용을 줄이기 위한 제한적 허용과 그 대가를 함께 설명해야 한다.
|
||||
|
||||
반대로 SLF4J의 존재만 확인되고 선택 이유가 근거에서 발견되지 않았다면, “의도적으로 사용했다”는 이유를 추정해서는 안 된다. 주장을 제거하거나 확인되지 않은 범위로 남겨야 한다.
|
||||
|
||||
## 5. 기술적 선택은 하나의 완결된 설명 단위여야 한다
|
||||
|
||||
좋은 기술 문서는 선택을 제품 이름이나 annotation 이름으로 요약하지 않는다. 독자가 자신의 환경에 판단을 옮길 수 있도록 선택이 성립한 조건을 보여 준다.
|
||||
|
||||
ClariDoc의 decision unit은 다음 여섯 항목을 최소 계약으로 사용한다.
|
||||
|
||||
1. **맥락과 제약**: 무엇이 단순한 해법을 막았는가
|
||||
2. **선택**: 무엇을 허용하거나 채택했는가
|
||||
3. **이유**: 어떤 구체적 비용 또는 실패를 줄이려 했는가
|
||||
4. **대안**: 현실적으로 가능한 다른 선택은 무엇이었는가
|
||||
5. **수용 비용**: 선택 때문에 새로 생기는 결합·운영·학습 비용은 무엇인가
|
||||
6. **가드레일**: 비용이 경계 밖으로 번지면 어떤 검사나 규칙이 실패하는가
|
||||
|
||||
운영 또는 설계 글에서는 검증과 적용하지 않을 조건까지 추가한다.
|
||||
|
||||
```text
|
||||
무엇을 해결하는가?
|
||||
→ 왜 어려운가?
|
||||
→ 어떤 판단 모델이 필요한가?
|
||||
→ 해결 방식은 어떻게 동작하는가?
|
||||
→ 구체적 입력이 결과로 어떻게 변하는가?
|
||||
→ 어떤 근거로 효과와 정확성을 판단하는가?
|
||||
→ 무엇을 포기했고 언제 쓰지 말아야 하는가?
|
||||
→ 독자는 다음에 무엇을 해야 하는가?
|
||||
context → constraint → options → decision → mechanism
|
||||
→ verification → accepted cost → not-applicable condition
|
||||
```
|
||||
|
||||
### 4.2 튜토리얼
|
||||
`RAT001`, `RAT002`, `RAT003` lint는 선택 선언 뒤 이유가 없는 문장, 대안·비용·가드레일 누락, 결정 섹션에 rationale evidence가 배치되지 않은 상태를 각각 탐지한다. 휴리스틱이므로 모델 reviewer와 도메인 소유자 검토를 대체하지는 않는다.
|
||||
|
||||
## 6. 우아한형제들 기술 블로그 표본에서 가져온 작성 패턴
|
||||
|
||||
우아한형제들의 공식 편집 규정을 확보한 것은 아니다. 공개된 기술 글 8편을 표본으로 읽고 반복되는 전개와 문장 형식을 운영 프로필로 추출했다. 표본은 2017~2025년에 공개된 Backend, Frontend, Data, AI, 장애 회고 글을 포함한다. 출처별 관찰과 일반화 경계는 `SOURCE_MATRIX.md`에 기록했다.
|
||||
|
||||
조사는 다음 두 층을 분리했다.
|
||||
|
||||
- **정보 전개 구조**: 문제, 제약, 대안, 선택 이유, 구현, 검증이 어떤 순서로 이어지는가
|
||||
- **문장 형식**: 문단을 어떤 문장으로 시작하고, 앞 문장과 어떤 관계를 만들며, 순서·질문·선택 이유를 어떻게 표현하는가
|
||||
|
||||
`문제 → 제약 → 대안 → 선택 이유`는 첫 번째 층의 계약이다. 이 구조를 `첫 번째 제약은`, `두 번째 제약은`, `세 번째 제약은` 같은 문장 틀로 출력해야 한다는 뜻은 아니다.
|
||||
|
||||
### 6.1 팀과 시스템의 실제 맥락에서 시작한다
|
||||
|
||||
Polars 적용기는 팀이 어떤 크기와 형태의 데이터를 처리하는지 먼저 설명하고 예상 독자를 명시한다. B마트 OMS 글은 고객, 라이더, 현장 작업자의 서로 다른 목표와 물리적 제약을 구체적인 주문 장면으로 보여 준다.
|
||||
|
||||
하네스 적용:
|
||||
|
||||
- 첫 섹션을 추상적인 정의가 아니라 `problem_scene`으로 둔다.
|
||||
- 팀, 시스템, 요청 흐름, 장애 증상, 반복 비용 중 최소 하나를 구체적으로 제시한다.
|
||||
- “이 글에서는 무엇을 다룬다”보다 독자가 왜 이 문제를 읽어야 하는지가 먼저 드러나게 한다.
|
||||
|
||||
### 6.2 문제를 비용과 관측 가능한 증상으로 표현한다
|
||||
|
||||
B마트 OMS 글은 피크 시간대에 주문이 몰릴 때 출고 지연, 라이더 대기, 현장 부하가 어떻게 연결되는지 보여 준다. LLMOps 글은 provider 복잡성, 프롬프트 버전 추적, 장애, 비용, 실험 재현성 같은 운영 문제를 각각 구체적인 실패로 분해한다.
|
||||
|
||||
하네스 적용:
|
||||
|
||||
- “복잡했다”, “비효율적이었다”만 쓰지 않는다.
|
||||
- 누가 어떤 작업을 반복했는지, 어떤 상태가 관측됐는지, 어느 경계에서 비용이 커졌는지 적는다.
|
||||
- 근거가 없는 수치는 만들지 않는다. 숫자가 없다면 qualitative cost를 정확히 제한해 쓴다.
|
||||
|
||||
### 6.3 선택지를 보여 준 뒤 선택 이유를 설명한다
|
||||
|
||||
LLMOps 글은 Langfuse를 선택하기 전에 여러 후보와 각 후보의 한계를 비교한다. 기술 선택은 “유명해서”가 아니라 현재 조직의 요구와 맞지 않은 지점을 통해 설명된다.
|
||||
|
||||
하네스 적용:
|
||||
|
||||
- `options`와 `decision_rationale`을 별도 intent로 둔다.
|
||||
- 대안을 허수아비로 만들지 않는다.
|
||||
- 비교 기준은 brief와 근거에서 회수한다.
|
||||
- 선택의 장점과 함께 수용한 비용을 쓴다.
|
||||
|
||||
### 6.4 구현은 구성요소 목록이 아니라 흐름으로 설명한다
|
||||
|
||||
B마트 OMS 글은 주문, 출고, 배송, 시뮬레이션 시간과 비동기 작업이 어떤 순서로 이어지는지 보여 준다. 독자는 클래스 이름을 외우는 대신 입력이 결과로 변하는 경로를 따라간다.
|
||||
|
||||
하네스 적용:
|
||||
|
||||
```text
|
||||
무엇을 완성하는가?
|
||||
→ 무엇이 필요한가?
|
||||
→ 전체 여정은 어떤 모습인가?
|
||||
→ 어떤 순서로 따라가는가?
|
||||
→ 각 단계가 맞는지 어떻게 확인하는가?
|
||||
→ 최종 결과를 어떻게 검증하는가?
|
||||
→ 무엇을 정리하고 다음에 무엇을 배우는가?
|
||||
input → decision → state change → dependency call
|
||||
→ observation → success / stop / recovery
|
||||
```
|
||||
|
||||
### 4.3 하우투
|
||||
- 메커니즘 섹션에 데이터 또는 제어 흐름을 요구한다.
|
||||
- component 목록만 나열하면 reviewer가 인과 단절로 지적한다.
|
||||
|
||||
### 6.5 검증 결과와 한계를 같이 둔다
|
||||
|
||||
공개 기술 글은 시뮬레이션, 성능 지표, 파일럿 결과, 장애 회고처럼 선택이 실제로 무엇을 바꿨는지 보여 준다. 장애 회고는 시간 순서와 놓친 조건을 드러내고 이후의 리뷰·협업 개선으로 연결한다.
|
||||
|
||||
하네스 적용:
|
||||
|
||||
- test, build rule, metric, incident timeline 중 실제로 존재하는 검증만 사용한다.
|
||||
- local verification을 production verification으로 확대하지 않는다.
|
||||
- 정적 분석의 reflection 우회처럼 자동 검사가 보장하지 못하는 범위를 함께 쓴다.
|
||||
|
||||
### 6.6 개요의 분류명을 문장 머리에 반복하지 않는다
|
||||
|
||||
8편에서 `첫 번째 제약은`이라는 문장 형식은 확인되지 않았다. 순서 표현은 존재했지만 용도가 달랐다. 실제 처리 단계, 두 가지 입력 방법, 여러 레이어, 차트처럼 **순서 자체가 내용인 대상**을 구분할 때 사용했다. 반면 문제와 제약은 대체로 구체적인 상태와 그 결과를 바로 서술했다.
|
||||
|
||||
예를 들어 표본은 다음과 같은 관계를 문장에 드러낸다.
|
||||
|
||||
| 문장 역할 | 표본에서 관찰한 형식 | 적용 경계 |
|
||||
|---|---|---|
|
||||
| 문제 전환 | 정상적으로 보이던 상태 뒤에 달라진 조건과 비용을 `하지만`, `문제는`, `다만`으로 연결 | 접속어 자체를 의무화하지 않고 실제 역접 관계가 있을 때만 사용 |
|
||||
| 인과 연결 | 앞 문장의 상태를 `이 때문에`, `그 결과`, `그래서`, `이에`로 다시 받아 선택이나 결과로 연결 | 지시어가 가리키는 원인이 바로 앞 문맥에 명확해야 함 |
|
||||
| 선택 이유 | 후보나 기준을 먼저 제시하고, 선택 문장에서 현재 조건과 제외 이유를 함께 설명 | 제품 이름이나 장점 목록만으로 선택을 정당화하지 않음 |
|
||||
| 질문 | 질문형 heading이나 짧은 전환 질문을 두고 바로 사례·설명·결과로 답함 | 답하지 않는 수사 질문을 장식처럼 반복하지 않음 |
|
||||
| 순서 표현 | 실제 단계, 방법, 레이어, 도표의 순서를 구분 | 추상적인 section intent를 산문으로 읽어 주는 용도로 사용하지 않음 |
|
||||
| 프로젝트 목소리 | `팀에서는`, `저희는`, `우리는`으로 판단 주체와 적용 범위를 밝힘 | 모든 문장을 1인칭으로 쓰거나 조직의 선택을 보편 법칙으로 확대하지 않음 |
|
||||
|
||||
하네스 적용:
|
||||
|
||||
- outline의 `constraints`, `options`, `decision_rationale`은 작성자가 충족해야 할 의미 계약이지 독자에게 그대로 읽어 줄 문장 표지가 아니다.
|
||||
- 문단은 가능하면 행위자·상태·변화·영향 중 하나를 바로 제시한다.
|
||||
- 연속된 병렬 항목이 실제로 필요하면 목록이나 의미 있는 소제목을 사용한다.
|
||||
- `첫 번째/두 번째/세 번째 + 추상 분류명`으로 문단을 반복 시작하면 deterministic lint가 `STYLE001` warning을 낸다.
|
||||
- editor reviewer는 정보 구조가 문장 템플릿으로 노출됐는지, 질문이 바로 답을 얻는지, 접속어가 실제 논리 관계를 가리키는지 별도로 검사한다.
|
||||
|
||||
이 규칙은 우아한형제들의 문장을 복제하기 위한 것이 아니다. 조사 표본에서 확인한 **구체성, 관계가 드러나는 전환, 판단 주체, 순서 표현의 제한된 용도**를 하네스의 작성·검토 기준으로 번역한 것이다.
|
||||
|
||||
## 7. 우아한테크코스와 Tecoble에서 가져온 학습형 글 패턴
|
||||
|
||||
우아한테크코스 조직은 교육 자료와 학습 기록을 공개하고 있으며, Tecoble에는 팀 프로젝트에서 겪은 문제를 출발점으로 단계적 해결 과정을 설명하는 글이 축적돼 있다. 이를 공식 글쓰기 교과과정 전체로 일반화하지 않고, 학습형 기술 글에서 유용한 다음 패턴만 반영했다.
|
||||
|
||||
- 자신이 놓였던 프로젝트 상황과 선행지식을 먼저 밝힌다.
|
||||
- 작은 재현 사례에서 출발해 개념을 확장한다.
|
||||
- 처음 시도와 실패 이유를 숨기지 않는다.
|
||||
- 최종 코드만 보여 주지 않고 판단이 바뀐 과정을 설명한다.
|
||||
- 독자가 따라 할 수 있도록 입력, 결과, 검증 지점을 제공한다.
|
||||
|
||||
이 패턴은 `tutorial`, `explanation`, 입문자 대상 `technical_blog`에 적용한다. 숙련 독자를 위한 reference 문서에는 같은 서사 구조를 강제하지 않는다.
|
||||
|
||||
## 8. 일반 기술 문서 원칙과의 결합
|
||||
|
||||
우아한형제들 표본의 문제 해결 서사만으로 모든 문서 유형을 설계할 수는 없다. 다음 공식·표준 자료를 함께 사용한다.
|
||||
|
||||
- Google Technical Writing: 독자, 범위, 문단 중심점, outline, 점진적 상세화
|
||||
- GitHub Docs content design: 사용자 목표, 콘텐츠 유형, 결론 우선, 의미 있는 heading
|
||||
- Diátaxis: tutorial, how-to, explanation, reference의 목적 분리
|
||||
- OASIS DITA: concept, task, reference, troubleshooting의 정보 구조
|
||||
- Kubernetes documentation types: task와 tutorial의 선행 조건, 단계, 검증
|
||||
|
||||
이를 바탕으로 ClariDoc은 일곱 문서 유형을 분리한다.
|
||||
|
||||
| 유형 | 독자가 끝내려는 일 | 핵심 질문 사슬 |
|
||||
|---|---|---|
|
||||
| `technical_blog` | 문제와 설계 판단 이해 | 문제 → 제약 → 대안 → 이유 → 구현 → 검증 → 비용 → 판단 |
|
||||
| `tutorial` | 안내받으며 결과와 개념 학습 | 결과 → 준비 → 전체 경로 → 단계 → 체크포인트 → 검증 → 다음 학습 |
|
||||
| `how_to` | 특정 작업 완료 | 적용 조건 → 사전 조건 → 절차 → 확인 → 롤백 → 문제 해결 |
|
||||
| `explanation` | 개념과 인과 모델 이해 | 질문/답 → 기준점 → 모델 → 메커니즘 → 예시 → 대안 → 한계 |
|
||||
| `reference` | 정확한 사실 조회 | 범위 → 구문 → 필드 → 동작 → 오류 → 최소 예시 → 관련 항목 |
|
||||
| `troubleshooting` | 증상에서 원인과 복구로 이동 | 증상 → 영향 → 안전 → 진단 → 분기 → 조치 → 복구 → 예방 |
|
||||
| `design_doc` | 대안을 비교하고 결정 | 요약 → 문제 → 목표 → 제약 → 대안 → 결정 → 구조 → 실패 → 배포 → 관측 → 위험 |
|
||||
|
||||
## 9. 모델 역할을 분리한다
|
||||
|
||||
하나의 모델이 작성과 자기검토를 모두 수행하면 같은 전제와 누락을 반복하기 쉽다. ClariDoc은 역할을 분리하고 자유 형식 감상이 아니라 JSON 계약으로 리뷰를 받는다.
|
||||
|
||||
| 역할 | 기본 provider | 검사 대상 |
|
||||
|---|---|---|
|
||||
| planner | Codex | 구조, reader question, evidence allocation |
|
||||
| writer | Claude | 자연스러운 reader-facing prose |
|
||||
| logic reviewer | Codex | 전제, 인과, 결론 |
|
||||
| decision reviewer | Codex | 이유, 대안, 비용, 가드레일 |
|
||||
| reader reviewer | Claude | 독자 맥락, 인지 부하, 정보 누락 |
|
||||
| editor reviewer | Claude | 도입, 문단 초점, 전환, 반복, 상투 문구 |
|
||||
| evidence reviewer | Antigravity | source fit, status, 과장, provenance 누출 |
|
||||
| operations reviewer | Antigravity | 안전, 검증, 롤백, 실패 경로 |
|
||||
| reviser | Claude | blocker와 error 수정 |
|
||||
|
||||
모델을 다르게 배치해도 진실이 자동으로 보장되는 것은 아니다. 결정적 lint, source hierarchy, manifest, 사람 검토가 함께 필요하다.
|
||||
|
||||
## 10. 품질 게이트가 증명하는 것과 증명하지 않는 것
|
||||
|
||||
품질 게이트는 다음을 재현 가능하게 확인한다.
|
||||
|
||||
- 문서 유형의 필수 섹션이 존재하고 순서를 지키는가
|
||||
- 작성 과정의 메타 문장이 독자용 글에 누출됐는가
|
||||
- 선택 선언에 이유, 대안, 비용, 가드레일이 있는가
|
||||
- 절차에 사전 조건, 검증, 중단, 복구가 있는가
|
||||
- provider 응답이 계약 형식을 지켰는가
|
||||
- 산출물과 provenance의 hash가 일치하는가
|
||||
|
||||
다음은 증명하지 않는다.
|
||||
|
||||
- source 문장이 현실 세계에서 참이라는 것
|
||||
- 모델 reviewer의 합의가 도메인 정답이라는 것
|
||||
- 코드와 명령이 대상 시스템에서 안전하게 실행된다는 것
|
||||
- local test 결과가 production 효과를 보장한다는 것
|
||||
- 표본에서 추출한 글쓰기 패턴이 우아한형제들의 공식 규정이라는 것
|
||||
|
||||
Mock provider PASS는 파이프라인 배선과 검사기의 동작만 검증한다. 실제 문서 품질 점수로 사용하지 않는다.
|
||||
|
||||
## 11. 최종 작성 원칙
|
||||
|
||||
ClariDoc이 기술 글에 요구하는 핵심은 다음 한 문장으로 정리할 수 있다.
|
||||
|
||||
> 독자에게는 문제와 판단의 흐름만 보이고, 검토자에게는 그 판단이 어디에서 왔는지 끝까지 추적되어야 한다.
|
||||
|
||||
이를 위해 최종 글은 다음 순서를 지향한다.
|
||||
|
||||
```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)를 참조한다.
|
||||
이 구조는 미문을 보장하지 않는다. 대신 독자가 “무엇을 했는가”뿐 아니라 “왜 그랬고, 어디까지 믿어도 되는가”를 판단할 수 있는 최소 조건을 만든다.
|
||||
|
||||
+84
-44
@@ -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의 이해도 검증
|
||||
|
||||
현재 프로필은 조사 표본과 프로젝트 요구를 바탕으로 한 설계 가설이다. 이를 공식 스타일이나 보편 법칙으로 주장하지 않는다.
|
||||
|
||||
Reference in New Issue
Block a user