QoderAI/better-harness

An open-source Harness Engineering platform for coding agents—define harnesses as code, run controlled experiments, inspect evidence, and compare outcomes. Turn task evidence into actionable team and organization insights.

Better Harness – AI 코딩 에이전트를 위한 코치

기능

  • AI 기반 코딩 어시스턴트(Claude Code, Codex, Cursor, GitHub Copilot, Qoder 등)를 사용할 때, Better Harness는 전체 작업 루프를 모니터링합니다: 작업 설명, 에이전트가 실행하는 명령, 변경된 파일, 실행된 테스트 또는 린터, 그리고 최종 검토 단계.
  • 호스트가 제공할 수 있는 모든 증거(프로젝트 파일, 세션 기록, CI 로그 등)를 수집하고 5가지 차원에서 워크플로우를 평가합니다:
    1. 작업 이해 (Task Understanding) – 에이전트가 목표와 '완료'의 정의를 알고 있는가?
    2. 제어된 실행 (Controlled Execution) – 단계가 반복 가능하며 정의된 도구에 의해 제한되는가?
    3. 변경 검증 (Change Validation) – 변경 사항이 작동한다는 구체적인 증거(테스트, lint, 진단)가 있는가?
    4. 신뢰할 수 있는 전달 (Reliable Delivery) – 검토나 CI와 같은 품질 게이트 체크가 적용되는가?
    5. 학습 캡처 (Learning Capture) – 다음 작업이 학습한 내용으로부터 이점을 얻는가?
  • 누락된 증거는 추측되는 대신 명시적으로 표시됩니다. 격차가 존재하는 경우, Better Harness는 다음을 포함하는 우선순위가 지정된 발견 사항을 생성합니다:
    • 격차의 영향,
    • 예상 결과,
    • 범위가 지정된 수정 계획('AI 수정'), 그리고
    • 팀이 실행할 수 있는 승인 체크.
  • 출력은 발견 사항, 증거 소스, 프롬프트, 도구 호출 및 커밋의 타임라인을 시각화하는 독립형 HTML 보고서(Markdown 및 JSON 포함)입니다.

사용 방법

  • 이미 사용 중인 코딩 에이전트용 플러그인을 설치합니다(Claude Code, Codex Desktop/CLI, Qoder Desktop/CLI, Cursor, GitHub Copilot CLI 등). README에 호스트별 설치 명령이 제공됩니다; 단일 범용 진입점은 없습니다.
  • 분석하려는 리포지토리의 새 세션에서 슬래시 명령을 실행합니다:
    /better-harness analyze this project's AI coding workflow and generate an evidence‑backed report
  • 호스트는 호스트별 폴더에 report.html(및 report.md와 findings.json)을 생성합니다. HTML을 열어 발견 사항을 탐색하거나 Markdown을 통해 빠른 요약을 확인할 수 있습니다.
  • 별도의 CLI(better-harness plugin status …, better-harness doctor …)를 사용하면 호스트 UI를 건드리지 않고도 지원되는 모든 호스트에서 플러그인의 설치 상태를 검사할 수 있습니다.

중요성

  • AI 코딩 에이전트는 코드를 빠르게 생성할 수 있지만, 팀은 코드가 어떻게 생성되었는지 파악하지 못하는 경우가 많습니다. 목표가 모호하고, 단계가 즉흥적이며, 검증이 불완전하고, 교훈이 잊혀질 수 있습니다. Better Harness는 이러한 숨겨진 부분을 가시화하여 모호한 마찰을 구체적이고 실행 가능한 개선 항목으로 바꿉니다.
  • 증거를 명시적으로 유지함으로써, 이 도구는 지나치게 낙관적인 점수를 피하고 팀이 AI 속도를 활용하면서도 개발 프로세스를 강화할 수 있는 명확한 경로를 제공합니다.

