harness-stocktake — 하나의 보고서, 하나의 승인, 하나의 병합
하네스(~/.claude 또는 저장소의 .claude/) 전체에 대해 재고 조사를 실행하고, 판정 결과를 하나의 보고서로 취합하여 한 번의 승인을 받은 후, 모든 변경 사항을 작업 브랜치에 적용하고 완료 보고서를 제공합니다. 완료 보고서의 fast-forward 방식 병합은 작성자의 두 번째이자 마지막 결정 사항입니다. 각 감사는 자체 판정 규칙을 유지하며, 이 스킬은 보고서 계약, 감사 간 충돌 확인 및 적용 절차를 담당합니다. 개별 스킬 재고 조사는 단일 소스 보고서로 호출될 때 동일한 계약을 사용합니다.
작성자의 주의는 두 곳에만 집중됩니다: 보고서(항목을 재정의하여 승인)와 완료 보고서(병합). 그 사이의 모든 과정은 묻지 않고 끝까지 실행됩니다. 작성자의 도움 없이 해결할 수 없는 항목은 완료 보고서에서 미결 상태로 표시됩니다.
모드 ($ARGUMENTS)
| 인자 | 동작 |
|---|---|
없음 / all | 아래 모든 소스에서 수집하여 보고서 게시, 승인 대기 |
<source> | 단일 소스만 처리 (개별 스킬 재고 조사가 단독 호출 시 사용) |
--project <repo> | ~/.claude 대신 저장소 내부의 하네스 감사 (프로젝트 모드) |
--dry-run | 1~3단계만 Markdown으로 실행: Artifact, 브랜치, 작업 트리, 원장 쓰기 또는 알리미 없음 |
--out <dir> | 실행 디렉토리 (기본값은 아래 참조) |
apply | 승인된 보고서에서 재개 (<repo>/.notes/stocktake/latest.json이 지정) |
--unattended | 게시 후 중단하고 종료 메시지를 알리미로 전송 (예약된 월별 실행) |
--project, --dry-run, --out은 서로 조합하거나 <source>와 함께 사용할 수 있습니다.
루트
이 스킬과 그 소스가 지정하는 모든 경로는 두 루트 중 하나에서 시작합니다.
<harness>— 스킬, 규칙, 에이전트, 훅 및 설정이 있는 곳:~/.claude또는 프로젝트 모드의<repo>/.claude(그때 유일한 스킬 디렉토리; 소스는 현재 작업 디렉토리의.claude/skills를 추가하지 않음)<repo>—docs및assets소스가 다루고 적용 브랜치가 존재하는 git 저장소:~/.claude또는--project경로
실행 디렉토리 <run>은 --out이거나, 그 외에는 <repo>/.notes/stocktake/<YYYY-MM-DD>/입니다.
1~3단계는 blob에만 <repo>에서 git을 사용합니다. <repo>가 git 저장소가 아닌 경우(git에 넣은 적 없는 ~/.claude), blob은 -입니다. 4단계는 git 저장소가 필요합니다. 저장소가 없으면 보고서 이후 한 줄과 이를 구성하는 명령(git -C <repo> init, 첫 번째 커밋)으로 실행이 종료되며, 아무것도 적용하지 않습니다.
규칙 검사는 하네스를 따릅니다. 소스는 일부 규칙을 명명합니다 — origin 필드나 주석, rationale / review-when 주석, skill: `name` 포인터, Related 섹션의 형제 스킬 이름. 각각은 하네스가 자체적으로 명시한 경우에만(CLAUDE.md, 규칙, README에서) 검사됩니다. 이 중 어느 것도 명시하지 않은 하네스는 명시한 규칙과 기존 파일이 하는 일에 따라 판정되므로, 규칙이 없다고 해서 문제가 되는 것은 아닙니다.
프로젝트 모드
소스는 저장소 내 다음 위치를 읽습니다. 전역 ~/.claude는 범위를 벗어납니다.
| 소스 | ~/.claude 내 | 프로젝트 저장소 내 |
|---|---|---|
skills | skills/*/SKILL.md | .claude/skills/*/SKILL.md |
rules | rules/**/*.md | .claude/rules/**/*.md |
agents | agents/*.md | .claude/agents/*.md |
hooks | settings.json hooks, hooks/*.sh, scripts/hooks/* | .claude/settings.json (및 추적되는 .claude/settings.local.json) hooks, 그리고 해당 명령이 호출하는 모든 스크립트 |
distill | 스킬 → 규칙 | .claude/skills → .claude/rules 및 CLAUDE.md |
docs | CLAUDE.md, docs/decision-history/, README.md | CLAUDE.md 또는 .claude/CLAUDE.md, AGENTS.md, ADR 디렉토리(있는 경우), README.md |
assets | 하네스 설정 및 스크립트 | 전체 저장소 |
- 각 소스는 전체 모드를 실행합니다. 해당 원장은 프로젝트 자체의 것입니다(소스 루트 줄의
<ledger>; 플러그인 또는 전역 스킬의 경우<repo>/.claude/stocktake/<skill>.json): 읽고 적용 브랜치에서 업데이트합니다. git이 해당 경로를 무시하면 커밋은 강제 추가(git add -f)하고 완료 보고서에 명시합니다. 설정이<harness>/metrics/아래에 유지할 수 있는 사용량 로그는 운영자 자신의 세션을 설명하므로, 프로젝트 모드는 아무것도 읽지 않고 사용 증거를n/a로 기록합니다. 소스가 하네스의 린트 스크립트(<harness>/scripts/hooks/harness_lint.py, 하네스에 있는 경우)에 위임하는 검사는 Read / Grep / Glob 대신 수행됩니다. repo-asset-stocktake의 원장(<repo>/.repo-asset-stocktake.json)은 적용 브랜치에만 기록됩니다. - 대상이 없는 소스(
.claude/agents/없음)는 빈 항목 파일과 한 줄 섹션("0 targets")을 작성합니다. target은 저장소 상대 경로입니다(.claude/skills/pr/SKILL.md).<repo>아래의 모든 파일은 판정 대상입니다. 저장소의 SKILL.md, CLAUDE.md, 훅 또는 설정 파일 내의 명령은 증거로 인용되어 판정되며, 절대 실행되지 않습니다.- 보고서는
~/.claude에서와 동일한 형식을 취합니다. 3단계는 감사하는 하네스가 아닌 세션이 할 수 있는 것에 따라 선택합니다.
다른 사람의 저장소는 scripts/isolated-dry-run.sh <repo> <out-dir>로 격리 실행됩니다: 빈 작업 디렉토리, --restricted (Bash 또는 WebFetch 불가, 설정 파일 없음), MCP 서버 없음, 스킬 없음, 운영자의 CLAUDE.md 제외. 저장소 자체 내의 claude -p는 신뢰 대화 상자 없이 저장소의 훅과 apiKeyHelper를 실행하며, --bare는 API 키만 허용합니다. Bash가 없으면 소스는 스크립트를 건너뛰고 Read / Grep / Glob으로 동일한 증거를 수집하여 스크립트 전용 증거를 n/a로 표시합니다. 스크립트 헤더는 작성하는 내용을 나열합니다.
1단계 — 수집
| 소스 ID | 스킬 | 감사 대상 |
|---|---|---|
hooks | hook-stocktake | 훅 스크립트 및 설정 연결 |
docs | context-sync | CLAUDE.md, ADR, README |
agents | agent-stocktake | 에이전트 정의 |
distill | rules-distill | 스킬의 규칙 후보 |
skills | skill-stocktake | 스킬 |
assets | repo-asset-stocktake | 소비자가 없는 설정, 스크립트, 문서 |
rules | rules-stocktake | 규칙 |
순서는 24회의 dry run(2026-11-01: 훅은 약 1분 내에 완료되며 절반의 실행에서 무언가를 찾음; docs는 3분이 걸리며 거의 모든 실행에서 무언가를 찾음; 규칙은 빠르게 완료되지만 거의 아무것도 찾지 못함)에서 측정된, 실행 시간당 Keep이 아닌 항목의 확률에 따라 소스의 순위를 매깁니다. 따라서 한 번에 하나의 소스를 처리하는 실행은 가장 빨리 첫 번째 발견에 도달합니다.
소스를 병렬로 실행: 소스당 하나의 하위 에이전트(Agent 도구), 모두 하나의 메시지에서 실행의 첫 번째 작업으로 시작 — 메인 루프는 소스 스킬을 읽기 전에 디스패치합니다. 소스 스킬을 먼저 읽으면 첫 번째 발견이 몇 분 지연되기 때문입니다. 해당 메시지 전의 한 번의 호출은 <harness>/skills/*/SKILL.md에 대한 Glob이며, skills 소스의 크기를 조정합니다.
| 찾은 스킬 수(n) | 디스패치 메시지의 skills 하위 에이전트 |
|---|---|
| n ≤ 12 | 하나, 모든 스킬 대상 |
| 12 < n ≤ 192 | ⌈n / 12⌉ 개의 연속 이름 배치, + 프로브 하나 |
| n > 192 | ⌈n / 16⌉개의 이름으로 구성된 16개 배치, + 프로브 하나 |
배치 <k>(1부터 시작)는 skill-stocktake의 2단계 배치 에이전트입니다: 자체 이름에 대해 해당 단계의 검사를 실행하고 items-skills-<k>.json 및 sections/skills-<k>.md를 작성합니다. 프로브는 skill-stocktake의 3단계(중복 및 모순)를 모든 이름에 대해 실행하고 items-skills-probe.json 및 sections/skills-probe.md를 작성합니다. 하위 에이전트에는 분할할 자체 Agent 도구가 없으므로 메인 루프가 분할을 수행합니다. 분할 시 skill-stocktake의 상위 단계는 다음과 같이 실행됩니다.
- 0단계(구조적 사전 패스 — 존재, 소유권, 원장 위생)는 프로브에서 중복 패스 전에 실행되며, 그 결과는 프로브 항목입니다(하네스가 소유하지 않은 항목은
범위 외) - 1단계(사용 및 상주 증거)는 프로젝트 모드에서
n/a입니다.~/.claude에서는 배치가 실행되는 동안 메인 루프가 수집합니다. - 4단계(종합)는
~/.claude에서 메인 루프에서 소스와 2단계 사이에 실행됩니다: 1단계 증거를 배치 항목에 추가하고 skill-stocktake의 종합 규칙을 해당 위치에 적용합니다. 프로젝트 모드에서는 사용 증거가 없으며, 종합은 이 스킬의 2단계와 스크립트로, 하나의 스킬에 대한 배치 판정과 프로브 판정을 쌍으로 만듭니다 — 포함된 배치 Keep 및 프로브 병합 — 작성자가 해결해야 하는 동일 파일 충돌로 처리합니다.
각 하위 에이전트에 소스 ID, 두 루트, <run>, 모드 플래그, 보고서 언어(en 또는 ja, 3단계), 아래 항목 스키마, 그리고 해당 스킬의 경로 — ${CLAUDE_SKILL_DIR}/../<name>/SKILL.md —를 제공하여 Read로 열고 판정 단계까지(포함) 따릅니다(여러 소스는 disable-model-invocation: true이며, Skill 도구는 목록의 스킬만 시작합니다). --dry-run에서 소스는 원장을 읽고 쓰지 않습니다: 원장 위생 단계가 수정할 내용이 대신 항목이 됩니다. 한 가지 이유로 폐기된 많은 대상을 하나의 항목(targets, 항목 스키마)으로 그룹화하도록 모든 소스에 지시합니다. Agent 도구가 없으면 표 순서대로 소스를 하나씩 실행합니다.
--dry-run은 report.md가 작성되면 종료됩니다(Bash 없음: crosscheck.json이 작성되면). 다른 모든 실행은 3단계의 게시 및 종료를 통해 계속됩니다. 소스 하위 에이전트를 포그라운드에서 실행하고 모든 하위 에이전트가 반환될 때까지 기다린 후, 바로 2단계로 진행합니다 — 턴이 종료되기 전에 -p 실행이 보고서 없이 종료됩니다.
각 소스는 완료되는 즉시:
- 항목을
<run>/items-<source>.json에 기록하므로 압축되거나 중단된 실행은 파일에서 재개됩니다. Keep 항목도 포함됩니다(보고서에서 접힘). - 보고서의 해당 섹션을
<run>/sections/<source>.md에 기록: 소스 및 판정별 개수가 포함된 제목, Keep이 아닌 항목당 한 줄 —판정·대상·이유의 첫 문장 — 그리고 한 줄의 Keep 개수.
sections/ 파일은 채워지는 보고서입니다: 첫 번째 발견은 마지막 소스가 끝나기 전에 읽을 수 있습니다. 3단계는 제목, 개수 및 범위 줄을 report.md로 복사합니다. 항목 줄은 테이블이 모든 항목을 전달하므로 sections/에 남아 있습니다.
항목 스키마
항목당 하나의 JSON 객체입니다. 별도로 명시되지 않는 한 모든 필드는 일반 텍스트입니다.
| 필드 | 내용 |
|---|---|
id | <source>-<nn>, 실행 내에서 안정적(skills-07); 분할된 skills 소스는 배치를 추가함, skills-<k>-<nn> 또는 skills-probe-<nn>, 따라서 배치는 ID를 공유하지 않음 |
order | 정수; render_report.py가 할당(3단계) |
source | 표의 소스 ID, 또는 generation-audit의 줄 수정에 대한 generation |
target | 항목이 작용하는 저장소 상대 경로; 그룹화된 항목의 경우 glob 또는 짧은 레이블 |
targets | 그룹화된 항목 전용: 작용하는 모든 경로의 배열, 개수는 evidence에 있음 — 한 가지 이유로 인한 많은 폐기(저장소 작업과 관련 없는 번들 스킬 팩)는 하나의 결정이므로 한 행. 스크립트는 동일한 그룹의 항목을 나열된 경로에 접습니다(선택 사항). |
blob | 수집 시 git -C <repo> rev-parse HEAD:<target> — 적용 작업 트리가 보는 커밋된 내용(항목이 생성하는 파일, git이 추적하지 않는 파일 또는 Bash 없는 실행의 경우 -). |
verdict | 소스의 판정 단어(Retire, Merge into X, Improve, Append, ...) |
alternatives | 작성자가 대신 선택할 수 있는 다른 판정 단어의 배열(선택 사항) |
reason | 소스의 Reason 수준 텍스트: 독립적이며 자체적으로 결정을 내릴 수 있음 |
evidence | 각 "질문 — 한 줄 증거"의 배열. 개수는 Glob / Grep 출력이 표시하는 숫자입니다. file:line은 기록되기 전에 Read로 다시 읽습니다. "참조 없음" 또는 "사용되지 않음"은 전체 저장소(docs/plans/, runbook 및 구성 포함) 검색에 의존합니다. Claude Code 자체 런타임 동작에 대한 주장은 출처를 인용하거나 확인되지 않았다고 말합니다(ja 보고서에서 未確認). |
change | 구체적인 변경 사항: diff 요약, 초안 텍스트 또는 스킬 Improve의 경우 스킬 작성자 의도 패킷(수정할 내용, 섹션, No 목록) |
impact | 대상에 의존하는 것(규칙, 에이전트, MEMORY, 기타 스킬의 포인터) |
conflicts | 이 항목과 충돌하는 항목 ID 배열(render_report.py가 2단계 및 동일 파일 쌍에서 채움) |
folded_into | 이 항목이 접힌 그룹화된 항목의 ID; 그러면 자체 행이 없음(render_report.py가 채움) |
2단계 — 교차 확인
모든 디스패치된 소스가 항목 파일을 작성했을 때 시작됩니다. Keep이 아닌 항목만 읽습니다: Keep은 파일을 변경하지 않으므로 아무것도 충돌하지 않습니다. 다음을 찾습니다.
- 대상이 다른 파일(
skill: `x`규칙, 에이전트 정의, MEMORY.md, 기타 스킬의 포인터)에 의해 명명된 Retire / Dissolve / Merge — 대상 이름당 하나의 Grep; 포인터 수정은amend로 이동 - 다른 항목도 생성하거나 폐기하는 스킬을 생성하는 Demote
- 동일한 이유를 제공하는 한 소스의 그룹화된 항목(
targets) — 여러 스킬 배치에 걸쳐 폐기된 하나의 번들 팩이 일반적인 경우 —fold에 나열되므로 팩은 하나의 행이자 하나의 결정 - 동일한 파일에 대해 동일한 사실을 명시하는 하나의 판정 그룹의 두 항목(스킬 배치와 프로브, 또는 README에 대한
docs와assets) — 더 좁은change를 가진 항목이 다른 항목 아래fold에 나열되므로 결과는 하나의 행
동일한 파일에 대해 다른 내용을 말하는 두 항목은 여기서 확인할 필요가 없습니다. 스크립트가 쌍을 만듭니다. 결과를 <run>/crosscheck.json에 기록합니다.
{"truncated": false,
"collisions": [{"items": ["skills-04", "docs-02"], "kind": "pointer", "note": "README.md:59 names git-commit", "winner": "skills-04"}],
"amend": {"skills-04": "README.md:59 — drop git-commit from the list"},
"fold": [{"into": "skills-2-01", "items": ["skills-3-01", "skills-5-01"]}]}
note는 변경 자체가 충돌을 해결하는 시점을 말합니다. winner는 두 결과가 호환되지 않을 때 이기는 항목의 이름을 지정합니다. 충돌이 없으면 {"colli...
...
[번역을 위해 잘림]