# Leave The Why

> 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. 코드를 짠 사람의 머릿속에만 있는 *왜*를 코드 옆에 한 줄로 남기는 엔지니어링 철학 스킬.

- Skill: `kwakseongjae/leave-the-why` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kwakseongjae/leave-the-why`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kwakseongjae/leave-the-why/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kwakseongjae (https://skillmd.com/u/kwakseongjae)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kwakseongjae/leave-the-why

---


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

## 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에 한 줄:**
```ts
// Firefox는 input event를 paste 직후 두 번 발생시킴 (2024 기준).
// 100ms debounce로 중복 처리 방지. Firefox가 고치면 제거 가능.
const debounced = debounce(handleInput, 100);
```

**의례적 주석은 안 씀:**
```ts
// 안 씀 — 이름이 다 말해주는데 노이즈
// Validates an email address
function isValidEmail(email: string): boolean { ... }
```

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

## Pitfalls

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

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