Method

1. 기본값으로 놓치지 않음. commit hook에 positive trigger 레이어. commit이 200 LOC 초과, 민감 경로 touch, 또는 architecture-flavored 키워드 포함이면 [no-log] tag를 override함. 작성자 판단이 약 30% 정도 미끄러지는데 — 시스템이 잡아냄.
2. AI 작성 + 사람 주석. 모든 AI 작성 log entry 옆에 .human.mdx 슬롯이 나란히 렌더링됨. 빈 슬롯은 “REVIEW NEEDED”로 표시 — 부재가 *눈에 보임*, 침묵 아님.
3. 크로스 레포 aggregation. 5개 프로젝트 (이 hub + 4개 satellite)가 한 portfolio timeline으로 모임. pull-on-demand 방식 — sync 없음, 두 번째 source of truth 없음.
4. Tier별 결정 기록. 무게별로 templates: Tier 1 substantial → 8 슬롯 MBA-grade template, Tier 2 notable → 6 슬롯, Tier 3 trivial → 템플릿 없음. 추가로 learning-gap kind — 내가 *처음에 모르던 것*을 기록. 대부분 시스템이 빠뜨리는 성장 artifact.

검증된 framework에서 가져옴. 새 슬롯을 만든 게 아니라 실제 조직에서 load-bearing이었던 것들 활용.

• Tier 1 — substantial (architecture / vendor / monetization / security / data model / major refactor)

  8 슬롯: Context & constraints · Goals 우선순위 · Options considered (≥3, “do nothing” 포함) 각각 Cost/Reversibility/Risk/Evidence · Trade-off accepted · Pre-mortem (6개월 뒤 실패 시나리오 3개) · Decision criteria to flip · Success measure · Reversal plan.

  작성 시간: 20–30분 (제대로 할 때). 목표: 월 3–5개.

• Tier 2 — notable (feature 방향 / UX 결정 / dependency upgrade)

  6 슬롯: Context · Options considered (≥2) · Chosen + Why · Trade-off · Reversibility · Verified by. ~5–10분.

• Tier 3 — trivial (rename / lint / formatting / 동작 변경 없는 dep bump)

  결정 entry 없음. 그냥 commit.

세 가지 log kind가 AI 엔지니어의 차별 신호를 운반:

decision

option weighing 순간의 ADR-style 기록. Tiered. reversibility 필드는 Bezos two-way / one-way door framing.

discussion

옵션을 surface한 대화 — claude.ai와, 사람과, 또는 brainstorm. 내가 AI의 default suggestion을 어디서 거절했는지 기록.

learning-gap

처음에 이해 못 했던 것, 그 gap이 어디서 왔는지, 무엇이 click했는지, 아직 헷갈리는 게 무엇인지. wiki entry와 짝지어 mental model의 성장을 시간 흐름에 따라 추적.

hook 스크립트, install kit, CLAUDE.md snippet 모두 공개. 한 줄 install로 dual-write 컨벤션 + positive-trigger hook이 어떤 git repo에든 적용됨.

시스템을 *지어가며* 동시에 기록. 아래 post는 실제 순서 — 뭘 시도했고 뭐가 깨졌고 뭐가 출하됐는지.

• Michael Nygard, Documenting Architecture Decisions, 2011 — ADR 패턴.
• Jeff Bezos, 1997 shareholder letter — reversibility용 two-way / one-way door framing.
• Gary Klein, “Performing a Project Premortem,” Harvard Business Review, 2007.
• Atlassian DACI — decision-roles framework (솔로 작업엔 lightweight 형태).
• Andy Grove, High Output Management, 1983 — 구조화된 정보 capture가 관리 leverage.
• Salvatore Sanfilippo (antirez) — high-signal 개인 엔지니어링 글쓰기 devlog 전통.
• Obsidian / Logseq — linked atomic notes ([[wiki-link]] syntax 가져옴).

• CMS 아님. Log는 MDX 파일, 렌더링 레이어는 그냥 읽음.
• Sync 시스템 아님. hub가 satellite log를 *pull on demand*; 두 번째 source of truth 없음.
• 관료주의 아님. Tier 3는 “그냥 commit, entry 없음” — 대부분 commit이 여기 머물름.
• 코드 리뷰 대체 아님. 추론을 기록하지, 평가하지는 않음.