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)를 참조한다.
|
||||
이 구조는 미문을 보장하지 않는다. 대신 독자가 “무엇을 했는가”뿐 아니라 “왜 그랬고, 어디까지 믿어도 되는가”를 판단할 수 있는 최소 조건을 만든다.
|
||||
|
||||
Reference in New Issue
Block a user