개요
context-capture는 사용자가 직접 호출하지 않는 유일한 스킬입니다. Claude Code의 post-commit hook과 SKILL.md의 강제 호출 메시지 조합으로 커밋 직후 자동 활성화되며, 에이전트가 자신의 대화 컨텍스트를 분석해 요약을 만든 뒤 capture.js가 사용자 git repo의 aiflare/timeline/v1 orphan 브랜치 (entries/<commitHash>.json) 에 직접 기록합니다. 백엔드 전송은 git push 시점의 sync 트리거로 일원화됩니다.
캡처되는 정보
한 번의 커밋이 발생하면 아래 7개 필드가 한 건의 Timeline Entry로 묶여 저장됩니다.
| 필드 | 타입 | 설명 |
|---|---|---|
| title | string | 50자 이내의 작업 제목. 기본값은 git commit 메시지의 제목 줄. |
| intent | markdown | 왜 이 변경이 필요했는지 Problem → Solution → Effect 3단 구조로 작성. 6개월 뒤에도 결정의 맥락이 살아 있도록 작성하는 것이 원칙. |
| alternatives | markdown | 대화에 명시적으로 등장한 대안과 기각 이유만 기록. 신호가 없으면 빈 문자열로 둠 — 추측은 금지. |
| diffSummary | markdown | 변경된 파일별 핵심 변경 사항 요약. import 정리·포맷팅 등 부수 변경은 제외. |
| tag | enum | FEATURE · BUGFIX · REFACTORING · TEST · DOCS 중 하나. 대시보드에서 변경 종류별 필터링에 사용. |
| changedFiles | string[] | git diff --name-only HEAD~1 HEAD 결과를 그대로 사용한 변경 파일 목록. |
| conversationSnippet | jsonl | 마지막 캡처 이후의 사용자·AI 대화 JSONL. 줄 수(메시지 인덱스) 기반 delta로 추출되어 Entry와 함께 저장됨. |
작동 흐름
Hook → Skill → 서버 → 그룹핑 → push까지 7단계 파이프라인으로 동작합니다. 사용자가 별도로 호출할 필요는 없습니다.
세션 시작 시 $CLAUDE_ENV_FILE에 CLAUDE_SESSION_ID를 export. 병렬 세션 환경에서도 capture.js가 자신이 속한 세션을 결정적으로 식별할 수 있게 합니다.
사용자 프롬프트와 AI 응답을 .claude-prompts-{SESSION_ID} 파일에 JSONL 한 줄씩 누적합니다.
AskUserQuestion 직후 .pending-question 플래그 파일을 생성합니다. 다음 커밋의 continuation 신호로 사용되어 그룹핑이 끊기지 않게 합니다.
git commit 직후 ① 전체 대화 JSONL을 PUT /work-sessions/prompt로 전송, ② 이전 캡처 이후의 새 줄만 추출해 delta 파일로 저장, ③ Skill 호출 강제 메시지 출력.
에이전트가 자신의 컨텍스트를 분석해 title/intent/alternatives/diffSummary/tag를 생성하고 capture.js를 실행합니다. delta 파일을 자동으로 읽어 conversationSnippet으로 첨부합니다. 백엔드 전송은 없습니다 — 본문은 다음 단계에서 git tree에 직접 기록됩니다.
capture.js가 본문을 entries/<commitHash>.json 으로 aiflare/timeline/v1 orphan 브랜치에 기록합니다. 이 시점에는 백엔드 호출이 없으며 (오프라인에서도 동작), 그룹핑(group_root_id) 판정은 다음 push 시점의 백엔드 sync에서 수행됩니다.
pre-push hook이 aiflare/timeline/v1 브랜치도 사용자 git remote에 함께 push(force-with-lease) 한 뒤 sync-captures.js가 POST /api/v1/captures/sync (body 없음) 를 호출합니다. 백엔드는 등록된 git remote credential로 표준 git protocol을 통해 timeline 브랜치를 fetch → DB 메타 reconcile + group_root_id 판정 (직전 entry · continuation 플래그 기반) 을 수행합니다. POST /captures 와 POST /captures/batch 는 Phase 6에서 410 Gone으로 영구 제거됐습니다.
다른 스킬과의 관계
context-capture가 만들어낸 Timeline Entry와 EntryConversation은 다음 스킬들이 직접 소비합니다. 이 스킬이 동작하지 않으면 나머지 모든 스킬의 입력이 사라집니다.
캡처된 intent·alternatives를 git log -L의 줄 단위로 묶어 「이 한 줄이 왜 이렇게 작성됐는지」 시간순 타임라인을 만듭니다.
한 세션의 캡처들을 모아 목표·검토한 대안·최종 변경을 한 페이지 보고서로 정리해 서버에 저장합니다.
summarize로 저장한 보고서를 새 세션의 LLM 컨텍스트에 다시 주입해 결정 맥락을 인계합니다.
하루 분 캡처를 모아 커밋·세션·태그 분포와 주요 결정을 Markdown 리포트로 자동 정리합니다.
한 주 분 캡처를 멤버별·영역별로 집계해 팀 관점의 주간 보고서를 만듭니다.
두 세션의 캡처를 의도·접근·결과 측면에서 나란히 대조 분석합니다.
캡처된 사용자 프롬프트를 Claude Code 모범사례 기준으로 자동 평가하고 개선안을 제시합니다.
트러블슈팅
캡처가 동작하지 않을 때 가장 흔한 원인 5가지입니다.