diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..00130bc --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,25 @@ +{ + "permissions": { + "deny": [ + "Read(**/.env)", + "Read(**/.env.local)", + "Read(**/.env.*.local)", + "Read(**/.env.production)", + "Edit(**/.env)", + "Edit(**/.env.local)", + "Edit(**/.env.*.local)", + "Edit(**/.env.production)" + ] + }, + "extraKnownMarketplaces": { + "claude-harness": { + "source": { + "source": "git", + "url": "https://git.learn.hyeonworks.com/donghyeon.kang/claude-harness.git" + } + } + }, + "enabledPlugins": { + "harness@claude-harness": true + } +} diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..e977fa6 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +docs/ledger/estimates.jsonl merge=union diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..94f22da --- /dev/null +++ b/.gitignore @@ -0,0 +1,8 @@ +# 개인 설정과 비밀 값 +.claude/settings.local.json +.env +.env.local +.env.*.local +.env.production + +__pycache__/ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..9290967 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,36 @@ +# AGENTS.md — messaging-library의 정본 + +템플릿 밖에서 버전으로 배포하는 브로커 중립 메시징 라이브러리(dev.cakit.messaging) 방향은 `docs/vision.md`, 풀 문제와 하지 않을 것은 `docs/problem-statement.md`다. + +## 꼭 지킬 것 — 하나라도 어기면 동작해도 완료가 아니다 + +1. 관련 검증(아래 「검증」) 없이, 또는 돌리지 못한 이유를 밝히지 않고 완료를 말한다. +2. 요청 범위 밖의 큰 리팩터링, 사용자 변경 되돌리기, 요청 없는 파괴적 명령을 한다. +3. 비밀 값(`.env`, 키, 토큰)을 읽거나 커밋한다. +4. (채울 것: 이 프로젝트의 아키텍처 불변식. 예: 도메인 계층이 프레임워크·DB를 import한다) + +## 지도 + +- (채울 것: 최상위 폴더 → 하는 일. 개수·버전 숫자는 적지 않는다. 정본이 따로 있으면 그 파일을 가리킨다) +- 폴더마다의 규칙은 그 폴더의 `AGENTS.md`다. 작업 파일과 가장 가까운 것을 따른다. +- 결정 기록은 `docs/adr/`(양식 `0000-template.md`), 예측·실측 장부는 `docs/ledger/`다. + +## 맡은 일 + +- (채울 것: 일의 종류 → 먼저 읽을 문서. 예: 새 기능 → `docs/…`) +- brief가 있으면 brief의 범위·크기·완료 기준이 먼저다. + +## 검증 + +- 진입점은 하나다: `scripts/verify.sh <단계>`(docs · unit · pr · app). 사람·CI·에이전트가 같은 명령을 쓴다. +- 무거운 실행을 다른 기계에서 돌릴 때는 `scripts/verify.sh <단계> --on <호스트>`(지금 작업 트리를 패치로 옮긴다). + +## 헷갈리는 곳 + +- (채울 것: 코드만 보고는 알 수 없는 것. 없으면 이 절을 지운다) + +## 일하는 방식 + +- 착수할 때 예측을, 끝날 때 실측을 장부에 남긴다(Claude Code는 `estimate` 스킬). +- 파일을 바꾸는 위임은 사람이 열어 보고 멈출 수 있는 하위 세션에, 결과만 받는 일(검색·구조 리뷰·실행 검증)은 서브에이전트에 맡긴다. +- 커밋 메시지·PR 규칙: (채울 것: 규칙 문서 경로) diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..cbbd698 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,7 @@ +@AGENTS.md + +## Claude Code에서만 + +- 권한은 `.claude/settings.json`이다: 실제 `.env` 읽기·쓰기를 막는다(`.env.example` 같은 예시는 막지 않는다). +- 공통 훅과 스킬은 하네스 플러그인 `harness@claude-harness`가 준다: 되돌릴 수 없는 명령 차단, 비밀 값 알림, 예측·실측 장부 기록, `estimate`·`retro`·`techdebt`. 플러그인 설명은 claude-harness repo의 README다. +- 이 프로젝트만의 훅은 `scripts/hooks/`, 경로별 규칙은 `.claude/rules/`, 스킬은 `.claude/skills/`, 서브에이전트는 `.claude/agents/`에 둔다. diff --git a/docs/adr/0000-template.md b/docs/adr/0000-template.md new file mode 100644 index 0000000..6fb7fb9 --- /dev/null +++ b/docs/adr/0000-template.md @@ -0,0 +1,35 @@ + +> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. + +- 상태: 제안 +- 작성일: YYYY-MM-DD +- 요약: 무엇을 정했는지 한국어 한 문장 +- 현재 정본: 지금 동작을 설명하는 살아 있는 문서의 경로. 없으면 「없음 — 이유」 + + +# NNNN. (결정 제목: 무엇을 정했나) + +## 맥락 + +무엇이 문제였고, 무엇이 결정을 강요했나. 숫자와 사건으로 쓴다. + +## 결정 + +정한 것을 한두 문장으로. 누가 정했는지(소유자·팀·에이전트 판단)를 밝힌다. + +## 고른 이유와 버린 대안 + +| 안 | 장점 | 단점 | 고름 | +|---|---|---|---| +| A | | | 예 | +| B | | | 아니요 — 이유 | + +## 결과 + +- 좋아지는 것: +- 치르는 값: +- 다시 볼 때: (어떤 숫자나 사건이 생기면 이 결정을 다시 보나) + +## 틀렸다면 어디서 드러나나 + +이 결정의 가정이 틀렸다면 무엇을 보면 알 수 있나. 잴 수 있게 쓴다. diff --git a/docs/ledger/README.md b/docs/ledger/README.md new file mode 100644 index 0000000..9890e66 --- /dev/null +++ b/docs/ledger/README.md @@ -0,0 +1,49 @@ +# 예측·실측 장부 + +작업마다 착수할 때의 예측과 끝날 때의 실측을 한 줄씩 쌓는다. 틀린 예측에서 하네스를 고칠 곳(아키텍처 → 게이트 → 지침 → 사용자 행동 순서)을 찾는 것이 목적이다. 질타가 아니라 측정이다. + +```text +착수(첫 5분) ──> estimate 줄: p30·p50·p80 예측과 근거 +끝 보고 직전 ──> actual 줄: 세션 기록에서 뽑은 실측 +회고(주 1회) ──> retro 줄: 틀린 이유와 고칠 단계 +``` + +- 파일은 `docs/ledger/estimates.jsonl` 하나다. 한 줄이 JSON 하나다(JSON Lines). 줄을 고치거나 지우지 않고 더하기만 한다. 고칠 일이 있으면 같은 `task`로 `"correction": true` 줄을 더한다. +- 여러 브랜치가 끝에 줄을 더해도 병합이 멈추지 않게 `.gitattributes`가 이 파일에 `merge=union`을 준다. +- p30·p50·p80은 그 값 안에 끝날 확률이 30%·50%·80%라고 보는 세 값이다. p30이 도전값, p80이 안전값이다. +- 시간의 기준은 작업 중 시간이다. 끝 보고 뒤 다음 지시를 기다린 시간은 넣지 않는다. 배수는 근거(손으로 판단할 결정 수, 검증 실행 횟수와 대기)가 있을 때만 쓴다. +- Claude Code에서는 하네스 플러그인의 `estimate`·`retro` 스킬이 이 파일을 읽고 쓴다(`ledger.py precedents`·`actual`·`append`). 손으로 써도 형식은 같다. + +## 줄의 칸 + +모든 줄: + +| 칸 | 형식 | 뜻 | +| --- | --- | --- | +| `schema` | 정수 | 이 형식의 판. 지금 1 | +| `kind` | `estimate` · `actual` · `retro` | 줄의 종류 | +| `task` | 문자열 | 작업 이름. 세 종류의 줄을 묶는 키다(예: 세션 이름) | +| `recorded_at` | ISO 8601 | 이 줄을 쓴 시각 | +| `transcript` | 문자열 | Claude Code 세션 기록 파일 이름(`~/.claude/projects/<폴더>/<이 값>.jsonl`). 실측을 다시 셀 때 쓴다 | + +`estimate`: + +| 칸 | 형식 | 뜻 | +| --- | --- | --- | +| `started_at` | ISO 8601 | 세션 첫 기록 시각 | +| `base` | 문자열 | 기준 커밋 | +| `task_kind`, `size` | 문자열 | 일의 종류, 작음·중간·큼(`small`·`medium`·`large`) | +| `minutes`, `calls`, `output_tokens` | `{"p30","p50","p80"}` 정수 | 작업 중 시간(분), 모델 호출 수, 출력 토큰 | +| `basis` | 문자열 | 근거: 비교한 선례와 그 실측, 결정 수, 검증 대기 | + +`actual`: + +| 칸 | 형식 | 뜻 | +| --- | --- | --- | +| `minutes`, `active_minutes` | 정수 | 벽시계 시간, 작업 중 시간(세션 기록 사이 빈틈을 5분까지만 더한 시간) | +| `calls`, `output_tokens`, `cache_read_tokens`, `max_context` | 정수 | 세션 기록 assistant 줄의 `message.usage`. 같은 `message.id`는 한 번만 센다 | +| `within` | 문자열 | `p30`·`p50`·`p80`·`over`: 시간 실측이 들어간 가장 작은 예측 | +| `result`, `commits` | 문자열, 배열 | `done`·`partial`·`failed`, 만든 커밋 | +| `why` | 문자열 | 예측이 틀렸으면 이유 한 줄 | + +`retro`: `cause`(지시 모호 · 착수 전 조사 부족 · 아키텍처 경직 · 검증 대기 · 외부 대기 · 범위 변경 · 예측 근거 없음), `level`(`architecture` · `gate` · `instructions` · `user`), `note`, `ref`(고친 커밋이나 문서). diff --git a/docs/ledger/estimates.jsonl b/docs/ledger/estimates.jsonl new file mode 100644 index 0000000..e69de29 diff --git a/docs/problem-statement.md b/docs/problem-statement.md new file mode 100644 index 0000000..0b41511 --- /dev/null +++ b/docs/problem-statement.md @@ -0,0 +1,34 @@ +# 문제 정의 — messaging-library + +> 아이디어가 아니라 고객의 문제에서 출발한다. 좋은 스펙은 헷갈리지 않게 하는 스펙이다. +> 바뀌면 고친다(살아 있는 문서). 왜 바꿨는지는 커밋 본문이나 결정 기록에 남긴다. + +## 고객의 말 그대로 + +- (채울 것: 고객이 실제로 한 말을 따옴표로. 해석하지 않는다) + +## 지금은 어떻게 버티나 + +- (채울 것: 고객이 지금 쓰는 우회 방법과 그 비용) + +## 하지 않는 것 + +- (채울 것: 이번에 일부러 풀지 않는 문제, 만들지 않는 기능) + +## 성공 기준 + +| 기준 | 구체적으로 | 어떻게 재나 | 목표 값 | 기한 | +|---|---|---|---|---| +| (채울 것) | | | | | + +## 세 관점 점검 + +| 관점 | 묻는 것 | 답 | +|---|---|---| +| 비즈니스 | 돈이 되나, 누가 대가를 치르나 | (채울 것) | +| 기술 | 만들 수 있나, 가장 위험한 가정은 | (채울 것) | +| 고객 | 쓸모 있나, 지금 방법보다 나은가 | (채울 것) | + +## 되돌릴 수 없는 결정 + +- (채울 것: 되돌리기 비싼 결정만 여기 적고 `docs/adr/`에 결정 기록을 남긴다. 되돌릴 수 있는 결정은 빨리 한다) diff --git a/docs/vision.md b/docs/vision.md new file mode 100644 index 0000000..e9c3b2b --- /dev/null +++ b/docs/vision.md @@ -0,0 +1,10 @@ +# 비전 — messaging-library + +> 소유자가 직접 쓴다. AI에게 맡기지 않는다. 방향·목적·철학만, 길어야 세 문장이다. +> 에이전트는 이 문서를 읽기만 한다. 고칠 일이 보이면 제안만 한다. + +1. 누구의 어떤 문제를 푸는가: (채울 것) +2. 성공하면 무엇이 달라지나(잴 수 있게): (채울 것) +3. 속도보다 먼저 지킬 것: (채울 것) + +점검 질문: 이 목표를 다 이뤘는데도 실패한다면 무엇 때문일까? 그 답이 빠진 목표다. diff --git a/scripts/verify.sh b/scripts/verify.sh new file mode 100755 index 0000000..3297275 --- /dev/null +++ b/scripts/verify.sh @@ -0,0 +1,128 @@ +#!/usr/bin/env bash +# 검증 진입점. 사람·CI·에이전트가 같은 명령을 쓴다. +# +# scripts/verify.sh <단계> [--on here|<호스트>] [--log <이름>] +# +# 단계 무엇 채우는 곳 +# docs 루트 지침·장부 검사 run_docs(뼈대에 기본 검사가 있다) +# unit 빠른 단위 시험 run_unit +# pr PR 전에 통과해야 하는 게이트 묶음 run_pr +# app 앱을 띄워 health와 기본 기능을 직접 확인 run_app +# +# --on <호스트>: 지금 작업 트리(커밋 안 된 변경 포함)를 패치로 그 호스트에 옮긴다. 기준 커밋에서 새 worktree를 +# 만들어 패치를 적용하고, 트리 해시가 여기와 같은지 본 뒤 잠금 아래에서 같은 단계를 돌리고 worktree를 지운다. +# push하지 않는다. 기준 커밋은 원격 checkout이 fetch로 받을 수 있어야 한다(기본: origin/main과 갈라진 곳). +# 환경 변수: VERIFY_HOST(--on 기본값, 없으면 here), VERIFY_REMOTE_REPO(원격 checkout, 기본 ~/workspace/), +# VERIFY_BASE_REF(기본 origin/main), VERIFY_LOCK(기본 /tmp/claude-gates/heavy.lock), VERIFY_SSH(기본 ssh). +# 종료 코드: 단계의 종료 코드. 2 = 사용법, 3 = 아직 채우지 않은 단계, 4 = 원격 준비 실패. +set -euo pipefail + +ROOT=$(git rev-parse --show-toplevel) +cd "$ROOT" +TMP_FILES=() +trap '[ ${#TMP_FILES[@]} -eq 0 ] || rm -f "${TMP_FILES[@]}"' EXIT # 빈 배열 + set -u는 옛 bash에서 오류다 + +usage() { + sed -n '2,19p' "$0" | sed 's/^# \{0,1\}//' >&2 + exit 2 +} + +todo() { + echo "verify: '$1' 단계는 아직 정하지 않았다. scripts/verify.sh의 run_$1을 채운다." >&2 + return 3 +} + +# ---------------------------------------------------------------- 단계 본문(프로젝트가 채운다) + +run_docs() { + local rc=0 lines + lines=$(wc -l < AGENTS.md) + if [ "$lines" -gt 40 ]; then + echo "AGENTS.md가 ${lines}줄이다(40줄 이하). 나머지는 하위 폴더 AGENTS.md·.claude/rules·스킬로 옮긴다." >&2 + rc=1 + fi + if grep -rn --include='*.md' '(채울 것' AGENTS.md docs >&2; then + echo "verify docs: 위 자리를 아직 채우지 않았다(실패로 치지 않는다)." >&2 + fi + if [ -s docs/ledger/estimates.jsonl ] && ! python3 -c ' +import json, sys +for n, line in enumerate(open(sys.argv[1], encoding="utf-8"), 1): + if line.strip(): + json.loads(line) +' docs/ledger/estimates.jsonl; then + echo "docs/ledger/estimates.jsonl에 JSON이 아닌 줄이 있다." >&2 + rc=1 + fi + return "$rc" +} + +run_unit() { todo unit; } + +run_pr() { run_docs && run_unit && todo pr; } + +run_app() { todo app; } + +# ---------------------------------------------------------------- 실행 위치 + +run_here() { + case "$1" in + docs | unit | pr | app) "run_$1" ;; + *) usage ;; + esac +} + +run_remote() { + local stage=$1 host=$2 log=$3 ssh=${VERIFY_SSH:-ssh} + local name base tree tmp_index patch id remote_repo lock + name=$(basename "$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")") + remote_repo=${VERIFY_REMOTE_REPO:-"~/workspace/$name"} + lock=${VERIFY_LOCK:-/tmp/claude-gates/heavy.lock} + base=$(git merge-base HEAD "${VERIFY_BASE_REF:-origin/main}") + tmp_index=$(mktemp) + patch=$(mktemp) + TMP_FILES+=("$tmp_index" "$patch") + cp "$(git rev-parse --git-path index)" "$tmp_index" + GIT_INDEX_FILE=$tmp_index git add -A + tree=$(GIT_INDEX_FILE=$tmp_index git write-tree) + git diff --binary "$base" "$tree" > "$patch" + id="verify-$(date +%s)-$$" + echo "verify: $host에서 '$stage' (기준 ${base:0:12}, 트리 ${tree:0:12}, 로그 ~/$log-logs/$stage.log)" >&2 + $ssh "$host" "cat > /tmp/$id.patch" < "$patch" + $ssh "$host" bash -s <&2; exit 4; fi +mkdir -p "\$(dirname $lock)" ~/$log-logs +flock $lock ./scripts/verify.sh $stage --on here 2>&1 | tee ~/$log-logs/$stage.log +exit \${PIPESTATUS[0]} +EOF +} + +main() { + local stage=${1:-} on=${VERIFY_HOST:-here} log="" + [ -n "$stage" ] || usage + shift + while [ $# -gt 0 ]; do + case "$1" in + --on) on=${2:?--on 뒤에 호스트}; shift 2 ;; + --log) log=${2:?--log 뒤에 이름}; shift 2 ;; + *) usage ;; + esac + done + if [ "$on" = here ]; then + run_here "$stage" + else + log=${log:-$(git branch --show-current | tr '/' '-')} + run_remote "$stage" "$on" "${log:-detached}" + fi +} + +main "$@"