강력한 AI 에이전트도 방치하면 작업 경로가 쉽게 무너집니다. 채팅에만 계획이 남고 테스트는 생략되기 일쑤입니다. 문제를 해결하려고 등장한 도구가 Claude Code Harness 입니다.

흐트러지는 에이전트 붙잡기

Claude Code Harness는 에이전트 코딩 작업을 명시적인 단계와 산출물로 고정하는 개발 하네스입니다. 도구를 설치하면 개발 흐름이 완전히 바뀝니다. 무작정 코드를 짜는 대신 명세와 계획을 먼저 작성합니다. 기준이 명확합니다.

계획의 중심에는 spec.md 와 Plans.md 가 있습니다. 관찰하지 못한 정보는 조용히 지어내지 않고 미지로 남깁니다. 안전장치가 작동합니다. Go 언어로 작성한 가드레일 엔진이라 별도 Node.js 환경도 요구하지 않습니다.

다섯 가지 동사로 움직이는 루프

Harness는 복잡한 에이전트 작업을 다섯 가지 핵심 동사로 단순화합니다. 사용자가 원하는 결과를 설명하면 /harness-plan 명령이 범위와 수용 기준을 담은 초안을 뽑아냅니다. 개발자는 계획을 승인하거나 교정하는 역할만 맡습니다. 흐름이 단순합니다.

승인된 작업은 /harness-work 단계에서 TDD와 검증을 거쳐 실제 구현으로 이어집니다. 구현을 마치면 독립적인 검토 단계인 /harness-review가 대기합니다. 주요 지적 사항을 해결하지 않으면 다음 단계로 넘어가지 못합니다. 실수가 줄어듭니다.

가볍고 명확한 명령 체계

개발자는 몇 가지 명령어 조합으로 전체 파이프라인을 제어합니다. /harness-setup으로 프로젝트 가이드와 점검 훅을 설치해 동작 기준선을 잡습니다. 기존 설정을 바꾸기 전에는 bin/harness doctor --migration-report 명령을 실행합니다. 유용합니다.

플러그인 마켓플레이스에서 도구를 설치한 뒤 /harness-plan을 실행하면 준비가 끝납니다. 로컬 설정 쓰기 권한을 가진 프로젝트 저장소와 Claude Code v2.1 이상 버전만 있으면 바로 작동합니다. 세션 간 메모리가 필요할 때는 harness-mem 을 연결하면 됩니다. 확장이 쉽습니다.

에이전트에게 무작정 키보드를 쥐여주기 전에 명확한 계약부터 맺는 습관이 좋은 소프트웨어를 만듭니다. 도구를 믿되 프로세스로 통제하는 방식이 답을 제시합니다.

요약

  • 에이전트의 자율적 코딩에 명세(spec.md)와 계획(Plans.md)을 강제하여 작업의 탈선을 원천 차단합니다.
  • Go 기반의 가볍고 독립적인 가드레일 엔진을 활용해 Node.js 의존성 없이 로컬 환경에서 빠르게 작동합니다.
  • 계획 작성, 작업 실행, 독립 검토, 릴리즈 패키징으로 이어지는 5대 동사 기반의 명확한 개발 루프를 제공합니다.