# Logic model

## 1. 독자 질문의 순서

좋은 기술 글은 정보량보다 질문의 순서를 통제한다. 기술 블로그의 기본 질문은 다음과 같다.

```text
무슨 문제가 있었나?
왜 단순히 풀 수 없었나?
무엇을 검토했나?
왜 이 선택을 했나?
코드에서는 어떻게 동작하나?
무엇으로 확인했나?
어떤 비용과 한계가 남았나?
내 환경에서 무엇을 판단해야 하나?
```

제목은 이 질문에 대한 표지판이어야 한다. `개요`, `상세`, `기타`처럼 정보 역할을 드러내지 않는 heading은 경고 대상이다.

## 2. Decision unit

기술 선택은 다음 6요소를 하나의 논리 단위로 본다.

| 요소 | 질문 |
|---|---|
| context/constraint | 어떤 문제와 제약 아래에서 결정했는가 |
| choice | 무엇을 선택·허용·금지했는가 |
| why | 그 선택이 어떤 비용이나 위험을 줄였는가 |
| alternative | 현실적인 다른 선택은 무엇이었는가 |
| accepted cost | 선택 때문에 무엇을 감수했는가 |
| guardrail | 허용 범위가 넓어지지 않게 무엇이 실패하는가 |

“X를 의도적으로 사용한다”는 choice 하나만 있다. 이유가 없으면 `RAT001`, 대안·비용·가드레일이 없으면 `RAT002` 후보가 된다.

## 3. Evidence semantics

근거는 단어 일치가 아니라 claim role로 배치한다.

- **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

공식 문서가 `@Service`의 동작을 설명해도 프로젝트가 왜 그것을 선택했는지는 증명하지 않는다. 반대로 branch note가 선택 이유를 설명해도 현재 구현 상태가 바뀌었다면 canonical source를 확인해야 한다.

## 4. Status boundary

다음 status를 서로 바꾸어 쓰지 않는다.

```text
actually implemented
locally verified
production verified
documented only
planned
needs confirmation
unsupported
```

로컬 ArchUnit test 통과는 운영 효과의 증거가 아니다. 다른 회사의 사례는 이 프로젝트가 같은 결과를 얻었다는 증거가 아니다.

## 5. Concrete example

예시는 최종 코드 조각만 보여주지 않는다.

```text
initial state
  → input
  → decision criterion
  → selected path
  → state/control-flow change
  → observable result
  → success or recovery criterion
```

독자는 예시에서 추상 모델의 각 요소를 대응시킬 수 있어야 한다.

## 6. Korean problem-solving blog profile

`woowahan_tech_blog_ko` profile은 다음을 권장한다.

- 팀이나 시스템의 구체적 맥락에서 시작
- 기술 이름보다 문제와 비용을 먼저 설명
- 기존 방식, 실패한 시도, 대안을 숨기지 않음
- 선택 기준과 이유를 명시
- 구현 세부가 앞에서 세운 문제에 답하도록 구성
- 검증 결과를 원래 문제에 다시 연결
- project-local 결정을 보편 규칙으로 쓰지 않음
- 억지 접속어보다 문단 사이의 실제 논리 관계를 수정
- `문제 → 제약 → 대안 → 선택`을 의미 순서로 사용하되 문장 틀로 읽어 주지 않음
- 문단을 행위자, 상태, 변화, 결과, 판단에서 시작
- 질문형 heading은 바로 다음 문장에서 답하고, 접속어는 실제 인과·역접을 가리키게 함
- 순서어는 실제 단계·방법·레이어·도표에 사용하고, 추상 분류는 목록이나 의미 있는 소제목으로 표현

이는 샘플 글에서 관찰한 패턴을 하네스 규칙으로 번역한 것이며 공식 house style은 아니다.

특히 `첫 번째 제약은`, `두 번째 제약은`, `세 번째 제약은`처럼 outline의 분류명을 연속 문단 머리에 두는 방식은 정보 구조를 산문으로 노출한다. 한국어 기술 블로그에서 이런 형식이 가까운 문단에 세 번 이상 나타나면 `STYLE001` warning 대상이다. 실제 순서를 설명하는 번호 목록과 단계 문장은 대상이 아니다.

## 7. Date and citation logic

- access date는 provenance
- version/date가 behavior, compatibility, reproducibility를 바꿀 때만 본문에 사용
- hidden citation mode에서는 internal marker 금지
- public citation이 필요하면 footnote 또는 inline link 사용

## 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의 과장 여부