개요
커밋 메시지는 「무엇이 바뀌었는지」만 남기지만, why tool은 그 뒤의 의도·기각한 대안·당시 대화를 커밋별로 반환합니다. 로컬에서 `git log -L` 을 실행해 대상 줄(또는 파일)을 만진 커밋 해시를 찾고, 각 커밋의 AIFlare 캡처를 조회해 최신 커밋이 위쪽인 타임라인으로 묶어 줍니다. 캡처가 없는 커밋은 fallback 으로 커밋 목록만 안내합니다.
언제 쓰나
AI 가 만든 코드를 손대기 전에 원래 의도를 먼저 확인하고, 추측 대신 근거 위에서 디버깅·리팩터링하기 위한 도구입니다.
이상하게 보이는 한 줄이 왜 그렇게 작성되었는지 — 의도된 워크어라운드인지, 단순 실수인지 — 를 커밋의 의도와 대안 기록으로 판별합니다.
건드리려는 코드가 어떤 제약·트레이드오프 위에서 결정되었는지 확인한 뒤 안전하게 구조를 바꿉니다.
내가 만들지 않은 모듈의 한 줄이 어떤 흐름에서 등장했는지를 커밋별 대화 조각과 함께 따라갑니다.
AI 에이전트가 디버깅 중 추측으로 코드를 수정하기 전에 why 를 호출해 자기 또는 다른 에이전트의 과거 의도를 먼저 확인합니다.
사용법
구문
Claude Code 의 슬래시 커맨드로 직접 호출하거나, AI 가 도구를 통해 호출합니다. 파일 경로 뒤에 콜론과 줄 번호를 붙이면 그 줄만 추적합니다.
/why <file>[:<line>]파라미터
| 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
| file | string | 필수 | - | 조회 대상 파일 경로 (git 루트 기준 상대 경로 또는 절대 경로). |
| line | number | 선택 | - | 설명할 줄 번호. 생략 시 파일 전체 이력을 사용합니다 (어느 모드든 최신 5개 커밋 cap). |
처리 흐름
주요 에러
`aiflare.yml` 이 없거나 `api_key` 가 비어 있을 때. 「AIFlare is not configured. Place aiflare.yml in your project root.」 메시지를 반환합니다.
git 루트를 찾지 못할 때. 「Not in a git repository.」 메시지를 반환합니다.
파일이 존재하지 않거나 줄 번호가 범위를 벗어났을 때. 「git query failed — check the file path …」 안내를 반환합니다.
출력 형식
Markdown 문자열로 반환됩니다. 캡처가 있는 경우와 없는 경우 두 가지 모양이 있습니다.
각 커밋이 카드 형태로 묶여 「Title / Tag / Intent / Alternatives considered / Diff around this line / Conversation behind this commit」 섹션이 차례로 표시됩니다. 가장 최근 커밋이 위쪽이며, 캡처가 1개뿐일 때는 'only', 그 외에는 'latest / earlier / oldest' 레이블이 붙습니다.
커밋 이력은 있지만 AIFlare 캡처가 하나도 없을 때 사용됩니다. 「N commits touched this line, but none are captured in AIFlare.」 안내와 함께 커밋 해시·날짜·subject 목록만 보여 줍니다. (AIFlare 도입 전 또는 Claude Code 외부 커밋)
총 커밋이 5개를 초과하면 타임라인에는 「Showing the 5 most recent of N commits.」, fallback 에는 「Checked the 5 most recent of N commits, but none are captured in AIFlare.」 안내가 추가됩니다.
에러·예외 처리
모든 에러는 Claude Code 세션을 중단시키지 않고 tool 응답 텍스트로 반환됩니다. AI 는 안내 문구를 보고 일반 디버깅으로 자연스럽게 이어갑니다.
| 상황 | 반환 문구 |
|---|---|
| AIFlare 미설정 | AIFlare is not configured. Place aiflare.yml in your project root. |
| git 리포지토리 아님 | Not in a git repository. |
| git log 실패 (경로·줄 번호 오류) | git query failed — check the file path … |
| 커밋 이력 없음 | No commit history found for {file}:{line}. (또는 …for {file}.) |
| 백엔드 타임아웃·네트워크 오류 | Error querying AIFlare: {message} |
| 특정 커밋의 git show 실패 | 그 커밋의 diff 섹션만 생략하고 나머지 타임라인은 정상 출력합니다. |