workhistory/PROJECT_ANALYSIS.md

workhistory 프로젝트 분석

생성일: 2026-04-09 대상 브랜치: main

1. 개요

workhistory는 개인 작업 이력·메모 저장소이자, Claude Code 훅(Aptabase 토큰 기록) 테스트베드로 운영되는 git 저장소다. 프로덕션 코드는 없고, 저장소 자체가 .claude/ 하위 훅 구성을 검증하기 위한 샌드박스다.

• 위치: .
• 최근 커밋: 68d4012 docs: add project analysis and hooks documentation
• 주요 산출물: .claude/hooks/token-usage/ 의 Aptabase 연동 훅

2. 디렉터리 구조 (현재 상태)

workhistory/
├── README.md                          # 저장소 목적 요약
├── SKILLS.md                          # (참고용) 과거 skills 문서 — 현재 skills 디렉터리는 없음
├── claude-common-installer(4).exe     # 공통 설정 설치 바이너리 (~12MB)
├── .claude/
│   ├── settings.json                  # UserPromptSubmit / Stop / PostToolUse(Bash) 훅 등록
│   └── hooks/
│       └── token-usage/
│           ├── aptabase.json          # app_key, host, user_name, git_repositories
│           └── claude-hook.exe        # 단일 바이너리 (Go/Rust 추정, ~27KB)
└── .usage/
    └── token/
        ├── .gitignore
        ├── job-commit-pool.json       # commit-pool 대기 레코드 (현재 빈 배열)
        └── job-send-pool.json         # send-pool 대기 레코드 (현재 빈 배열)

이전 커밋(68d4012)의 분석 문서에서 언급된 .ps1 / .sh / aptabase-accumulate.* 스크립트 구조는 더 이상 존재하지 않는다. 현재는 모든 훅 로직이 단일 바이너리 claude-hook.exe 로 통합되었다.

3. 핵심 기능 — Aptabase 토큰 기록 훅 (v2: 단일 바이너리)

3.1 목적

