Files

minsung 68d4012f11 docs: add project analysis and hooks documentation

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-04-08 11:25:46 +09:00

5.9 KiB

Raw Blame History

workhistory 프로젝트 분석

생성일: 2026-04-08

1. 개요

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

위치: d:/MYCLAUDE_PROJECT/workhistory
원격 저장소: (로컬 전용 추정)
현재 브랜치: main
최근 커밋: e09c019 test: empty test commit

2. 디렉터리 구조

workhistory/
├── README.md                         # 저장소 목적 요약
├── test-aptabase.txt                 # 훅 테스트용 더미
├── claude-common-installer(3).exe    # 공통 설정 설치 바이너리 (12MB)
├── .claude/
│   ├── settings.json                 # Stop / PostToolUse(Bash) 훅 등록
│   ├── hooks/
│   │   ├── aptabase.json             # app_key, host, user_name
│   │   ├── aptabase-accumulate.{sh,ps1}   # 응답 종료 시 토큰 누적
│   │   ├── aptabase-commit.{sh,ps1}       # 커밋 감지 → Aptabase flush
│   │   ├── install-git-hook.sh       # .git/hooks/post-commit 설치
│   │   └── usage.md                  # 상세 사용 문서
│   ├── skills/aptabase/SKILL.md      # 슬래시 스킬 정의
│   └── state/
│       ├── .gitignore
│       └── aptabase-accum.json       # 누적 상태 (자동 생성)
└── memory/                           # 장기 메모리 저장소 (README 기준)

참고: usage.md에 언급된 aptabase_common.py, aptabase-*.py 파이썬 구현은 실제 디렉터리에는 없고, .sh / .ps1 진입점만 존재한다. Windows 환경이라 PowerShell 경로가 실제 실행된다.

3. 핵심 기능 — Aptabase 토큰 기록 훅

3.1 목적

Claude Code 세션에서 발생한 응답 토큰을 git 커밋 단위로 묶어 자체 호스팅 Aptabase(https://aptabase.hmac.kr)로 전송. 커밋 메시지·이슈 번호·사용자 식별자와 함께 누적 토큰(input/output/cache)을 이벤트(claude_commit)로 기록한다.

3.2 훅 파이프라인

트리거	훅 이벤트	스크립트	역할
Claude 응답 완료	`Stop`	`aptabase-accumulate.ps1`	트랜스크립트 JSONL 증분 파싱 → `state.accum` 누적 (네트워크 없음)
Claude의 `Bash` 툴 호출 후	`PostToolUse(Bash)`	`aptabase-commit.ps1`	HEAD 해시 변화 감지 시 Aptabase POST 후 리셋
모든 git 커밋 (외부 포함)	`.git/hooks/post-commit`	`aptabase-commit.sh`	Claude 밖 커밋도 포착 (clone 시 재설치 필요)

중복 전송은 last_sent_commit 해시 비교로 방지.

3.3 settings.json 등록 방식 (settings.json)

PowerShell 인라인 래퍼로 stdin JSON을 받아 cwd 추출 → 프로젝트의 .ps1을 실행하는 구조. 이 방식 덕에 전역 설정 한 줄로 프로젝트별 훅이 동작한다.

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"]

3.5 현재 상태 (aptabase-accum.json)

누적 토큰 전부 0 (마지막 커밋에서 flush된 직후 상태)
last_sent_commit: e09c019… — HEAD와 일치 → 정상

4. 전송 이벤트 스키마 (`claude_commit`)

props 주요 필드:

식별: 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 등.

5. 슬래시 스킬

.claude/skills/aptabase/SKILL.md — "aptabase 설정/테스트/토큰 기록 확인/누적 토큰" 질의 시 자동 발동. 설치·검증·트러블슈팅 절차를 담은 사용자-facing 문서 역할.

6. 관찰 및 리스크

app_key 평문 커밋 — self-hosted 라 영향은 제한적이나, 외부 공개 저장소로 전환 시 반드시 gitignore 또는 환경변수로 분리 필요.
usage.md ↔ 실제 파일 불일치 — 문서는 .py 기반 구현을 전제로 하나, 실제는 .sh / .ps1 만 존재. 문서 갱신 또는 .py 복구 중 하나가 필요.
12MB 바이너리 커밋 — claude-common-installer(3).exe가 저장소에 포함됨. Git LFS 또는 별도 배포 채널 권장.
.git/hooks/post-commit 재설치 — clone 시마다 install-git-hook.sh 수동 실행 필요. 자동화 스크립트가 없음.
memory/ 디렉터리 — README에 명시되어 있으나 현재는 비어있음(또는 미생성). 전역 메모리는 C:\Users\nbright\.claude\projects\...\memory\ 쪽에 저장되는 것으로 보임.

7. 커밋 히스토리

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
e44877d Initial commit

대부분의 커밋이 훅 파이프라인 E2E 검증용 empty/dry-run 커밋이다. 9357d85에서 이슈 번호 추출 로직까지 실제 flush 검증을 마친 것으로 보인다.

8. 요약

이 저장소는 "Claude Code 사용량을 커밋 단위로 Aptabase에 자동 기록하는 훅 시스템"의 개인 실험장이다. 핵심 산출물은 .claude/hooks/의 Aptabase 연동 훅 묶음이며, 나머지(README, test 파일, empty 커밋)는 모두 그 훅의 동작을 검증하기 위한 스캐폴딩이다.

5.9 KiB Raw Blame History