126 lines
5.1 KiB
Markdown
126 lines
5.1 KiB
Markdown
# 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의 과장 여부
|