주요 콘텐츠로 건너뛰기
AI 튜토리얼

harness-map으로 Claude Code 하네스 매핑 및 감사

이 튜토리얼에서는 하나 이상의 Claude Code 작업 공간을 스캔하고, 선택적으로 에이전트 프로브를 실행하며, 대화형 하네스 맵을 생성하고, 민감한 구성 데이터를 보호하면서 성숙도 평가를 해석하는 방법을 설명합니다.

약 14분 소요
harness-map으로 Claude Code 하네스 매핑 및 감사

harness-map이 하는 일

harness-map은 Claude Code 주변의 구성을 읽고 하나의 시각적 어셈블리 맵으로 변환합니다. harness라고 하는 이 주변 구성에는 CLAUDE.md 같은 지침 파일, 자동 메모리, MCP 서버, 스킬, 권한, 훅, 규칙 및 관련 설정이 포함됩니다.

유효한 harness는 Claude Code가 시작되는 폴더와 새 에이전트가 실행되는 방식에 따라 달라질 수 있습니다. 기본 세션, 포크, 하위 에이전트, Explore 또는 Plan 에이전트, 팀원, claude -p 호출은 서로 다른 정보를 받을 수 있습니다. harness-map은 선택한 각 시작 폴더와 실행 방식에 따른 이러한 차이를 보여 줍니다.

이 프로젝트는 Python 3을 사용하며 추가 Python 패키지가 필요하지 않습니다. 스크립트는 구성을 변경하지 않고 읽어 구조화된 harness.json 파일을 생성하며, 브라우저에서 볼 수 있는 harness-map.html 보고서를 작성합니다.

주요 기능

  • 폴더별 분석: --cwd를 반복해 필요한 만큼 시작 디렉터리를 비교할 수 있습니다.
  • 에이전트 인계 시각화: 각 구성 요소가 상위 세션에서 상속되는지, 파일에서 다시 읽히는지, 새 에이전트에 전달되지 않는지 확인할 수 있습니다.
  • 규칙 상호작용 분석: 대체, 거부 우선 병합, 모든 규칙 실행, 우선순위 없는 연결, 하나의 규칙만 선택하는 다섯 가지 처리 패턴을 검사할 수 있습니다.
  • 위험 및 주의 사례: 폴더에 따라 자동 메모리가 나뉘거나 팀 기능으로 인해 권한 모드가 새 에이전트에 전달되는 상황을 식별할 수 있습니다.
  • 성숙도 평가: 육각형 차트에서 여섯 가지 harness 규율에 대한 1~5단계 수준을 검토할 수 있습니다.
  • 개인정보를 고려한 출력: 지침 본문, 환경 변수 값, 토큰, 명령 인수 및 기타 민감한 세부 정보는 제외하고 구조적 메타데이터를 기록합니다.
  • 이식 가능한 렌더링: 다른 사람의 harness.json을 보고서 인터페이스에 붙여 넣어 해당 맵을 다시 그릴 수 있습니다.

시작하기 전에

Python 3, Git, 그리고 일반 사용자 계정에 속한 Claude Code 구성에 대한 접근 권한이 필요합니다. pip를 사용한 패키지 설치는 필요하지 않습니다.

Claude Code를 실행하는 동일한 사용자로 harness-map을 실행하세요. sudo를 사용하지 마세요. 관리자 권한으로 실행하면 유효한 홈 디렉터리가 바뀌고 다른 사용자의 구성이 노출될 수 있으므로, 스크립트는 이러한 방식의 실행을 거부합니다.

평소 Claude Code를 시작하는 실제 디렉터리를 선택하세요. 각 시작 폴더에서 구성이 상위 방향으로 확인되므로, 상위 디렉터리를 검사해도 하위 프로젝트에서 시작할 때 적용되는 모든 구성이 드러나지는 않습니다.

설치

저장소를 복제하고 해당 디렉터리로 이동하세요.

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

github.com/Dominic-DK/harness-map에서 프로젝트를 검토할 수 있습니다. 이 프로젝트는 MIT 라이선스로 배포됩니다.

1단계: Claude Code harness 검사

