harness-map

Claude Code 하네스를 읽어 한 장의 조립도로 보여 주는 도구이다.

하네스는 모델을 둘러싼 설정 전체를 말한다. 지시 파일(CLAUDE.md), 자동 기억, 도구(MCP, 스킬), 권한, 훅이 여기에 들어간다. 같은 설정을 쓰더라도 어느 폴더에서 Claude Code 를 시작하는지, 새 에이전트를 어떤 방식으로 띄우는지에 따라 모델이 실제로 받는 내용이 달라진다. 이 도구는 그 차이를 폴더별, 띄우는 방식별로 보여 준다.

에이전트에게 맡기기

Claude Code 같은 코딩 에이전트에 아래 문장을 붙여 넣는다. 폴더 경로는 자기가 자주 작업을 시작하는 곳으로 바꾼다.

https://github.com/Dominic-DK/harness-map 의 README 를 읽고 "직접 실행" 순서대로 실행해 줘.
내가 자주 작업을 시작하는 폴더는 ~/work/a 와 ~/work/b 야.
3단계의 에이전트 점검은 안내에 적힌 안전 규칙을 지켜서 직접 수행하고 기록해 줘.
끝나면 만들어진 harness-map.html 을 브라우저로 열고, 결과를 쉬운 문어체로 다섯 문장 안팎으로 요약해 줘.

직접 실행

Python 3 가 필요하다. 추가 패키지는 필요 없다.

git clone https://github.com/Dominic-DK/harness-map.git
cd harness-map

# 1. 하네스를 읽어 harness.json 으로 저장한다. --cwd 는 원하는 만큼 반복할 수 있다.
#    설정 파일 읽기와 대화 기록 집계로 할 수 있는 점검도 이때 함께 수행한다.
python3 harness-map.py --cwd ~/work/a --cwd ~/work/b -o harness.json

# 2. 에이전트가 직접 해야 하는 점검의 절차와 안전 규칙을 출력한다.
python3 harness-map.py --probe-plan

# 3. (에이전트) 2단계의 안내대로 점검을 수행하고 결과를 probes.json 에 기록한다.
#    점검을 건너뛰어도 된다. 수행하지 않은 점검은 "미점검"으로 표시되고 레벨 계산에서 빠진다.

# 4. 점검 결과를 합쳐 다시 계산한다.
python3 harness-map.py --cwd ~/work/a --cwd ~/work/b --probes probes.json -o harness.json

# 5. 화면을 만들고 브라우저로 연다. (Linux 는 xdg-open, Windows 는 start)
python3 build.py harness.json
open harness-map.html

--cwd 를 생략하면 현재 폴더 하나만 조사한다. 대화 기록 집계 기간은 기본 30일이며 --days 로 바꿀 수 있다.

실행할 때 알아둘 것

• Claude Code 를 쓰는 그 사용자 계정으로 실행한다. 스크립트가 읽을 수 있는 범위는 Claude Code 가 읽는 범위와 같다.
• 관리자 권한(sudo)으로 실행하지 않는다. 관리자 권한으로 실행하면 홈 폴더가 바뀌어 다른 사용자의 설정을 읽게 되므로, 스크립트가 실행을 거부한다.
• 상위 폴더에서 한 번 실행한 결과로는 하위 프로젝트의 설정을 알 수 없다. 설정은 시작 폴더에서 위쪽 방향으로 결정되기 때문이다. 보고 싶은 폴더를 --cwd 로 각각 지정한다.
• 읽을 권한이 없는 파일은 결과의 unreadable 목록에 따로 적힌다. 그 파일은 Claude Code 도 읽지 못한다.

읽는 것과 남기지 않는 것

스크립트는 파일을 읽기만 하고 어떤 설정도 바꾸지 않는다.

결과 파일에는 폴더 이름과 설치한 플러그인 목록이 들어 있다. 다른 사람에게 보내기 전에 한 번 열어 확인한다. .gitignore 는 harness.json 과 harness-map.html 을 올리지 않도록 설정되어 있다.

화면에서 볼 수 있는 것

