leave-the-why

name	leave-the-why
description	Leaves the WHY beside non-obvious decisions — in commit messages, PR descriptions, and short comments next to surprising code. Never writes ceremonial comments that restate the obvious WHAT; only surfaces the non-obvious reasoning that would otherwise be lost when the author moves on. 코드를 짠 사람의 머릿속에만 있는 *왜*를 코드 옆에 한 줄로 남기는 엔지니어링 철학 스킬.
when_to_use	Use when a non-obvious decision is being made, committed, or is about to be lost — typical moments include writing a commit message ("커밋할게", "commit message"), drafting a PR description ("PR 올릴게", "PR description"), encountering a workaround or hack, or answering questions like "이거 왜 이래?", "이상해 보이는데", "여기 주석 좀", "why is this here". Actively avoids docstrings on self-explanatory code; "fix bug" / "update" / "refactor" style messages are rewritten with the actual reason.
allowed-tools	Read Edit Bash(git *)

한 줄. 코드는 무엇을 하는지 말해주지만, 왜는 말해주지 않는다. 그 한 줄을 남긴다.

Why this mindset

진짜 프로그램은 코드가 아니라, 만든 사람 머릿속의 이해입니다 (Peter Naur, "Programming as Theory Building"). 그 이해를 남기지 않으면, 다음 사람 — 미래의 본인을 포함해서 — 은 같은 자리를 다시 헤맵니다. 무엇은 코드를 읽으면 알 수 있습니다. 하지만 왜는 그 자리에 없으면 영영 잃습니다. 그래서 우리가 남길 가치가 있는 단 한 가지는 왜입니다.

Instructions

모든 줄에 주석을 다는 게 아니다. 왜가 코드에서 안 보이는 자리에만, 한 줄 남긴다.

1. 커밋 메시지엔 무엇이 아니라 왜를 한 줄로. diff가 무엇이 바뀌었나는 이미 말해준다. 메시지가 할 일은 왜 바꿨나. "update component"·"fix bug"·"refactor" 같은 건 둘 다 안 말해주는 가장 약한 메시지다.

   • 약함: fix login bug
   • 강함: 로그인 시 토큰 만료 직전 race condition 방지 — 재발급 후 요청이 더 빨리 도착하던 케이스

2. 비자명한 결정 옆에만 왜 주석을. 자명한 코드 위엔 안 쓴다. 함수가 무엇을 하는지는 안 적는다 — 이름이 말해줘야 한다. 의례적 docstring("이 함수는 X를 한다")은 노이즈가 된다. 주석은 읽는 사람이 의아해할 자리에만.

3. 우회·hack·이상해 보이는 코드엔 반드시 이유. *"왜 이래?"*가 다음 사람의 첫 반응일 자리엔, 그 질문이 나오기 전에 답을 둔다. 한 줄이면 충분하다.

   • // iOS Safari가 첫 렌더 직전에 폰트 사이즈를 잘못 계산해서, 16px 이상으로 강제
   • 이 한 줄이, 6개월 뒤 누군가가 "쓸데없어 보여서" 지우는 일을 막는다.

4. 다음 사람은 미래의 본인이다. 본인이 한 달 뒤 자기 코드를 봤을 때 *"내가 왜 이렇게 했지?"*에 답이 있어야 한다. 코드는 짠 사람도 한 달이면 남이 된다. 미래의 자신에게 친절한 한 줄을 남긴다.

5. PR 설명은 결정의 맥락을 담는다. 어떤 옵션이 있었고, 왜 이걸 골랐는지. 코드만 보면 한 가지 정답처럼 보이지만, 거기엔 보통 고른 길과 고르지 않은 길이 있다. 후자를 한 줄 남기면 — 다음 사람이 같은 길을 다시 의심하느라 쓰는 시간을 줄여준다.

Examples

커밋 메시지 — 무엇이 아니라 왜:

• 약함: add caching
• 강함: 검색 결과 캐싱 추가 — 동일 키워드를 5분 내 재검색하는 사용자 패턴이 GA에서 30% 관찰됨

hack에 한 줄:

// Firefox는 input event를 paste 직후 두 번 발생시킴 (2024 기준).
// 100ms debounce로 중복 처리 방지. Firefox가 고치면 제거 가능.
const debounced = debounce(handleInput, 100);

의례적 주석은 안 씀:

// 안 씀 — 이름이 다 말해주는데 노이즈
// Validates an email address
function isValidEmail(email: string): boolean { ... }

PR 설명 — 고른 길과 안 고른 길:

"장바구니 동기화를 서버 단일 소스 방식으로 변경. 옵션이었던 클라이언트 마지막 쓰기 우선은, 다중 탭에서 충돌 빈도가 측정 단계에서 너무 높아 제외. 트레이드오프 — 오프라인 동기화는 일단 비활성. 추후 별도 이슈로."

Pitfalls

• 무엇만 적힌 커밋 메시지 (update, fix, refactor) → 6개월 뒤 누구도 왜를 모름
• 자명한 코드 위에 의례적 주석 → 노이즈만 늘고 진짜 왜는 묻힘
• 이상한 우회 코드를 설명 없이 남기기 → 다음 사람이 두려워서 못 만짐 / 모르고 지움
• "코드가 다 말해줘야지" 극단주의 — 왜는 코드가 절대로 말하지 않는다
• 주석을 너무 길게 → 다음 사람이 안 읽음. 한 줄이 정답
• 왜가 코드와 함께 갱신 안 됨 → 거짓말하는 주석. 코드가 바뀌면 왜도 같이.

코드는 결과물이고, 우리가 진짜 남기는 건 이해다. 그 이해를 다음 사람 손에 쥐어주는 한 줄이, 코드베이스를 유산이 아니라 길로 만든다.