Dominic-DK / harness-map

# harness-map
Claude Code 하네스를 읽어 한 장의 조립도로 보여 주는 도구이다.
하네스는 모델을 둘러싼 설정 전체를 말한다. 지시 파일(CLAUDE.md), 자동 기억, 도구(MCP, 스킬), 권한, 훅이 여기에 들어간다. 같은 설정을 쓰더라도 어느 폴더에서 Claude Code 를 시작하는지, 새 에이전트를 어떤 방식으로 띄우는지에 따라 모델이 실제로 받는 내용이 달라진다. 이 도구는 그 차이를 폴더별, 띄우는 방식별로 보여 준다.
## 에이전트에게 맡기기
Claude Code 같은 코딩 에이전트에 아래 문장을 붙여 넣는다. 폴더 경로는 자기가 자주 작업을 시작하는 곳으로 바꾼다.
 [code] 
## 직접 실행
Python 3 가 필요하다. 추가 패키지는 필요 없다.
 [code] 
`--cwd` 를 생략하면 현재 폴더 하나만 조사한다. 대화 기록 집계 기간은 기본 30일이며 `--days` 로 바꿀 수 있다.
## 실행할 때 알아둘 것
- Claude Code 를 쓰는 그 사용자 계정으로 실행한다. 스크립트가 읽을 수 있는 범위는 Claude Code 가 읽는 범위와 같다.
- 관리자 권한(sudo)으로 실행하지 않는다. 관리자 권한으로 실행하면 홈 폴더가 바뀌어 다른 사용자의 설정을 읽게 되므로, 스크립트가 실행을 거부한다.
- 상위 폴더에서 한 번 실행한 결과로는 하위 프로젝트의 설정을 알 수 없다. 설정은 시작 폴더에서 위쪽 방향으로 결정되기 때문이다. 보고 싶은 폴더를 `--cwd` 로 각각 지정한다.
- 읽을 권한이 없는 파일은 결과의 `unreadable` 목록에 따로 적힌다. 그 파일은 Claude Code 도 읽지 못한다.
## 읽는 것과 남기지 않는 것
스크립트는 파일을 읽기만 하고 어떤 설정도 바꾸지 않는다.
| 대상 | 결과에 남기는 것 | 남기지 않는 것 |
|---|---|---|
| CLAUDE.md, rules | 경로, 줄 수, 읽히는 시점 | 본문 |
| 설정 파일 | 권한 모드, 규칙 개수, 환경변수 이름 | 환경변수 값, 규칙 내용 |
| 훅 | 이벤트, 출처, 실행 파일 이름 | 명령 인자, 경로 |
| MCP 서버 | 이름, 출처 | 명령, 인자, 헤더, 토큰 |
| 경로 | `~` 로 바꾼 경로 | 홈 폴더의 실제 경로 |
결과 파일에는 폴더 이름과 설치한 플러그인 목록이 들어 있다. 다른 사람에게 보내기 전에 한 번 열어 확인한다. `.gitignore` 는 `harness.json` 과 `harness-map.html` 을 올리지 않도록 설정되어 있다.
## 화면에서 볼 수 있는 것
- 시작 폴더와 띄우는 방식(메인, 포크, 서브에이전트, Explore·Plan, 팀원, `claude -p`)을 바꿔 가며, 각 구성 요소가 새 에이전트에 어떻게 전달되는지 볼 수 있다. 전달 상태는 세 가지이다. 부모 세션에서 그대로 받는 경우, 파일에서 새로 읽는 경우, 전달되지 않는 경우이다.
- 규칙이 서로 겹칠 때 처리되는 다섯 가지 방식을 볼 수 있다. 덮어쓰기, 합치기(거부 우선), 전부 실행, 이어 붙이기(우선순위 없음), 하나만 선택이다.
- 데이터에서 찾아낸 주의할 상황을 케이스로 볼 수 있다. 예를 들어 폴더마다 자동 기억이 나뉜 경우, 팀 기능이 켜져 있어 권한 모드가 새 에이전트로 전달되는 경우가 있다.
- 다른 사람의 `harness.json` 을 화면의 붙여넣기 칸에 넣어 다시 그릴 수 있다.
## 성숙도 자가진단
하네스를 여섯 분야로 나누어 레벨 1~5 로 진단하고 육각형 그래프로 보여 준다. 여섯 분야는 지시 설계, 기억과 위치, 도구 범위, 사전 차단, 사후 검증과 관측, 위임 설계이다. 각 레벨의 기준에는 그 기준이 어느 명제나 공식 문서 사실에서 나왔는지 근거 번호가 붙어 있다.
- 스크립트는 데이터만으로 판정할 수 있는 레벨 4 까지를 자동으로 계산한다. 결과에는 어떤 조건이 맞았고 어떤 조건에서 멈췄는지가 함께 기록된다. 채점표는 `harness-map.py` 의 `SCORECARD` 에 들어 있다.
- 레벨을 올리거나 내리는 점검은 사람이 답하지 않고 스크립트와 에이전트가 수행한다. 점검은 세 가지 방법으로 이루어진다. 설정 파일을 읽는 방법, 대화 기록에서 개수를 세는 방법, 임시 폴더 안에서 실제로 시험해 보는 방법이다. 점검마다 무엇을 실행했고 무엇을 보았는지가 근거로 기록된다.
- 레벨 5 는 실제로 확인한 기록이 있을 때만 오른다. 예를 들어 금지 규칙이 실제로 명령을 막은 기록이 있어야 사전 차단이 5 가 된다. 설정이 있어도 쓰이지 않는 경우(30일 동안 쓰지 않은 도구, 설정과 다른 권한 모드로 실행된 세션 등)는 한 단계 내려간다.
- 기본 권한 모드가 bypassPermissions 라는 이유만으로 사전 차단을 레벨 1 로 보지 않는다. 금지(deny) 규칙과 행동 전 훅은 이 모드에서도 막기 때문이다. 대신 이 모드에서 꺼지는 것(승인 창, 확인 규칙)을 레벨 변화 없는 표시로 보여 준다.
- 대화 기록은 개수만 센다. 대화 본문, 명령 내용, 파일 내용은 결과에 옮기지 않는다.
- 시작 폴더가 여러 개이면 폴더별 레벨의 중앙값(짝수일 때는 낮은 쪽)을 쓰고, 최솟값과 최댓값의 범위를 함께 보여 준다.
- 사용 방식(혼자 쓰는지, 하위 에이전트를 얼마나 띄우는지, 되돌리기 어려운 명령을 얼마나 실행하는지)을 설정과 대화 기록에서 추정해 분야별로 필요한 레벨을 계산한다. 높은 레벨이 항상 좋은 것은 아니다. 혼자 쓰는 사람에게는 레벨 3 이면 충분한 분야도 많다. 화면은 필요한 레벨보다 낮은 분야만 주의 표시를 한다.
## Python 이 없을 때
`PROMPT.md` 를 에이전트에 그대로 붙여 넣는다. 에이전트가 설정 파일을 직접 읽어 같은 형식의 JSON 을 만들고 화면까지 만든다. 이 방식은 스크립트보다 빠뜨리거나 잘못 셀 가능성이 있다.
## 근거와 한계
- 새 에이전트에 무엇이 전달되는지에 대한 규칙은 2026년 10월 2일에 확인한 공식 문서를 따른다. 확인한 버전은 Claude Code 2.1.287 이다. 문서는 sub-agents, agent-te