• 시작 폴더와 띄우는 방식(메인, 포크, 서브에이전트, Explore·Plan, 팀원, claude -p)을 바꿔 가며, 각 구성 요소가 새 에이전트에 어떻게 전달되는지 볼 수 있다. 전달 상태는 세 가지이다. 부모 세션에서 그대로 받는 경우, 파일에서 새로 읽는 경우, 전달되지 않는 경우이다.
• 규칙이 서로 겹칠 때 처리되는 다섯 가지 방식을 볼 수 있다. 덮어쓰기, 합치기(거부 우선), 전부 실행, 이어 붙이기(우선순위 없음), 하나만 선택이다.
• 데이터에서 찾아낸 주의할 상황을 케이스로 볼 수 있다. 예를 들어 폴더마다 자동 기억이 나뉜 경우, 팀 기능이 켜져 있어 권한 모드가 새 에이전트로 전달되는 경우가 있다.
• 다른 사람의 harness.json 을 화면의 붙여넣기 칸에 넣어 다시 그릴 수 있다.

성숙도 자가진단

하네스를 여섯 분야로 나누어 레벨 1~5 로 진단하고 육각형 그래프로 보여 준다. 여섯 분야는 지시 설계, 기억과 위치, 도구 범위, 사전 차단, 사후 검증과 관측, 위임 설계이다. 각 레벨의 기준에는 그 기준이 어느 명제나 공식 문서 사실에서 나왔는지 근거 번호가 붙어 있다.

• 스크립트는 데이터만으로 판정할 수 있는 레벨 4 까지를 자동으로 계산한다. 결과에는 어떤 조건이 맞았고 어떤 조건에서 멈췄는지가 함께 기록된다. 채점표는 harness-map.py 의 SCORECARD 에 들어 있다.
• 레벨을 올리거나 내리는 점검은 사람이 답하지 않고 스크립트와 에이전트가 수행한다. 점검은 세 가지 방법으로 이루어진다. 설정 파일을 읽는 방법, 대화 기록에서 개수를 세는 방법, 임시 폴더 안에서 실제로 시험해 보는 방법이다. 점검마다 무엇을 실행했고 무엇을 보았는지가 근거로 기록된다.
• 레벨 5 는 실제로 확인한 기록이 있을 때만 오른다. 예를 들어 금지 규칙이 실제로 명령을 막은 기록이 있어야 사전 차단이 5 가 된다. 설정이 있어도 쓰이지 않는 경우(30일 동안 쓰지 않은 도구, 설정과 다른 권한 모드로 실행된 세션 등)는 한 단계 내려간다.
• 대화 기록은 개수만 센다. 대화 본문, 명령 내용, 파일 내용은 결과에 옮기지 않는다.
• 시작 폴더가 여러 개이면 폴더별 레벨의 중앙값(짝수일 때는 낮은 쪽)을 쓰고, 최솟값과 최댓값의 범위를 함께 보여 준다.
• 사용 방식(혼자 쓰는지, 하위 에이전트를 얼마나 띄우는지, 되돌리기 어려운 명령을 얼마나 실행하는지)을 설정과 대화 기록에서 추정해 분야별로 필요한 레벨을 계산한다. 높은 레벨이 항상 좋은 것은 아니다. 혼자 쓰는 사람에게는 레벨 3 이면 충분한 분야도 많다. 화면은 필요한 레벨보다 낮은 분야만 주의 표시를 한다.

Python 이 없을 때

PROMPT.md 를 에이전트에 그대로 붙여 넣는다. 에이전트가 설정 파일을 직접 읽어 같은 형식의 JSON 을 만들고 화면까지 만든다. 이 방식은 스크립트보다 빠뜨리거나 잘못 셀 가능성이 있다.

근거와 한계

• 새 에이전트에 무엇이 전달되는지에 대한 규칙은 2026년 10월 2일에 확인한 공식 문서를 따른다. 확인한 버전은 Claude Code 2.1.287 이다. 문서는 sub-agents, agent-teams, memory 이다. 이후 버전에서 규칙이 바뀌었을 수 있다.
• 이 규칙은 harness-map.py 의 SPAWN_RULES 에 고정되어 있다. 실제 세션을 관찰한 결과는 아니다.
• 문서와 실제 동작이 다르게 관찰된 항목이 하나 있다. 문서는 서브에이전트가 자동 기억을 읽지 않는다고 설명하지만, 작성자 환경에서는 서브에이전트가 기억 목록을 받았다고 보고했다. 화면에는 이 항목을 "문서와 관찰이 다름"으로 표시한다.
• 명령줄 인자(--agents, --permission-mode 등)로 주는 설정은 파일에 남지 않으므로 읽을 수 없다.
• 플러그인은 설치 폴더 안에서 가장 최근 버전을 읽는다.

라이선스

MIT