Post-mortem과 history 로그 습관

두 종류 기록, 두 목적

프로덕션 작업이 두 종류 기록 생성 — commits(뭐 변경)와 history entry(왜와 뭐 배움). Commits가 '오늘 코드 뭐 함' 답. History가 '이거 알았으면 뭐 다르게 했을까' 답. 두 번째 skip하면 매 regression이 fresh discovery.

History entry에 뭐 들어가

cwkPippa history convention — significant task당 Markdown 파일 history/YYYY-MM-DD-task.md. 콘텐츠 — 뭐 했는지, 왜(트리거 link — incident, request, observation), key tradeoff와 결정, 만진 파일, 발견한 gotcha, 그리고 'future-me가 git log에서 못 받을 컨텍스트' 한 단락. 포인트는 변경 X, intent.

Post-mortem subset

프로덕션에서 뭐 깨졌으면 history entry가 post-mortem 됨 — timeline, root cause, blast radius, recovery에 뭐 동작, 더 일찍 잡았을 거 뭐. Blameless하고 specific. cwkPippa history 폴더에 JSONL fragmentation 사고, at-rest 암호화 rollout, streaming-cancel 버그 — 다음 운영자에 durable 교훈.

원칙: Commits가 뭐 답. History가 왜 답. 운영에 둘 다 필수; 두 번째가 compound.

Code

History entry 템플릿·markdown

# 2026-04-28 — JSONL Fragmentation Fix

## What happened

한 단락 — user가 본 증상, 언제 시작, 어떻게 감지.

## Root cause

실제로 뭐 깨짐(commit, function, config link). Specific.

## Recovery

Back 가져온 단계. 먼저 시도한 거 vs 먼저 동작한 거.

## Lesson

미래 내가 알았으면 좋았을 한두 문장. Non-obvious 부분.

## Files

- backend/store/sessions.py
- backend/services/healing.py

Runbook의 post-mortem one-liner·markdown

## Streaming cancel 버그 (2026-03-15)

`__anext__()` 주변 `asyncio.wait_for`가 async generator cancel(Python 스펙).
긴 tool 호출 동안 SSE 죽임. Fix — HTTP-레벨 timeout만; streaming iterator에
wait_for 절대 X. history/2026-03-15-stream-cancel.md 참고.

Exercise

지난 달의 significant 프로덕션 task 하나 픽. History entry 작성 — 뭐, 왜, key 결정, 교훈. Repo의 history 폴더에 commit. 앞으로 매 significant task에 이렇게 할 계획.

Hint

'history 폴더 없어'면 mkdir이 첫 commit. Future you가 today you의 polish보다 습관 더 필요.

Post-mortem과 history 로그 습관

두 종류 기록, 두 목적

History entry에 뭐 들어가

Post-mortem subset

Code

External links

Exercise

Progress

댓글 0