비교하려는 각 작업 공간에 하나씩 --cwd 인수를 지정하여 harness-map.py를 실행하세요. 다음 명령은 두 개의 예시 폴더를 검사하고 결과를 harness.json에 기록합니다.

python3 harness-map.py --cwd ~/work/a --cwd ~/work/b -o harness.json

필요한 만큼 --cwd를 반복할 수 있습니다. 생략하면 harness-map은 현재 디렉터리만 검사합니다.

python3 harness-map.py -o harness.json

초기 검사는 구성 파일을 읽고 해당 파일과 대화 기록의 집계된 수에서 완료할 수 있는 검사를 수행합니다.

대화 기록 기간 변경

기본 집계 기간은 30일입니다. 다른 관찰 기간이 필요하면 --days를 사용하세요. 예를 들어 다음 명령은 90일을 사용합니다.

python3 harness-map.py --cwd ~/work/a --days 90 -o harness.json

대화 분석은 이벤트만 집계합니다. 대화 텍스트, 명령 내용 또는 파일 내용을 결과에 복사하지 않습니다.

2단계: 에이전트 프로브 계획 출력

일부 검사는 정적 구성을 검사하는 것만으로는 충분하지 않고, 에이전트가 통제된 테스트를 수행해야 합니다. 다음 명령으로 프로젝트가 제공하는 절차와 안전 규칙을 출력하세요.

python3 harness-map.py --probe-plan

에이전트에 검사를 수행하도록 요청하기 전에 이 출력을 읽으세요. 프로브 명령을 임의로 만들지 말고 생성된 지침을 따르세요. 검사에는 구성 읽기, 관련 기록 이벤트 집계, 임시 디렉터리에서의 동작 테스트가 포함될 수 있습니다.

3단계: 프로브 수행 또는 건너뛰기

에이전트가 출력된 프로브 계획을 수행하도록 하고 관찰 결과를 probes.json에 저장하세요. 각 프로브에는 실행한 내용과 근거 자료로 관찰한 내용이 기록됩니다.

이 단계는 선택 사항입니다. 프로브를 수행하지 않으면 해당 항목은 확인되지 않음으로 표시되며 수준 계산에서 제외됩니다. 실제로 관찰하지 않은 성공 동작을 수동으로 주장하지 마세요. 특히 5단계 검사에서는 더욱 그렇습니다.

4단계: 프로브 결과 병합

동일한 시작 폴더로 검사를 다시 실행하고 --probes probes.json을 추가하세요.

python3 harness-map.py --cwd ~/work/a --cwd ~/work/b --probes probes.json -o harness.json

동일한 --cwd 집합을 사용하면 최종 계산이 첫 번째 검사에서 다룬 작업 공간에 맞게 유지됩니다.

5단계: 보고서 생성 및 열기

완성된 JSON 파일에서 HTML 보고서를 생성하세요.

python3 build.py harness.json

macOS에서는 다음 명령으로 엽니다:

open harness-map.html

Linux에서는 다음 명령을 사용합니다:

xdg-open harness-map.html

Windows에서는 다음 명령을 사용합니다:

start harness-map.html

하네스 맵 읽기

보고서에서 시작 폴더와 실행 방법을 전환하면 각 상황에 적용되는 하네스를 확인할 수 있습니다. 보고서는 각 구성 요소를 다음 세 가지 전달 상태로 구분합니다:

  • 새 에이전트가 부모 세션에서 직접 전달받습니다.
  • 새 에이전트가 파일에서 다시 읽습니다.
  • 구성 요소가 새 에이전트에 전달되지 않습니다.

이 비교를 통해 동일한 저장소를 사용하는 두 에이전트가 다르게 동작하는 이유를 이해할 수 있습니다. 예를 들어 서브에이전트는 기본 세션에서 사용할 수 있는 모든 것을 전달받지 못할 수 있으며, 특정 시작 폴더와 연결된 설정은 다른 위치에서는 적용되지 않을 수 있습니다.

겹치는 규칙 이해하기

보고서는 겹치는 규칙이 어떻게 해결되는지도 보여 줍니다. 구성 유형에 따라 나중의 값이 다른 값을 대체할 수 있고, 거부 규칙이 우선하는 방식으로 규칙이 병합될 수 있으며, 일치하는 모든 작업이 실행되거나, 우선순위 없이 텍스트가 연결되거나, 하나의 옵션만 선택될 수 있습니다.

