Claude Code Harness 소개
Claude Code Harness는 Claude Code의 에이전트 작업을 계획에서 출시까지 하나의 반복 가능한 운영 경로로 묶는 개발 하네스(harness)입니다. 저자는 강력한 에이전트라도 그냥 두면 작업이 흐트러진다고 지적합니다. 계획은 채팅 안에만 남고, 테스트는 선택사항이 되며, 검토는 너무 늦게 이루어지고, 릴리즈 근거는 기억에 의존해 다시 만들어진다는 것입니다. Harness는 이 과정을 명시적인 단계와 산출물로 고정합니다.
설치 후에는 기본 동작이 "에이전트에게 코딩을 시키는 것"에서 다음 순서로 바뀝니다. 먼저 명세와 계획을 쓰고, 승인된 작업 조각만 구현하며, 결과를 검증하고, 구현과 분리해 독립적으로 검토한 뒤, PR이나 릴리즈를 위한 증거를 패키징합니다. 이 흐름의 중심에는 spec.md 와 Plans.md 라는 진실 공급원(source of truth) 파일이 있으며, Harness는 이 파일들을 기준으로 삼습니다.
이 프로젝트가 강조하는 원칙 중 하나는 에이전트가 보지 못한 데이터를 함부로 사실로 끌어올리지 않는다는 것입니다. 관찰되지 않은 정보는 조용히 지어내는 대신 unknown 으로 남깁니다. 저자는 이를 "관찰되지 않음은 없음과 다르다(not_observed != absent)"는 문장으로 표현합니다. Harness의 핵심은 Go로 작성된 가드레일 엔진이라 별도의 Node.js가 필요 없으며, Claude Code를 주 대상으로 하면서 Codex와 OpenCode를 향한 제한된 경로도 함께 제공합니다.
Claude Code Harness의 작업 루프
Harness는 작은 표면을 유지하기 위해 다섯 개의 동사형 스킬(plan, work, review, sync, release)로 작업을 정리합니다. 사용자가 원하는 결과를 일상 언어로 설명하면, /harness-plan 이 범위와 수용 기준, 미지수, 중단 조건을 담아 spec.md 와 Plans.md 초안을 작성합니다. 비자명한 계획은 team_validation_mode 를 기록하고, 팀이나 서브 에이전트 또는 수동 검토 관점에서 명세와 계획의 정합성, 메모리 재사용, 제품 적합성, 보안 적합성을 점검합니다.
이후 /harness-work 가 승인된 작업 조각을 TDD와 검증으로 구현하고, /harness-review 가 구현과 분리된 검토를 수행하며 주요 지적을 완료 차단 사유로 다룹니다. 마지막으로 /harness-release 는 검증된 증거만 패키징합니다. 사용자의 역할은 계획을 직접 손으로 쓰는 것이 아니라, 실행이 이어지기 전에 생성된 계약(contract)을 승인하거나 교정하는 것입니다.
Claude Code Harness의 주요 명령
Harness의 명령은 각 단계가 무엇을 하는지 명확히 구분되어 있습니다.
| 명령 | 하는 일 |
|---|---|
/harness-setup |
프로젝트 가이드, 명령 표면, 훅, 점검을 설치해 하나의 기준선에서 워크플로우를 시작합니다. |
/harness-plan |
의도를 spec.md 와 Plans.md 로 바꾸며 범위, 수용 기준, 의존성, 미지수, 중단 조건을 담습니다. |
/harness-work |
승인된 작업이나 범위를 실행하고, 필요할 때 테스트를 추가하며, 검증을 돌리고 계획 범위 안에 머뭅니다. |
/harness-review |
구현과 분리해 결과를 검토하고, 주요 지적을 완료 차단 사유로 다룹니다. |
/harness-release |
릴리즈 준비 상태, CHANGELOG와 태그 경계, 증거 패키징을 구현과 검토 이후에 점검합니다. |
기존 사용자는 설정을 바꾸기 전에 bin/harness doctor --migration-report 를 실행할 수 있습니다. 이 명령은 오래된 Claude 플러그인 캐시, 중복된 Codex 스킬, 낡은 심볼릭 링크, OpenCode 백업 경로 등을 아무것도 지우지 않고 점검만 합니다.
Claude Code Harness 설치 및 사용법
Claude Code 경로에서는 플러그인 마켓플레이스를 통해 설치한 뒤 /harness-setup 으로 초기화합니다.
claude
/plugin marketplace add Chachamaru127/claude-code-harness
/plugin install claude-code-harness@claude-code-harness-marketplace
/harness-setup
설치 후에는 작은 요청 하나로 /harness-plan 을 실행해 봅니다. Harness가 spec.md 와 Plans.md 초안을 대신 작성하면, 사용자는 그 계약을 승인하거나 교정한 뒤 가장 작은 작업부터 실행합니다.
# 작은 요청으로 계획 생성
/harness-plan Improve the README onboarding flow
# 승인된 가장 작은 작업 실행 후 검토
/harness-work 1.1.1
/harness-review
지원되는 Claude 경로의 요구사항은 Claude Code v2.1 이상과 로컬 설정에 쓰기 권한이 있는 프로젝트 저장소입니다. 가드레일 엔진이 Go 네이티브라 Node.js는 필요하지 않으며, 세션 간 메모리가 필요하면 선택적 companion인 harness-mem 을 연결할 수 있습니다. Codex CLI, OpenCode, Cursor 등은 내부 호환(internal-compatible) 경로로 분류되어 있어, 각 도구의 설치 안내 문서 에서 지원 등급 경계를 확인할 수 있습니다.
Claude Code Harness의 라이선스
Claude Code Harness는 MIT 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.
Claude Code Harness 프로젝트 GitHub 저장소
더 읽어보기
-
Claude Code 동적 워크플로우(Dynamic Workflows): 작업마다 하네스를 직접 짜는 병렬 오케스트레이션
-
Agentic Harness Engineering(AHE): 관측 가능성 기반 코딩 에이전트 하네스의 자동 진화 프레임워크에 대한 연구
-
Learn Harness Engineering: AI 코딩 에이전트를 신뢰할 수 있게 만드는 하네스 엔지니어링 강의
-
Harness: 도메인 프롬프트 입력로부터 Claude Code 에이전트 팀과 스킬을 자동 생성하는 메타 스킬
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. 
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다!
텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다. 
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 