changelog

name	changelog
description	되돌릴 수 없는 결정과 그 근거를 시간순으로 changelog/changelog.md에 기록한다. 아키텍처·의존성·API 계약 변경 시 사용. push/PR 직전 changelog-reminder 훅이 매니페스트 변경을 감지하면 이 스킬로 기록할지 검토한다.

changelog (결정 기록)

결정·근거·대안·영향을 append-only로 changelog/changelog.md에 기록한다. 코드가 "무엇을" 하는지는 git이 안다. 여기 적는 건 "왜 이 선택인가" — 되돌리기 어렵고 근거가 시간이 지나면 잊히는 것들이다.

무엇을 기록하나

• 아키텍처 결정: 모듈 경계, 데이터 흐름, 동기/비동기, 저장소 선택.
• 의존성: 라이브러리 추가/교체/제거, 메이저 버전업, 그 이유와 탈락한 대안.
• API 계약: 공개 인터페이스·스키마·이벤트 포맷 변경(하위호환 깨짐 여부 명시).

일상적 버그픽스·리팩터·문서 수정은 기록하지 않는다. 되돌리기 비용이 크거나 나중 사람이 "왜 이렇게 했지?" 물을 것만.

항목 형식

changelog/changelog.md 상단에 최신이 오도록 prepend (또는 하단 append — 프로젝트 규칙 따름). 각 항목:

## <YYYY-MM-DD> — <결정 한 줄>
- **결정**: 무엇을 정했나
- **이유**: 왜 (핵심 근거)
- **대안**: 검토했다 버린 선택 + 버린 이유
- **영향**: 무엇이 바뀌나 / 깨지나 (하위호환·마이그레이션)

• 짧게. 각 줄 한두 문장. 근거 없는 결정은 기록할 가치가 없다.
• append-only: 과거 항목을 고쳐 쓰지 않는다. 결정이 뒤집히면 새 항목으로 "X를 Y로 되돌림, 이유:"를 추가한다.

훅과의 관계

.claude/hooks/changelog-reminder.py(PreToolUse 훅)가 git push/gh pr create 직전, 이번에 나갈 커밋에 의존성·빌드 매니페스트(package.json·go.mod·Cargo.toml·pom.xml 등) 변경이 있는데 changelog/changelog.md 갱신이 없으면 비차단 리마인더를 남긴다. 그때 이 스킬로 기록할지 사용자에게 물어라. push를 막지는 않는다.

프로젝트별 기록 규칙은 이 아래에 추가한다 (예: ADR 번호 체계, 승인자 명시, 관련 PR 링크).