chore(harness): claude-harness 뼈대를 깐다
템플릿에서 옮긴 gRPC 이력 위에 새 repo의 작업 환경을 먼저 깐다.
claude-harness main 72078ca의 scripts/new-project.sh가 만든 파일을
그대로 복사했다: AGENTS.md·CLAUDE.md 양식, .claude/settings.json
(.env deny, 하네스 플러그인 harness@claude-harness 켜기),
scripts/verify.sh 뼈대, docs/vision.md·problem-statement.md·
adr/0000-template.md 양식, docs/ledger/ 빈 장부, .gitattributes,
.gitignore.
채울 자리(「(채울 것」)는 뒤 커밋에서 이 repo의 내용으로 채운다.
이 커밋 자체는 아직 빌드되지 않는다(Gradle 루트가 없다).
검증: new-project.sh 종료 코드 0, 남은 {{…}} 없음.
Refs: design-docs repo-structure/05-library-repos.md 14.2절
This commit is contained in:
@@ -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
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1 @@
|
||||
docs/ledger/estimates.jsonl merge=union
|
||||
@@ -0,0 +1,8 @@
|
||||
# 개인 설정과 비밀 값
|
||||
.claude/settings.local.json
|
||||
.env
|
||||
.env.local
|
||||
.env.*.local
|
||||
.env.production
|
||||
|
||||
__pycache__/
|
||||
@@ -0,0 +1,36 @@
|
||||
# AGENTS.md — grpc-library의 정본
|
||||
|
||||
gRPC 서버·클라이언트를 Spring Boot 앱에 붙이는 플랫폼 라이브러리다(Stable 7 모듈, advanced 2 모듈). 방향은 `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 규칙: (채울 것: 규칙 문서 경로)
|
||||
@@ -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/`에 둔다.
|
||||
@@ -0,0 +1,35 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 새 결정 기록은 이 파일을 복사해 NNNN-<짧은-이름>.md로 만든다 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 제안
|
||||
- 작성일: YYYY-MM-DD
|
||||
- 요약: 무엇을 정했는지 한국어 한 문장
|
||||
- 현재 정본: 지금 동작을 설명하는 살아 있는 문서의 경로. 없으면 「없음 — 이유」
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# NNNN. (결정 제목: 무엇을 정했나)
|
||||
|
||||
## 맥락
|
||||
|
||||
무엇이 문제였고, 무엇이 결정을 강요했나. 숫자와 사건으로 쓴다.
|
||||
|
||||
## 결정
|
||||
|
||||
정한 것을 한두 문장으로. 누가 정했는지(소유자·팀·에이전트 판단)를 밝힌다.
|
||||
|
||||
## 고른 이유와 버린 대안
|
||||
|
||||
| 안 | 장점 | 단점 | 고름 |
|
||||
|---|---|---|---|
|
||||
| A | | | 예 |
|
||||
| B | | | 아니요 — 이유 |
|
||||
|
||||
## 결과
|
||||
|
||||
- 좋아지는 것:
|
||||
- 치르는 값:
|
||||
- 다시 볼 때: (어떤 숫자나 사건이 생기면 이 결정을 다시 보나)
|
||||
|
||||
## 틀렸다면 어디서 드러나나
|
||||
|
||||
이 결정의 가정이 틀렸다면 무엇을 보면 알 수 있나. 잴 수 있게 쓴다.
|
||||
@@ -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`(고친 커밋이나 문서).
|
||||
@@ -0,0 +1,34 @@
|
||||
# 문제 정의 — grpc-library
|
||||
|
||||
> 아이디어가 아니라 고객의 문제에서 출발한다. 좋은 스펙은 헷갈리지 않게 하는 스펙이다.
|
||||
> 바뀌면 고친다(살아 있는 문서). 왜 바꿨는지는 커밋 본문이나 결정 기록에 남긴다.
|
||||
|
||||
## 고객의 말 그대로
|
||||
|
||||
- (채울 것: 고객이 실제로 한 말을 따옴표로. 해석하지 않는다)
|
||||
|
||||
## 지금은 어떻게 버티나
|
||||
|
||||
- (채울 것: 고객이 지금 쓰는 우회 방법과 그 비용)
|
||||
|
||||
## 하지 않는 것
|
||||
|
||||
- (채울 것: 이번에 일부러 풀지 않는 문제, 만들지 않는 기능)
|
||||
|
||||
## 성공 기준
|
||||
|
||||
| 기준 | 구체적으로 | 어떻게 재나 | 목표 값 | 기한 |
|
||||
|---|---|---|---|---|
|
||||
| (채울 것) | | | | |
|
||||
|
||||
## 세 관점 점검
|
||||
|
||||
| 관점 | 묻는 것 | 답 |
|
||||
|---|---|---|
|
||||
| 비즈니스 | 돈이 되나, 누가 대가를 치르나 | (채울 것) |
|
||||
| 기술 | 만들 수 있나, 가장 위험한 가정은 | (채울 것) |
|
||||
| 고객 | 쓸모 있나, 지금 방법보다 나은가 | (채울 것) |
|
||||
|
||||
## 되돌릴 수 없는 결정
|
||||
|
||||
- (채울 것: 되돌리기 비싼 결정만 여기 적고 `docs/adr/`에 결정 기록을 남긴다. 되돌릴 수 있는 결정은 빨리 한다)
|
||||
@@ -0,0 +1,10 @@
|
||||
# 비전 — grpc-library
|
||||
|
||||
> 소유자가 직접 쓴다. AI에게 맡기지 않는다. 방향·목적·철학만, 길어야 세 문장이다.
|
||||
> 에이전트는 이 문서를 읽기만 한다. 고칠 일이 보이면 제안만 한다.
|
||||
|
||||
1. 누구의 어떤 문제를 푸는가: (채울 것)
|
||||
2. 성공하면 무엇이 달라지나(잴 수 있게): (채울 것)
|
||||
3. 속도보다 먼저 지킬 것: (채울 것)
|
||||
|
||||
점검 질문: 이 목표를 다 이뤘는데도 실패한다면 무엇 때문일까? 그 답이 빠진 목표다.
|
||||
Executable
+128
@@ -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/<repo 이름>),
|
||||
# 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 <<EOF
|
||||
set -u
|
||||
cd $remote_repo || exit 4
|
||||
git fetch -q origin || exit 4
|
||||
wt=\$(mktemp -d /tmp/$id.XXXXXX)
|
||||
git worktree add -q --detach "\$wt" $base || exit 4
|
||||
cleanup() { cd $remote_repo && git worktree remove --force "\$wt"; rm -f /tmp/$id.patch; }
|
||||
trap cleanup EXIT
|
||||
cd "\$wt"
|
||||
if [ -s /tmp/$id.patch ]; then git apply --binary --index /tmp/$id.patch || exit 4; fi
|
||||
got=\$(git write-tree)
|
||||
if [ "\$got" != "$tree" ]; then echo "트리 해시가 다르다: 원격 \$got, 여기 $tree" >&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 "$@"
|
||||
Reference in New Issue
Block a user