Claude Code 세션 토큰 사용량을 git 커밋 단위로 묶어 self-hosted Aptabase(https://aptabase.hmac.kr)로 전송. 커밋 해시·메시지·이슈 번호·사용자 식별자와 함께 input/output/cache 토큰을 claude_commit 이벤트로 기록한다.

3.2 훅 파이프라인 (settings.json)

이벤트	서브커맨드	역할
UserPromptSubmit	claude-hook.exe session-context	세션/프롬프트 컨텍스트 기록 (stdin JSON 수신)
Stop	claude-hook.exe stop-record	응답 종료 시 토큰 누적 기록
PostToolUse (matcher: Bash)	claude-hook.exe aptabase-commit	Bash 툴 호출 후 HEAD 해시 변화 감지 → Aptabase 전송

공통 패턴: stdin JSON 을 임시 파일로 받아 바이너리에 경로 인자로 넘김. [ -x "$e" ] 로 존재 확인 후 실행, 사용 뒤 임시 파일 정리. 타임아웃은 5s(경량) / 15s(네트워크 전송).

3.3 상태 저장소 — .usage/token/

• job-commit-pool.json — commit 감지 시점의 누적 레코드 풀
• job-send-pool.json — Aptabase 전송 대기 풀
• 둘 다 현재 [] 로 비어 있음 → 직전 flush 이후 신규 활동 없음 상태

과거 .claude/state/aptabase-accum.json 단일 파일 구조에서, commit-pool / send-pool 이원화 구조로 진화했다. 커밋 감지와 전송 단계를 분리해 네트워크 실패 시 재시도가 용이하다.

3.4 설정값 (aptabase.json)

• enabled: true
• app_key: A-SH-7756143445 ⚠️ (self-hosted 키지만 평문 커밋됨)
• aptabase_host: https://aptabase.hmac.kr
• user_name: 김민성(b16213)
• git_repositories: ["D:/MYCLAUDE_PROJECT/workhistory"]

4. 전송 이벤트 스키마 (claude_commit, 추정)

바이너리 내부 구현은 직접 읽을 수 없으나, 이전 버전 / 문서 기반으로 다음 필드가 유지되는 것으로 보인다:

• 식별: claude_oauth_id, plan, user_name, local_ip, public_ip
• 커밋: commit_hash, commit_message, issue_number, repository, repository_url
• 토큰: total_tokens, input_tokens, cache_creation_tokens, cache_read_tokens, output_tokens

이슈 번호 regex: FEAT-123, BUG-45, closes #45, GH-8, #123 등 (히스토리의 9357d85 FEAT-999 커밋에서 추출 로직 검증).

5. 변경점 — 이전 버전 대비

이전 커밋(68d4012)의 PROJECT_ANALYSIS.md 대비 달라진 부분:

항목	v1 (이전)	v2 (현재)
훅 구현체	.ps1 + .sh 스크립트 다중 파일	claude-hook.exe 단일 바이너리
설정 위치	.claude/hooks/aptabase.json	.claude/hooks/token-usage/aptabase.json
상태 파일	.claude/state/aptabase-accum.json	.usage/token/job-commit-pool.json, job-send-pool.json
훅 이벤트	Stop + PostToolUse(Bash) + post-commit	UserPromptSubmit + Stop + PostToolUse(Bash)
skills	.claude/skills/aptabase/ 존재	제거됨 (SKILLS.md 문서만 잔존)
git post-commit 훅	install-git-hook.sh 로 수동 설치	현재 .git/hooks/post-commit 없음 — PostToolUse 만으로 커버
HOOKS.md / PROJECT_ANALYSIS.md	존재	working tree 에서 삭제됨 (git status: D)
test-aptabase.txt	존재	삭제됨

방향성은 명확하다: 스크립트 난립 → 단일 바이너리 통합, 단일 상태 파일 → pool 기반 파이프라인, 사람 참조용 skills/docs → 코드 중심 으로 수렴 중.

6. 리스크 및 관찰

1. app_key 평문 커밋 — self-hosted 라 영향은 제한적이나, 공개 전환 시 gitignore/환경변수 분리 필요.
2. 바이너리 불투명성 — claude-hook.exe 소스가 이 저장소에 없음. 동작 검증을 위한 소스/빌드 스크립트 위치를 README 에 링크할 필요.
3. 대용량 바이너리 커밋 — claude-common-installer(4).exe (~12MB) 가 저장소에 포함. Git LFS 또는 외부 배포 권장.
4. 문서 ↔ 실체 불일치 — SKILLS.md 는 .claude/skills/aptabase/ 를 전제로 하지만 해당 디렉터리는 존재하지 않는다. 문서 갱신 또는 삭제 필요.
5. working tree 의 삭제 상태 — HOOKS.md, PROJECT_ANALYSIS.md, test-aptabase.txt 가 git 에선 tracked 이지만 working tree 에선 삭제됨. 커밋으로 정리되지 않은 중간 상태.
6. .git/hooks/post-commit 부재 — Claude 밖에서 발생한 커밋은 기록되지 않을 수 있음. PostToolUse(Bash) 만으로 커버 가능한지 확인 필요.

7. 커밋 히스토리 (최근 5)

68d4012 docs: add project analysis and hooks documentation
e09c019 test: empty test commit
a6e9e49 docs: flesh out README with repo purpose and structure
9357d85 test: aptabase flush dry-run (FEAT-999)
07660b9 test: empty test commit

대부분 훅 파이프라인 E2E 검증용 empty/dry-run 커밋. 9357d85 에서 이슈 번호 추출까지 실제 flush 검증 완료.

8. 요약

workhistory 는 "Claude Code 토큰 사용량을 git 커밋 단위로 self-hosted Aptabase 에 자동 기록하는 훅 시스템"의 개인 실험장이다. v1 의 PowerShell/Bash 스크립트 묶음에서 v2 의 claude-hook.exe 단일 바이너리 + commit/send pool 이원화 구조로 진화했으며, 나머지 파일(README, installer, empty 커밋들)은 모두 그 훅 검증을 위한 스캐폴딩이다.