대상 사용자

  • 이미 AI 코딩 어시스턴트를 사용 중이며 주변 워크플로우를 감사하고 개선하려는 팀.
  • AI 생성 변경 사항의 품질과 반복성을 체계적으로 파악하려는 엔지니어링 관리자.
  • AI 에이전트가 작업 중에 실제로 무엇을 했는지에 대한 시각적이고 증거 기반의 보고서를 원하는 개발자.

프로젝트 상태

  • npm 패키지(@qoder-ai/better-harness)로 게시되었으며 MIT 라이선스를 따릅니다.
  • 지원되는 호스트 목록이 계속 늘어나고 있습니다(Claude Code, Codex, Qoder, Cursor, GitHub Copilot 및 Qwen Code, Pi, Kimi Code, WorkBuddy, Grok).
  • 개발에는 Node 22+가 필요하며 테스트, 패키징 스크립트 및 미리보기 서버가 포함되어 있습니다.
  • 기여 가이드는 새로운 호스트 어댑터, 평가 모델 또는 워크플로우 지침 추가를 권장합니다.

결론 Better Harness는 AI 코딩 에이전트를 모니터링하고 실제 행동을 기록하며 증거의 격차를 구체적이고 우선순위가 지정된 개선 단계로 바꾸는 오픈소스 '코치'입니다. 팀이 AI의 속도를 유지하면서 각 작업으로부터 제어, 반복성 및 학습을 되찾도록 돕습니다.

관련

  • Dispatch
    모델 성능을 넘어: AI 에이전트를 위한 Harness Engineering의 부상

    AI 코딩 에이전트가 전문적인 소프트웨어 개발을 위해 신뢰할 수 있고, 관측 가능하며, 제약된 시스템이 되도록 폐쇄 루프 시스템을 구축하는 Harness Engineering의 개념을 탐구합니다.

  • 프로젝트
    WILLOSCAR/research-units-pipeline-skills

    연구 목표를 검증 가능하고 재시작 가능한 실행으로 변환하며, 완전한 증거 기록과 고정된 파이프라인 계약을 갖춘 에이전트 지원 연구를 위한 프레임워크입니다.

  • 프로젝트
    awslabs/aidlc-workflows

    AI‑DLC는 AWS Labs의 프레임워크로, AI 코딩 어시스턴트(Claude, Kiro, Codex, Cursor, Opencode, Copilot)에 구조적이고 감사 가능한 워크플로우를 추가합니다. 하드웨어에 의존하지 않는 코어, 여러 워크플로우 프로파일, 인간의 승인 게이트, 상세한 감사 로그를 제공하여 인기 있는 AI 개발 환경에서 반복 가능한 AI 기반 소프트웨어 배포를 가능하게 합니다.

  • Dispatch
    AI에서의 에이전트 하네스(Agent Harnesses) 이해하기

    에이전트 하네스는 가공되지 않은 AI 모델을 기능적인 AI 에이전트로 변환하기 위해 시스템 프롬프트, 도구, 에이전틱 루프를 제공하는 소프트웨어 환경입니다.

  • 프로젝트
    HangYu8123/HarnessFlow

    HarnessFlow는 Claude Code, Codex CLI, 또는 GitHub Copilot을 다단계로 자가 검토 가능한 코딩 어시스턴트로 바꾸는 포터블 Markdown 지침 파일 세트입니다. 리퀘스트 템플릿, 병렬 분석 에이전트, 악마의 변호사 도전, QA 검증, 지속적인 리포지토리 메모리를 제공합니다. 리포지토리의 `.github/HarnessFlow/`에 팩을 복사하고 제공된 `setup.sh` 또는 `cli_setup.sh`를 실행하여 설치할 수 있습니다. 리퀘스트 템플릿(코드, 리팩터링, 디버깅 등)을 선택하고 채운 후 어시스턴트에 붙여넣습니다. 이 팩은 `general`, `fast`, `skill` 세 가지 워크플로우 모드를 지원하며, 벤치마크 결과로 생성 코드 줄 수가 최대 76% 감소하면서도 100% 정확성을 유지했습니다.