커밋은 무엇을, 운영 기록은 왜를 남겨

두 기록은 서로 다른 질문에 답해

커밋은 코드가 어떻게 바뀌었는지 보여 주고, 이력 항목은 왜 바꿨으며 무엇을 배웠는지 설명해. 둘째를 생략하면 비슷한 회귀가 올 때마다 같은 사실을 새로 발견하게 돼. 운영 지식은 변경 내역만으로 복원되지 않아.

미래의 운영자에게 판단 근거를 건네

cwkPippa는 중요한 작업마다 history/YYYY-MM-DD-task.md에 촉발한 사건이나 요청, 핵심 절충과 결정, 만진 파일, 발견한 함정, Git 로그만으로 알 수 없는 맥락을 남겨. 변경 목록보다 당시 의도를 보존하는 게 목적이야.

장애가 있었다면 사후 분석으로 넓혀

시간순 사건, 근본 원인, 피해 범위, 복구에 효과가 있었던 조치, 더 일찍 잡을 신호를 구체적으로 적어. 비난은 빼고 사실은 흐리지 마. cwkPippa의 JSONL 파편화, 저장 암호화 전환, 스트리밍 취소 오류 기록이 다음 운영자의 재발 방지 자료가 돼.

원칙: 커밋은 무엇을 바꿨는지, 운영 기록은 왜 그랬는지 답해. 둘이 함께 있어야 배움이 쌓여.

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

지난달의 중요한 운영 작업 하나를 골라 무엇을·왜·어떤 결정을 했고 무엇을 배웠는지 이력 항목으로 작성해 저장소에 커밋해.

Hint

이력 폴더가 없다면 만드는 첫 커밋부터 시작해. 미래의 자신에게는 문장 광택보다 꾸준한 기록이 더 유용해.

두 기록은 서로 다른 질문에 답해

미래의 운영자에게 판단 근거를 건네

장애가 있었다면 사후 분석으로 넓혀

Code

External links

Exercise

Progress

댓글 0