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

docs/LOGIC_MODEL.md

@@ -1,168 +1,125 @@
-# Logic model for comprehensible technical documents
+# Logic model
 
-## 1. 문서는 질문 그래프다
+## 1. 독자 질문의 순서
 
-좋은 기술 문서를 “서론-본론-결론”이라는 형식만으로 설명하면 부족하다. 실제 독자는 순차적으로 다음 질문을 해결한다.
+좋은 기술 글은 정보량보다 질문의 순서를 통제한다. 기술 블로그의 기본 질문은 다음과 같다.
 
 ```text
-왜 읽어야 하는가?
-  ↓
-정확히 무엇을 다루는가?
-  ↓
-무엇을 이미 알아야 하는가?
-  ↓
-핵심 답 또는 결과는 무엇인가?
-  ↓
-그 답이 성립하는 이유와 메커니즘은 무엇인가?
-  ↓
-구체적인 사례에서 어떻게 보이는가?
-  ↓
-어떻게 확인하는가?
-  ↓
-언제 실패하거나 선택하지 않아야 하는가?
-  ↓
-그래서 무엇을 해야 하는가?
+무슨 문제가 있었나?
+왜 단순히 풀 수 없었나?
+무엇을 검토했나?
+왜 이 선택을 했나?
+코드에서는 어떻게 동작하나?
+무엇으로 확인했나?
+어떤 비용과 한계가 남았나?
+내 환경에서 무엇을 판단해야 하나?
 ```
 
-모든 문서가 이 질문을 동일한 비중으로 다루지는 않는다. 문서 유형은 **독자의 현재 상태와 목적**에 따라 필요한 질문 부분을 선택하고 순서를 최적화한 것이다.
+제목은 이 질문에 대한 표지판이어야 한다. `개요`, `상세`, `기타`처럼 정보 역할을 드러내지 않는 heading은 경고 대상이다.
 
-## 2. 문서 유형을 섞을 때의 규칙
+## 2. Decision unit
 
-한 페이지에 여러 유형이 존재할 수 있지만 주된 목적은 하나여야 한다.
+기술 선택은 다음 6요소를 하나의 논리 단위로 본다.
 
-- Tutorial 안의 짧은 explanation은 현재 단계를 이해시키는 데 필요한 만큼만 둔다.
-- How-to 안의 reference table은 절차 수행에 필요한 조회 표면으로 제한한다.
-- Technical blog 안의 code example은 전체 API reference가 아니라 인과 관계를 보여준다.
-- Reference 안의 장황한 배경 설명은 별도 explanation으로 분리한다.
-- Troubleshooting 안의 fix는 확인된 cause branch에만 연결한다.
+| 요소 | 질문 |
+|---|---|
+| context/constraint | 어떤 문제와 제약 아래에서 결정했는가 |
+| choice | 무엇을 선택·허용·금지했는가 |
+| why | 그 선택이 어떤 비용이나 위험을 줄였는가 |
+| alternative | 현실적인 다른 선택은 무엇이었는가 |
+| accepted cost | 선택 때문에 무엇을 감수했는가 |
+| guardrail | 허용 범위가 넓어지지 않게 무엇이 실패하는가 |
 
-판정 질문:
+“X를 의도적으로 사용한다”는 choice 하나만 있다. 이유가 없으면 `RAT001`, 대안·비용·가드레일이 없으면 `RAT002` 후보가 된다.
 
-> 이 부분이 독자의 현재 목표를 직접 전진시키는가, 아니면 다른 문서 유형의 목표를 새로 시작하는가?
+## 3. Evidence semantics
 
-후자라면 분리하거나 링크한다.
+근거는 단어 일치가 아니라 claim role로 배치한다.
 
-## 3. 논리 구조의 최소 단위
+- **current state**: canonical project가 우선
+- **decision history and rationale**: branch note가 유용
+- **vendor/protocol behavior**: official docs
+- **precedent**: company tech blog
+- **general explanation**: canonical concept 또는 안정적인 background knowledge
 
-### Section contract
+공식 문서가 `@Service`의 동작을 설명해도 프로젝트가 왜 그것을 선택했는지는 증명하지 않는다. 반대로 branch note가 선택 이유를 설명해도 현재 구현 상태가 바뀌었다면 canonical source를 확인해야 한다.
 
-각 section은 다음을 가진다.
+## 4. Status boundary
 