지침, 권한 또는 훅이 적용되지 않는 것처럼 보일 때 이러한 상호 작용을 검토하세요. 문제는 파일 누락이 아니라 규칙 결합 방식일 수 있습니다.

성숙도 평가 이해하기

harness-map은 여섯 가지 영역을 1단계부터 5단계까지 평가합니다:

  1. 지침 설계
  2. 메모리와 위치
  3. 도구 범위
  4. 예방적 차단
  5. 작업 후 검증 및 관찰 가능성
  6. 위임 설계

사용 가능한 데이터가 뒷받침하는 경우 스크립트는 최대 4단계까지 자동으로 계산할 수 있습니다. 결과에는 통과한 조건과 평가가 중단된 위치가 기록됩니다. 점수 정의는 harness-map.py의 SCORECARD에 저장되어 있습니다.

5단계에는 실제로 관찰된 확인 결과의 근거가 필요합니다. 예를 들어 예방적 차단은 금지 규칙이 실제로 명령을 중지했다는 기록이 있을 때만 5단계에 도달합니다. 구성에 금지 규칙이 존재하는 것만으로는 충분하지 않습니다.

구성이 존재하지만 사용되지 않는 것처럼 보일 때도 평가 점수가 낮아질 수 있습니다. 예를 들어 선택한 기록 기간 동안 사용되지 않은 도구나, 구성된 권한 모드와 다른 권한 모드로 실행된 세션이 이에 해당합니다.

여러 시작 폴더를 검사할 때 표시되는 단계는 폴더별 점수의 중앙값입니다. 폴더 수가 짝수이면 가운데 두 값 중 낮은 값을 사용합니다. 보고서에는 최솟값부터 최댓값까지의 범위도 표시됩니다.

높은 단계가 항상 더 좋은 것은 아닙니다. harness-map은 혼자 작업하는지, 하위 에이전트를 얼마나 자주 실행하는지, 되돌리기 어려운 명령을 얼마나 자주 실행하는지 등 사용 패턴을 바탕으로 각 영역에 필요한 단계를 추정합니다. 모든 5단계 미만 점수에 경고하는 대신, 추정된 필요 수준보다 낮은 영역을 강조 표시합니다.

개인정보 보호 및 출력 검토

스캐너는 파일을 읽지만 구성을 변경하지는 않습니다. 출력에 복사되는 정보는 의도적으로 제한됩니다:

  • CLAUDE.md 및 규칙 파일의 경우 경로, 줄 수, 읽힌 시점을 기록하지만 파일 내용은 기록하지 않습니다.
  • 설정의 경우 권한 모드, 규칙 수, 환경 변수 이름을 기록하지만 환경 변수 값이나 규칙 내용은 기록하지 않습니다.
  • 훅의 경우 이벤트, 소스, 실행 파일 이름을 기록하지만 명령 인수와 경로는 제외합니다.
  • MCP 서버의 경우 이름과 소스를 기록하지만 명령, 인수, 헤더, 토큰은 제외합니다.
  • 경로의 경우 실제 홈 디렉터리 접두사를 ~로 바꿉니다.

읽을 수 없는 파일은 unreadable 목록에 포함됩니다. 프로젝트에 따르면 Claude Code도 동일한 사용자 권한으로 해당 파일을 읽을 수 없습니다.

출력에는 여전히 폴더 이름과 설치된 플러그인 목록이 포함됩니다. 공유하기 전에 harness.json과 harness-map.html을 모두 열어 검토하세요.

저장소의 .gitignore는 harness.json과 harness-map.html이 버전 관리에 포함되지 않도록 구성되어 있습니다. 그래도 커밋하기 전에 스테이징된 파일을 확인해야 합니다.

코딩 에이전트에 워크플로 위임하기

Claude Code 또는 다른 코딩 에이전트에게 저장소 지침을 따르도록 요청할 수 있습니다. 예시 폴더를 자주 사용하는 자신의 시작 디렉터리로 바꾸세요. 적절한 요청은 다음과 같습니다:

https://github.com/Dominic-DK/harness-map의 README를 읽고 직접 실행 단계를 따르세요.
제가 보통 사용하는 시작 폴더는 ~/work/a와 ~/work/b입니다.
문서화된 안전 규칙에 따라 3단계 에이전트 확인을 수행하고 결과를 기록하세요.
완료되면 브라우저에서 harness-map.html을 열고 결과를 명확한 문장 약 5개로 요약하세요.

프로브 단계에서는 사람이 감독해야 합니다. 에이전트는 --probe-plan으로 생성된 정확한 안전 계획을 따라야 합니다.

고급 팁

의미 있는 모든 진입점 검사하기

저장소 루트를 검사하면 중첩된 프로젝트까지 포함된다고 가정하지 마세요. 실제로 Claude Code를 실행하는 각 디렉터리를 별도의 --cwd로 추가하세요. 이렇게 하면 상속된 지침, 메모리 경계, 도구 사용 가능 여부를 더 유용하게 비교할 수 있습니다.

작업에 맞는 관찰 기간 선택하기

기본 30일 기간은 최근 활동에 적합하지만, 자주 사용하지 않는 도구에는 더 긴 기간이 필요할 수 있습니다. 사용되지 않았다는 근거가 성숙도 점수에 영향을 줄 수 있으므로 --days를 신중하게 사용하세요.

설정과 검증된 동작을 분리하세요

파일 기반 결과는 의도된 설정의 증거로 간주하되, 컨트롤이 런타임에 작동한다는 증명으로 간주하지 마세요. 훅, 제한 또는 기타 동작이 실제로 적용되는지 확인해야 할 때는 선택적 프로브를 사용하세요.

원시 설정을 노출하지 않고 보고서를 비교하세요

누군가 검토된 harness.json을 보내면 보고서의 붙여넣기 영역을 사용해 다시 그리세요. 민감한 값은 생략되지만 프로젝트 이름, 폴더 이름, 플러그인 이름은 그대로 남아 있으므로 양측 모두 먼저 JSON을 확인해야 합니다.

Python을 사용할 수 없을 때 대체 방법을 사용하세요

Python 3을 사용할 수 없다면 PROMPT.md의 내용을 에이전트에 복사하세요. 에이전트는 설정을 직접 읽고, 같은 형식으로 JSON을 만들며, 화면을 구성할 수 있습니다. README에서는 이 방법이 스크립트보다 항목을 누락하거나 개수를 잘못 계산할 가능성이 높다고 경고합니다.

알려진 제한 사항

  • 인계 규칙은 harness-map.py의 SPAWN_RULES에 고정되어 있으며, 실제 세션을 관찰해 도출되지 않습니다.
  • README에 따르면 이러한 규칙은 2026년 10월 2일에 확인한 Claude Code 2.1.287 문서를 따릅니다. 이후 버전에서는 동작이 달라질 수 있습니다.
  • 인용된 출처는 공식 서브에이전트, 에이전트 팀, 메모리 문서입니다.
  • 프로젝트에서는 한 가지 불일치를 지적합니다. 문서에는 서브에이전트가 자동 메모리를 읽지 않는다고 되어 있지만, 작성자의 환경에서는 메모리 목록이 서브에이전트에 전달되었다고 합니다. 보고서는 이를 문서와 관찰 결과의 차이로 표시합니다.
  • --agents 및 --permission-mode와 같은 명령줄 전용 설정은 파일에 저장되지 않으므로 스캐너에서 검색할 수 없습니다.
  • 설치된 플러그인의 경우 스캐너는 플러그인 설치 디렉터리에서 찾은 최신 버전을 읽습니다.

결론

harness-map은 프로젝트와 에이전트 시작 모드 전반에서 Claude Code가 실제로 받는 설정을 파악할 수 있는 실용적인 방법을 제공합니다. 먼저 의미 있는 모든 작업 디렉터리를 스캔하고, 필요하면 문서화된 프로브를 실행한 다음, 해당 증거를 사용해 데이터를 다시 구성하고 HTML 보고서를 생성하세요. 시각화와 성숙도 평가를 활용해 설정 공백을 찾되, 공유하기 전에 생성된 파일을 검토하고 문서화된 인계 규칙은 버전에 따라 달라질 수 있다는 점을 고려하세요.