adr-writer

name	adr-writer
description	대화 중 되돌리기 어려운 설계·아키텍처 결정이 확정되는 순간 자동으로 docs/adr/에 ADR을 기록한다. 라이브러리·프레임워크 채택/교체, 모듈 경계·레이어 구조 변경, 의도적으로 하지 않기로 한 것 등 "이걸로 하자"라고 결론이 나는 대화에서 사용. 사용자가 ADR을 써달라고 명시적으로 요청하지 않아도, 결정이 확정되는 시점에 먼저 제안한다.

adr-writer — 대화 중 자동 ADR 기록

이 Skill의 목적은 문서 자체가 아니라 미래 세션의 토큰 절감이다. 결정 당시의 맥락과 이유를 놓치지 않고 남겨서, 나중에 다른 세션(다른 사람 또는 다른 Claude 인스턴스)이 "왜 이렇게 했지?"를 처음부터 재조사·재논의하지 않게 한다.

입력 (트리거 조건 — 스킬 실행 시 판단 기준)

명시적 파라미터 없이, 대화 중 아래 신호가 확정되는 순간(제안·검토 단계가 아니라 결론이 난 시점) 자동으로 판단한다. 강도 순으로 4단계이며, 마지막 안티-트리거를 반드시 함께 확인한다.

1. AskUserQuestion 호출 — 가장 강한 트리거

AskUserQuestion 호출 그 자체가 "대안이 여러 개 있고 자명하지 않아 사람에게 물었다"는 신호다. 구조가 이미 ADR 재료와 대응한다: options → 고려한 대안, 각 option의 description → 트레이드오프, 사용자가 고른 답 → 결정, question → 맥락.

단, 아래를 모두 만족할 때만 ADR감이다:

• 선택이 코드 한 곳이 아니라 앞으로의 방향·제약에 영향을 준다 (예: "네비게이션을 Activity Launcher로 vs NavHost로")
• 되돌리려면 여러 파일 수정·재합의가 필요하다
• 파일명 A/B, 문구 확인처럼 일회성 확인은 제외한다

2. 대화 흐름에서의 의미 기준 트리거

AskUserQuestion 없이 자연어 대화 중에도 아래 신호가 나타나면 결정이 굳은 것으로 본다.

트리거	감지 신호 예시
기술 선택·교체	"X 라이브러리 쓰자", "Y 대신 Z로 바꾸자", 빌드·의존성 방향 결정
구조·경계 결정	모듈 분리, 레이어 규칙, 공개 표면 범위, 패키지 책임 재정의
배제 결정 (안 하기로 함)	"이 우회책은 쓰지 말자", "@OptIn 박지 말자"
명시적 트레이드오프	2개 이상 대안을 비교하고 하나를 이유와 함께 채택
컨벤션 신설·변경	네이밍·커밋·워크플로 규칙을 새로 정하거나 기존 규칙을 뒤집음
되돌리기 비용 큼	마이그레이션, 데이터·직렬화 포맷, 공개 API 시그니처
반복되는 논의	예전에 정한 걸 또 묻는 상황 → 기록해서 재논의 막기

3. 사용자 발화 기준 트리거 — 명시적 의도

아래와 같은 발화는 확신도가 높은 즉시 트리거다.

• "이건 기록해두자 / 남기자 / 나중에 헷갈릴 것 같다"
• "왜 이렇게 했는지 이유를 남겨야"
• "다음에 또 이 고민 하지 않게"

4. 안티-트리거 — 반드시 제외 (노이즈 방지)

자동화의 최대 위험은 사소한 걸 ADR로 남겨 인덱스를 오염시키는 것이다. 아래는 트리거 신호처럼 보여도 남기지 않는다.

• 순수 구현 세부 (변수명, 지역적 리팩터, 파일 위치)
• 이미 문서·컨벤션에 있는 규칙을 그대로 따른 것 (SSOT 재기록 금지)
• 일회성·임시 우회
• 버그 수정 그 자체 (단, "이 방식으로 고치기로 하고 다른 방식은 배제"처럼 정책성 결정이면 대상)

위 기준을 통과해도 애매하면 남기는 쪽보다 사용자에게 "이거 ADR로 남길까요?" 한 줄로 먼저 확인한다.

작업 순서

1. 같은 폴더의 adr-format.md를 먼저 Read해 파일명·상태 값·템플릿 형식을 확인한다. 이 Skill 안에서 형식을 재정의하지 않는다.
2. 대화 맥락에서 아래를 추출한다.
   • 컨텍스트: 이 결정이 필요했던 배경, 제약 조건
   • 결정: 무엇을 선택했는가
   • 근거: 결정 자체와 분리해, 그 결정을 뒷받침하는 이유·트레이드오프
   • 결과: 시스템에 미치는 영향, 후속 지침
   • 고려한 대안: 채택하지 않은 다른 선택지와 배제 이유
   • 작성일: 오늘 날짜
   • 작성자: 대화에서 알 수 없으므로 git config user.name 값으로 채운다
3. adr-format.md의 템플릿에 맞춰 새 ADR 파일을 작성한다. 상태는 기본 Accepted(사용자가 확정한 결정이므로) — 아직 논의 중이면 Proposed.
4. docs/adr/README.md 인덱스 표에 새 줄을 추가한다.
5. 이 결정이 기존 ADR을 대체하는 것이라면, adr-format.md의 상태 규칙에 따라 기존 ADR의 상태를 갱신한다(README 인덱스의 상태 셀도 함께).

작성 규칙

• 결정의 "왜"나 고려한 대안이 대화에 없으면 추측해서 채우지 않고, "다른 방법은 검토 안 하셨나요?" 식으로 사용자에게 먼저 확인한다. 특히 고려한 대안이 빠지면 다음 세션에서 이미 배제된 방법이 다시 제안·논의된다.
• 이미 같은 주제의 Accepted ADR이 있는데 이번 결정이 그걸 뒤집는 것이라면, 이건 adr-writer가 아니라 failure-writer의 영역일 수 있다 — 이전 결정이 "틀렸던" 것인지 단순히 "갱신"되는 것인지 구분해 판단한다.

산출물 핸드오프

• 산출물: 새 ADR 파일 + docs/adr/README.md 인덱스 갱신, 필요 시 대체된 기존 ADR의 상태 갱신.
• 생성/수정한 파일을 사용자에게 요약해 알린다.
• 커밋은 이 Skill의 범위가 아니다 — /done에서 다른 변경사항과 함께 처리한다.