[AI 활용법 12] 문서화 3계층 — 주석 · 커밋 · 노트, 무엇을 어디에 쓰나

시리즈 12편. 문서는 쓰는 것 보다 어디에 쓰는가 가 더 중요하다. 자리가 틀리면 다음 주의 거짓말 이 된다.

3계층 — 무엇을 어디에

LLM에게 “주석 추가해 줘”라고만 하면, 셋의 차이를 모르고 아무 데나 쓴다. 명시적으로 어디에 쓰라고 알려 줘야 한다.

코드 주석 — Locality

코드 주석의 책임: 이 라인을 보는 사람 이 이 라인만 보고는 알 수 없는 것을 알려 줌.

좋은 주석:

# Skip rows where status='draft' — the analytics
# pipeline excludes them per ADR 2026-04-22-ingest.
rows = [r for r in rows if r["status"] != "draft"]

나쁜 주석:

# Filter rows
rows = [r for r in rows if r["status"] != "draft"]

무엇을 하는지 는 코드가 이미 말한다. 왜 를 추가해야 가치가 있다.

주석 안티패턴

• ❌ // added on 2026-04-22 (커밋 메타데이터에 있음)
• ❌ # TODO: ask Yoo about this (그가 떠나면?)
• ❌ 코드와 다른 동작 을 묘사 (코드가 변하면 주석이 거짓말)
• ❌ 주석으로 코드 단락 을 따로 표시 (함수로 빼라)

LLM이 주석을 잘 쓰게 하기

[규칙]
- 주석은 영문, "왜"만 적는다.
- "what"은 코드에 있다 — 다시 쓰지 않는다.
- TODO/FIXME 외엔 사람 이름 적지 않는다.
- 외부 제약, 이상해 보이는 결정의 이유, 알려진 버그 우회만 적는다.

커밋 메시지 — History

커밋의 책임: 시간이 흐른 뒤, 왜 이렇게 됐는지 를 git log로 찾을 수 있게.

fix(scheduler): drop draft rows in ingest pipeline

Drafts were being aggregated into daily metrics, leaking into
customer-facing dashboards. We now filter at ingest, matching
the rule in ADR 2026-04-22-ingest.

Refs: #481

핵심 3요소:

• subject — 한 줄 요약, type(scope) 포함
• body — 왜, 어떤 영향, 어떤 대안을 검토했는지
• footer — 이슈/ADR 참조, BREAKING CHANGE

코드 주석 vs 커밋 메시지

겹치지만 다르다:

• 코드 주석은 그 라인을 보는 사람
• 커밋 메시지는 그 변경 을 보는 사람 (git blame, PR 리뷰)

같은 왜 가 쓰일 수도 있고, 다를 수도 있다. 주석이 영구적 진실, 커밋이 그 진실로 옮겨간 이유.

Obsidian / 노트 — Context

노트의 책임: 코드/커밋에 남기지 않을 맥락. 의사결정의 배경, 시도-실패 기록, 외부 사람과의 논의, 한국어 풀이.

Projects/<프로젝트명>/
├── overview.md
├── decisions/
│   └── 2026-04-22-ingest.md       # ADR
├── logs/
│   └── 2026-04-29.md              # 작업 로그
├── issues/
│   └── draft-leak-incident.md     # 사고 회고
└── plans/
    └── today-queue.md

Obsidian에 쓰는 것 vs 안 쓰는 것

쓴다 ✅

• ADR (선택과 그 결과)
• 사고 회고 (5 whys)
• 외부 사람과의 논의 요약
• 한국어 맥락
• 시도해 봤다가 안 된 경로

안 쓴다 ❌

• 코드 (이건 git에)
• 변경 이력 자체 (이건 git log에)
• 시크릿/PII

셋의 연결

세 계층은 참조로 연결된다:

[code]
  # See ADR: decisions/2026-04-22-ingest.md
[commit]
  fix(...): ...
  See decisions/2026-04-22-ingest.md
[obsidian/decisions/2026-04-22-ingest.md]
  ## Status
  Accepted
  ## Context
  ...

코드를 보다가 → ADR로 → ADR이 어떤 커밋들에서 적용됐는지 추적 가능. 세 계층이 같은 왜 를 다른 깊이로 담는다.

LLM이 셋을 헷갈리는 패턴 3가지

LLM은 다음과 같이 자주 틀린다:

1. 모든 왜 를 코드 주석으로 — 코드가 구질구질해진다. ADR로 빼라.
2. 커밋 메시지에 한국어 맥락 통째로 — git log 가독성 떨어지고, 영문 검색 안 됨.
3. ADR을 현재 상태 묘사 로 — ADR은 결정 + 이유 + 결과, 사용 가이드 X.

명시적으로 분리해서 시켜야 한다:

• “지역적 왜 → 코드 주석”
• “변경된 이유 → 커밋 메시지”
• “결정과 그 영구적 결과 → ADR”

README — 4번째 계층?

엄밀히는 노트 의 일부지만, 위치가 다르다. README는 사용자가 처음 보는 문서:

• 한 줄 요약
• 빠른 시작 (5분 안에 돌아가게)
• 핵심 기능
• 환경변수 / 설정
• 트러블슈팅 / 라이선스

내부 결정 기록(ADR)은 README에 들어가지 않는다. README는 사용자, ADR은 기여자.

자동화 — 변경 가시성

LLM에게 다음을 자동으로 시켜 두면 문서 부채가 줄어든다:

• 사용자 가시 변경(섹션 4.5 — README 갱신 기준)이면 README 갱신 검토
• 의미 있는 결정이면 ADR 초안 생성
• 커밋 메시지에 ADR 참조 자동 삽입
• PR 본문에 노트 링크 첨부

자동화는 미루는 비용 을 즉시 비용 으로 바꾼다.

한 줄 요약

같은 왜 라도 어디에 쓰느냐로 가치가 바뀐다. 주석 / 커밋 / 노트 의 자리부터 합의하라.

다음 편: AI 활용법 13 — Tool 사용 전략 (검색/MCP/실행) 이전 편: AI 활용법 11 — 보안과 시크릿 관리