-1. **Reader question**: 독자가 이 시점에 묻는 질문
-2. **Purpose**: 이 절이 수행할 정보 작업
-3. **Claim/answer**: 질문에 대한 명시적 답
-4. **Support**: 근거, 메커니즘, 예시 또는 절차
-5. **Boundary**: 답이 유효한 범위와 예외
-6. **Transition**: 다음 질문이 왜 생기는지 연결
-
-### Paragraph contract
-
-문단은 보통 다음 순서를 사용한다.
+다음 status를 서로 바꾸어 쓰지 않는다.
 
 ```text
-중심 문장 → 이유/근거 → 구체화/예시 → 다음 문장으로의 연결
+actually implemented
+locally verified
+production verified
+documented only
+planned
+needs confirmation
+unsupported
 ```
 
-문단이 두 개의 독립 결론을 갖거나, 첫 문장이 뒤의 내용을 예고하지 못하거나, 마지막 문장이 새 주제를 시작하면 분리 후보로 본다.
+로컬 ArchUnit test 통과는 운영 효과의 증거가 아니다. 다른 회사의 사례는 이 프로젝트가 같은 결과를 얻었다는 증거가 아니다.
 
-## 4. 이해를 돕는 인과 구조
+## 5. Concrete example
 
-기술 설명에서 목록만 나열하면 독자는 구성요소를 기억해도 시스템을 예측하지 못한다. 메커니즘 section은 다음 중 하나의 명시적 순서를 사용한다.
-
-- 시간: 요청 전 → 요청 중 → 응답 후
-- 데이터 흐름: 입력 → 변환 → 저장 → 출력
-- 제어 흐름: 조건 → 분기 → 행동 → 상태 전이
-- 장애 흐름: 트리거 → 증상 → 전파 → 완화 → 복구
-- 결정 흐름: 제약 → 비교 기준 → 대안 평가 → 선택 → 수용 비용
-
-각 화살표에는 “왜 다음 상태가 되는가”가 있어야 한다. 단순히 컴포넌트 이름을 이어 붙이지 않는다.
-
-## 5. 점진 공개
-
-독자가 세부사항을 이해하기 위한 구조를 먼저 제공한다.
-
-1. 핵심 답/결과
-2. 범위와 전제
-3. 가장 단순한 모델
-4. 정상 메커니즘
-5. 완주하는 예시
-6. 검증
-7. 예외·실패·트레이드오프
-8. 운영 세부사항
-
-예외를 너무 일찍 넣으면 기본 모델을 형성하기 어렵고, 너무 늦게 숨기면 과도한 확신을 준다. 기본 모델을 제시한 직후 “어디까지 유효한가”를 명시하고, 상세 예외는 뒤에서 확장한다.
-
-## 6. Worked example 계약
-
-예시는 코드 조각의 존재가 아니라 **시작 상태부터 검증 결과까지의 연결**이다.
-
-필수 요소:
-
-- 초기 상태와 입력
-- 각 단계의 행동 또는 상태 변화
-- 단계의 이유
-- 예상 관측
-- 최종 결과
-- 성공 기준
-- 실패했을 때 되돌아갈 지점
-
-초보 독자에게는 중간 추론을 더 많이 보이고, 숙련 독자용 문서에서는 자명한 단계를 줄인다. 브리프의 `prior_knowledge`가 이 깊이를 결정한다.
-
-## 7. 근거와 주장 수준
-
-문장은 다음 네 종류 중 하나로 분류할 수 있어야 한다.
-
-| 종류 | 예 | 처리 |
-|---|---|---|
-| 관측 사실 | 특정 로그가 발생했다 | 출처·실험·측정 연결 |
-| 일반 기술 사실 | 프로토콜 의미, API 계약 | 권위 있는 reference 연결 |
-| 가정/가상 예시 | 설명을 위한 단순 모델 | 가정/예시임을 표시 |
-| 권고/판단 | 이 조건에서는 A를 선택 | 기준·대안·비용을 공개 |
-
-“관련된 출처”와 “그 주장을 지지하는 출처”는 다르다. Source pack의 `facts`는 허용된 주장 범위를 줄이는 역할을 한다.
-
-## 8. 트레이드오프 구조
-
-좋은 기술 글은 선택을 미화하지 않는다.
+예시는 최종 코드 조각만 보여주지 않는다.
 
 ```text
-선택한 접근
-├── 얻는 것
-├── 지불하는 비용
-├── 대안
-├── 선택 기준
-├── 실패 조건
-└── 선택하지 말아야 하는 상황
+initial state
+  → input
+  → decision criterion
+  → selected path
+  → state/control-flow change
+  → observable result
+  → success or recovery criterion
 ```
 
-대안을 비교할 때는 같은 기준을 사용한다. 한 대안은 성능으로, 다른 대안은 구현 편의성으로만 설명하면 비교가 성립하지 않는다.
+독자는 예시에서 추상 모델의 각 요소를 대응시킬 수 있어야 한다.
 
