Logic model

1. 독자 질문의 순서

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

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

제목은 이 질문에 대한 표지판이어야 한다. 개요, 상세, 기타처럼 정보 역할을 드러내지 않는 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를 서로 바꾸어 쓰지 않는다.

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

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

5. Concrete example

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

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

5.1 KiB Raw Blame History