kimminsung/workhistory
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

chore: update project docs and add local config

Browse Source 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
minsung
2026-04-09 09:08:35 +09:00
parent 68d4012f11
commit cb5efd591f
7 changed files with 266 additions and 401 deletions
Download Patch File Download Diff File Expand all files Collapse all files

121
PROJECT_ANALYSIS.md
View File

@@ -1,102 +1,115 @@
# workhistory 프로젝트 분석
생성일: 2026-04-08
생성일: 2026-04-09
대상 브랜치: `main`
## 1. 개요
`workhistory`는 개인 작업 이력·메모 저장소이자, **Claude Code 훅(Aptabase 토큰 기록) 테스트베드**로 운영되는 git 저장소다. 실제 "프로덕션 코드"는 없고, 저장소 자체가 `.claude/` 하위 훅/스킬 구성을 검증하기 위한 샌드박스다.
`workhistory`는 개인 작업 이력·메모 저장소이자, **Claude Code 훅(Aptabase 토큰 기록) 테스트베드**로 운영되는 git 저장소다. 프로덕션 코드는 없고, 저장소 자체가 `.claude/` 하위 훅 구성을 검증하기 위한 샌드박스다.
- 위치: [d:/MYCLAUDE_PROJECT/workhistory](.)
- 원격 저장소: (로컬 전용 추정)
- 현재 브랜치: `main`
- 최근 커밋: `e09c019 test: empty test commit`
- 위치: [.](.)
- 최근 커밋: `68d4012 docs: add project analysis and hooks documentation`
- 주요 산출물: `.claude/hooks/token-usage/` 의 Aptabase 연동 훅
## 2. 디렉터리 구조
## 2. 디렉터리 구조 (현재 상태)
```
workhistory/
├── README.md # 저장소 목적 요약
├── test-aptabase.txt # 훅 테스트용 더미
├── claude-common-installer(3).exe # 공통 설정 설치 바이너리 (12MB)
├── README.md # 저장소 목적 요약
├── SKILLS.md # (참고용) 과거 skills 문서 — 현재 skills 디렉터리는 없음
├── claude-common-installer(4).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 기준)
│ ├── 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 대기 레코드 (현재 빈 배열)
```
> 참고: [usage.md](.claude/hooks/usage.md)에 언급된 `aptabase_common.py`, `aptabase-*.py` 파이썬 구현은 실제 디렉터리에는 없고, `.sh` / `.ps1` 진입점만 존재한다. Windows 환경이라 PowerShell 경로가 실제 실행된다.
> 이전 커밋(`68d4012`)의 분석 문서에서 언급된 `.ps1` / `.sh` / `aptabase-accumulate.*` 스크립트 구조는 **더 이상 존재하지 않는다**. 현재는 모든 훅 로직이 **단일 바이너리 `claude-hook.exe`** 로 통합되었다.
## 3. 핵심 기능 — Aptabase 토큰 기록 훅
## 3. 핵심 기능 — Aptabase 토큰 기록 훅 (v2: 단일 바이너리)
### 3.1 목적
Claude Code 세션에서 발생한 응답 토큰을 **git 커밋 단위로** 묶어 자체 호스팅 Aptabase(`https://aptabase.hmac.kr`)로 전송. 커밋 메시지·이슈 번호·사용자 식별자와 함께 누적 토큰(input/output/cache)을 이벤트(`claude_commit`)로 기록한다.
Claude Code 세션 토큰 사용량을 **git 커밋 단위로** 묶어 self-hosted Aptabase(`https://aptabase.hmac.kr`)로 전송. 커밋 해시·메시지·이슈 번호·사용자 식별자와 함께 input/output/cache 토큰을 `claude_commit` 이벤트로 기록한다.
### 3.2 훅 파이프라인
### 3.2 훅 파이프라인 ([settings.json](.claude/settings.json))
| 트리거 | 훅 이벤트 | 스크립트 | 역할 |
|---|---|---|---|
| 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 시 재설치 필요) |
| 이벤트 | 서브커맨드 | 역할 |
|---|---|---|
| `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 전송 |
중복 전송은 `last_sent_commit` 해시 비교로 방지.
공통 패턴: stdin JSON 을 임시 파일로 받아 바이너리에 경로 인자로 넘김. `[ -x "$e" ]` 로 존재 확인 후 실행, 사용 뒤 임시 파일 정리. 타임아웃은 5s(경량) / 15s(네트워크 전송).
### 3.3 settings.json 등록 방식 ([settings.json](.claude/settings.json))
PowerShell 인라인 래퍼로 stdin JSON을 받아 `cwd` 추출 → 프로젝트의 `.ps1`을 실행하는 구조. 이 방식 덕에 전역 설정 한 줄로 프로젝트별 훅이 동작한다.
### 3.3 상태 저장소 — [.usage/token/](.usage/token/)
- `job-commit-pool.json` — commit 감지 시점의 누적 레코드 풀
- `job-send-pool.json` — Aptabase 전송 대기 풀
- 둘 다 현재 `[]` 로 비어 있음 → 직전 flush 이후 신규 활동 없음 상태
### 3.4 현재 설정값 ([aptabase.json](.claude/hooks/aptabase.json))
> 과거 `.claude/state/aptabase-accum.json` 단일 파일 구조에서, **commit-pool / send-pool 이원화** 구조로 진화했다. 커밋 감지와 전송 단계를 분리해 네트워크 실패 시 재시도가 용이하다.
### 3.4 설정값 ([aptabase.json](.claude/hooks/token-usage/aptabase.json))
- `enabled: true`
- `app_key: A-SH-7756143445` ⚠️ (self-hosted 키지만 평문 커밋 주의)
- `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](.claude/state/aptabase-accum.json))
- 누적 토큰 전부 0 (마지막 커밋에서 flush된 직후 상태)
- `last_sent_commit: e09c019…` — HEAD와 일치 → 정상
## 4. 전송 이벤트 스키마 (`claude_commit`, 추정)
## 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` 등.
이슈 번호 regex: `FEAT-123`, `BUG-45`, `closes #45`, `GH-8`, `#123` 등 (히스토리의 `9357d85 FEAT-999` 커밋에서 추출 로직 검증).
## 5. 슬래시 스킬
## 5. 변경점 — 이전 버전 대비
[.claude/skills/aptabase/SKILL.md](.claude/skills/aptabase/SKILL.md) — "aptabase 설정/테스트/토큰 기록 확인/누적 토큰" 질의 시 자동 발동. 설치·검증·트러블슈팅 절차를 담은 사용자-facing 문서 역할.
이전 커밋(`68d4012`)의 [PROJECT_ANALYSIS.md](https://git) 대비 달라진 부분:
## 6. 관찰 및 리스크
| 항목 | 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 | 존재 | **삭제됨** |
1. **`app_key` 평문 커밋** — self-hosted 라 영향은 제한적이나, 외부 공개 저장소로 전환 시 반드시 gitignore 또는 환경변수로 분리 필요.
2. **`usage.md` ↔ 실제 파일 불일치** — 문서는 `.py` 기반 구현을 전제로 하나, 실제는 `.sh` / `.ps1` 만 존재. 문서 갱신 또는 `.py` 복구 중 하나가 필요.
3. **12MB 바이너리 커밋** — `claude-common-installer(3).exe`가 저장소에 포함됨. Git LFS 또는 별도 배포 채널 권장.
4. **`.git/hooks/post-commit` 재설치** — clone 시마다 `install-git-hook.sh` 수동 실행 필요. 자동화 스크립트가 없음.
5. **`memory/` 디렉터리** — README에 명시되어 있으나 현재는 비어있음(또는 미생성). 전역 메모리는 `C:\Users\nbright\.claude\projects\...\memory\` 쪽에 저장되는 것으로 보임.
방향성은 명확하다: **스크립트 난립 → 단일 바이너리 통합**, **단일 상태 파일 → pool 기반 파이프라인**, **사람 참조용 skills/docs → 코드 중심** 으로 수렴 중.
## 7. 커밋 히스토리
## 6. 리스크 및 관찰
1. **`app_key` 평문 커밋** — self-hosted 라 영향은 제한적이나, 공개 전환 시 gitignore/환경변수 분리 필요.
2. **바이너리 불투명성** — `claude-hook.exe` 소스가 이 저장소에 없음. 동작 검증을 위한 소스/빌드 스크립트 위치를 README 에 링크할 필요.
3. **대용량 바이너리 커밋** — `claude-common-installer(4).exe` (~12MB) 가 저장소에 포함. Git LFS 또는 외부 배포 권장.
4. **문서 ↔ 실체 불일치** — [SKILLS.md](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
e44877d Initial commit
```
대부분의 커밋이 훅 파이프라인 E2E 검증용 empty/dry-run 커밋이다. `9357d85`에서 이슈 번호 추출 로직까지 실제 flush 검증을 마친 것으로 보인다.
대부분 훅 파이프라인 E2E 검증용 empty/dry-run 커밋. `9357d85` 에서 이슈 번호 추출까지 실제 flush 검증 완료.
## 8. 요약
이 저장소는 **"Claude Code 사용량을 커밋 단위로 Aptabase에 자동 기록하는 훅 시스템"의 개인 실험장**이다. 핵심 산출물은 `.claude/hooks/`의 Aptabase 연동 훅 묶음이며, 나머지(README, test 파일, empty 커밋)는 모두 그 훅의 동작을 검증하기 위한 스캐폴딩이다.
`workhistory` 는 **"Claude Code 토큰 사용량을 git 커밋 단위로 self-hosted Aptabase 에 자동 기록하는 훅 시스템"의 개인 실험장**이다. v1 의 PowerShell/Bash 스크립트 묶음에서 **v2 의 `claude-hook.exe` 단일 바이너리 + commit/send pool 이원화** 구조로 진화했으며, 나머지 파일(README, installer, empty 커밋들)은 모두 그 훅 검증을 위한 스캐폴딩이다.