-## 9. 절차 안전성
+## 6. Korean problem-solving blog profile
 
-절차 문서의 단계는 다음 상태 머신으로 본다.
+`woowahan_tech_blog_ko` profile은 다음을 권장한다.
 
-```text
-PRECONDITION_CHECKED
-  → CHECKPOINT_CREATED
-  → CHANGE_APPLIED
-  → EXPECTED_RESULT_OBSERVED
-  → VERIFIED
-```
+- 팀이나 시스템의 구체적 맥락에서 시작
+- 기술 이름보다 문제와 비용을 먼저 설명
+- 기존 방식, 실패한 시도, 대안을 숨기지 않음
+- 선택 기준과 이유를 명시
+- 구현 세부가 앞에서 세운 문제에 답하도록 구성
+- 검증 결과를 원래 문제에 다시 연결
+- project-local 결정을 보편 규칙으로 쓰지 않음
+- 억지 접속어보다 문단 사이의 실제 논리 관계를 수정
+- `문제 → 제약 → 대안 → 선택`을 의미 순서로 사용하되 문장 틀로 읽어 주지 않음
+- 문단을 행위자, 상태, 변화, 결과, 판단에서 시작
+- 질문형 heading은 바로 다음 문장에서 답하고, 접속어는 실제 인과·역접을 가리키게 함
+- 순서어는 실제 단계·방법·레이어·도표에 사용하고, 추상 분류는 목록이나 의미 있는 소제목으로 표현
 
-어느 단계에서든 불일치하면 다음으로 진행하지 않고 `STOPPED → ROLLED_BACK → RECOVERY_VERIFIED`로 이동해야 한다. 파괴적 명령은 경고 문구만으로 충분하지 않으며 백업/복구점, 영향 범위, 확인 명령이 함께 있어야 한다.
+이는 샘플 글에서 관찰한 패턴을 하네스 규칙으로 번역한 것이며 공식 house style은 아니다.
 
-## 10. 품질 평가 차원
+특히 `첫 번째 제약은`, `두 번째 제약은`, `세 번째 제약은`처럼 outline의 분류명을 연속 문단 머리에 두는 방식은 정보 구조를 산문으로 노출한다. 한국어 기술 블로그에서 이런 형식이 가까운 문단에 세 번 이상 나타나면 `STYLE001` warning 대상이다. 실제 순서를 설명하는 번호 목록과 단계 문장은 대상이 아니다.
 
-모델 reviewer는 다음 차원을 각각 검사한다.
+## 7. Date and citation logic
 
-- `reader_goal_alignment`: 약속한 결과를 실제로 제공하는가
-- `information_architecture`: 문서 유형과 section 역할이 맞는가
-- `logical_flow`: 전제·인과·결론·전환이 끊기지 않는가
-- `cognitive_load`: 선행지식에 맞고 세부사항이 점진적으로 공개되는가
-- `evidence_traceability`: 확인 가능한 주장이 근거와 연결되는가
-- `example_verifiability`: 예시가 끝까지 실행·검증 가능한가
-- `scannability`: heading과 첫 문장만 읽어도 구조가 보이는가
-- `operational_safety`: 절차·변경·실패·복구가 안전한가
-- `completeness_and_limits`: 범위, 비범위, 예외, 트레이드오프가 있는가
+- access date는 provenance
+- version/date가 behavior, compatibility, reproducibility를 바꿀 때만 본문에 사용
+- hidden citation mode에서는 internal marker 금지
+- public citation이 필요하면 footnote 또는 inline link 사용
 
-한 차원의 평균이 전체 결함을 숨기지 않도록 blocker/error 개수를 점수와 별도로 게이트한다.
+## 8. Lint와 model review의 역할 분리
+
+Deterministic lint가 잘하는 것:
+
+- heading 계약
+- source marker/path/date/meta 문자열 누출
+- 명시적 choice 뒤 rationale 어휘 부재
+- 반복된 서수 문단처럼 형식적으로 식별 가능한 문장 scaffolding
+- 절차 구조와 파괴적 command safety
+
+Model review가 필요한 것:
+
+- 이유가 실제로 선택을 정당화하는가
+- 대안 비교가 공정한가
+- source chunk가 claim을 충분히 지지하는가
+- 문단 흐름과 독자 인지 부하
+- 질문이 바로 답을 얻고 접속어가 실제 관계를 가리키는가
+- 정보 구조가 기계적인 문장 틀로 노출됐는가
+- project-local policy의 과장 여부