Harness Engineering (Team Attention, 2026)

요약

Team Attention의 이호연이 2026년 4월 7일에 발표한 54장 슬라이드 deck으로, AI 코딩 에이전트를 다루는 작업의 중심이 프롬프트 작성에서 작업 환경 설계로 옮겨갔다는 진단을 담았다. 발표는 이 전환에 harness engineering이라는 이름을 붙이고, 여섯 단계의 실행 순서와 각 단계에 배치할 Claude Code 도구를 한 장씩 매핑한다.

harness는 모델을 감싸 도구, 검증, 상태를 제공하는 실행 환경을 말한다. 발표가 내리는 정의는 조금 더 넓다. AI가 혼자서도 잘 일할 수 있는 작업 환경을 만들어주는 것이며, 특정 스킬이나 agent 조합이 아니라 환경 자체가 설계 대상이라는 것이다.

구성은 두 덩어리다. 앞쪽은 왜 harness가 성능 레버인지를 LangChain, OpenAI, Anthropic, Stripe 네 회사 사례로 보이고, 뒤쪽은 구조, 맥락, 계획, 실행, 검증, 개선 여섯 단계를 각각 3장에서 8장씩 할당해 실행 절차로 풀어낸다. 각 단계 끝에는 바로 설치해 쓸 수 있는 스킬 목록이 붙는다.

이 자료의 값은 측정된 효과가 아니라 정리와 매핑에 있다. 인용된 수치는 전부 외부 사례이고 발표자가 1차 측정한 값이 아니다. 도구와 패턴은 2026년 4월 시점의 Claude Code 생태계를 기준으로 삼으므로, 다른 코딩 에이전트에서는 개념만 이식되고 구현은 다시 설계해야 한다.

자료 구성

발표는 8개 절로 나뉘고, 개념 정의에 9장을 쓴 뒤 나머지를 여섯 단계에 배분한다. 단계마다 원칙 슬라이드와 실습 슬라이드가 짝을 이루는 구성이다.

발표자는 Contents Technologies와 Terminal X에서 Tech Lead를, Socar에서 Senior Data Engineer를 지냈고 인프런과 클래스101에서 수강생 1만 명 이상을 대상으로 강의한 이력이 있다. 자료에 실린 harness 구성은 이 실무 경험에서 나온 개인 설정이며 조직 표준이 아니다.

발표는 자기 harness를 세 저장소로 공개해 두고 두 가지 사용 경로를 제시한다. 플러그인으로 설치하는 방법과 Claude Code에 저장소 주소를 주고 분석을 요청하는 방법이다.

라이브 데모 절은 프로젝트 구조에서 설정 파일을 거쳐 실제 작업 흐름까지 보여주는 자리인데, 슬라이드에는 제목만 남아 있어 시연 내용은 자료로 확인할 수 없다.

배경

전환의 출발점은 프롬프트만으로 부족해진 상황이다. 발표는 이를 "말을 잘 하는 것"에서 "일하는 방법을 설계해주는 것"으로의 이동이라고 표현한다. 프롬프트를 다듬는 작업이 무의미해졌다는 뜻이 아니라, 성능을 끌어올리는 지렛대가 문장 밖으로 옮겨갔다는 뜻이다.

발표는 이 이동을 세 레벨의 진화로 그린다. 각 레벨은 사용자가 AI에게 무엇을 주는지에 따라 갈린다.

레벨이 올라갈수록 사람이 제공하는 것의 성격이 바뀐다. Level 1은 한 번의 발화, Level 2는 참고 자료, Level 3은 지속되는 환경이다. 앞의 두 레벨은 매 작업마다 다시 공급해야 하지만 환경은 한 번 깔아두면 계속 쓰인다.

전환의 근거로 발표가 드는 것은 이미 빠르게 움직이는 회사들의 사례다. 네 회사가 모두 모델을 바꿔서가 아니라 모델 바깥을 설계해서 결과를 얻었다는 공통점이 있다. 이 사례들이 자료 전체의 전제가 되므로 수치는 아래 결과 절에서 따로 다룬다.

핵심 개념

harness engineering은 AI 에이전트의 작업 환경 자체를 설계하는 행위다. 발표는 이 환경을 네 요소로 분해한다. 맥락(뭘 해야 하는지), 제한(뭘 하면 안 되는지), 작업 흐름(어떻게 일하는지), 검증(잘 했는지 확인)이다. 네 요소가 갖춰지면 사람이 매 단계 개입하지 않아도 에이전트가 스스로 일한다는 것이 설계의 목표다.

발표는 harness의 정의가 통용되는 것보다 넓다고 못박고, 좁은 의미 세 가지를 먼저 정리한 뒤 그것을 모두 포괄하는 개념으로 자기 정의를 세운다.

세 가지는 모두 harness의 일부이지만 전부가 아니다. 발표가 말하는 harness는 이 세 가지를 포함해 맥락과 제한과 흐름과 검증 전체를 포괄한다. 이 확장은 Anthropic의 문장 하나를 근거로 삼는다. harness의 모든 구성요소는 모델이 혼자서는 못 하는 것에 대한 가정을 담고 있다는 진술이다.

정의 슬라이드는 이 관점을 뒷받침하는 외부 인용 두 개를 함께 싣는다. OpenAI의 "사람이 방향을 잡고, 에이전트가 실행한다"와 Anthropic의 "규율은 코드가 아니라 스캐폴딩에서 드러난다"다. 두 문장이 같은 지점을 가리킨다. 사람이 남는 자리는 실행이 아니라 방향 설정과 구조 설계라는 것이다.

두 번째 핵심 개념은 여섯 단계 순환 구조다. 발표는 harness 설계를 한 번에 완성하는 작업이 아니라 계속 도는 순환으로 규정한다.

구조(Scaffolding)  →  맥락(Context)    →  계획(Planning)
      ↑                                          ↓
개선(Compounding) ←  검증(Verification) ←  실행(Execution)

각 단계에는 한 문장짜리 질문이 붙는다. 질문을 이어 읽으면 harness 설계의 전체 점검 목록이 된다.

순환이라는 점이 중요하다. 개선 단계에서 발견한 패턴이 새 스킬이나 새 규칙이 되어 다시 구조와 맥락으로 들어가기 때문이다. 즉 여섯 단계는 순서이면서 동시에 harness가 스스로 자라는 경로다.

세 번째 개념은 progressive disclosure다. 필요한 정보를 필요한 시점에만 단계적으로 노출하는 설계를 말한다. 발표가 이 개념을 맥락 단계의 핵심 원칙으로 올린 이유는 컨텍스트가 유한한 자원이라는 점에 있다. 한꺼번에 다 주면 AI도 헷갈린다는 것이 슬라이드의 표현이다.

방법

구조 설계

구조 단계는 한 번 해두면 계속 쓰이는 것을 깔아두는 작업이다. 발표는 프로젝트 구조 설계를 세 항목으로 제시한다.

• Monorepo로 묶기: 소스코드, 문서, 테스트, 설정을 하나의 프로젝트에서 관리해 AI가 전체 맥락을 한눈에 파악하게 한다.
• 역할별 폴더링: 목적이 명확한 폴더를 두면 AI가 어디에 무엇을 넣어야 하는지 바로 판단한다.
• 아키텍처가 퀄리티를 결정: 코드 아키텍처가 잘 잡혀 있으면 시간이 갈수록 AI 산출물의 품질이 올라간다.

세 항목의 공통 전제는 프로젝트 구조를 잘 설계하면 AI가 그 구조에 맞춰 따라간다는 것이다. 폴더가 곧 지시문 역할을 한다는 뜻이다. 발표가 드는 레퍼런스 레이아웃은 다음과 같다.

my-project/
├── src/         # 비즈니스 로직
├── docs/        # AI의 참고 문서
├── tests/       # 검증 인프라
├── .dev/        # 개발 도구와 스크립트
├── .claude/     # AI 설정
├── out/         # 빌드 산출물
└── CLAUDE.md    # 프로젝트 지도

폴더링이 왜 효과를 내는지는 지시와 위치의 대응으로 설명된다. "테스트 작성해줘"라고 하면 AI가 tests/로 가고, "문서 업데이트"라고 하면 docs/로 간다. 목적지를 매번 알려주지 않아도 되는 만큼 프롬프트가 짧아진다.

docs/의 역할은 AI의 참고서다. 아키텍처 문서와 컨벤션과 스펙을 이 폴더에 놓아두면 AI가 작업을 시작하기 전에 참고한다. 문서를 쓰는 일이 사람을 위한 기록에서 에이전트를 위한 입력으로 성격이 바뀐다는 의미다.

구조가 산출물 품질을 얼마나 가르는지는 3개월 시점의 비교로 제시된다.

30%와 85%는 한 프로젝트가 개선된 폭이 아니라 같은 시점에 두 구조를 나란히 비교한 값이다. 발표의 진단은 구조 없는 프로젝트에서 AI 품질이 시간과 함께 하락하고, 클린 아키텍처에서는 상승한다는 것이다. 새 기능이 기존 패턴의 복제로 처리되기 때문에 참고할 예시가 계속 늘어난다는 것이 상승의 이유다.

사람의 문서와 AI의 문서 분리

구조 단계에서 발표가 따로 한 장을 배정한 원칙은 문서를 두 종류로 나누는 것이다. 분리하지 않으면 사람이 관리를 멈춘 순간 AI도 엉뚱한 맥락으로 일하게 된다.

두 폴더의 차이는 누가 진실을 보증하는지에 있다. docs/의 내용이 틀리면 AI의 모든 작업이 틀린 전제에서 출발하므로 사람이 책임진다. .dev/는 에이전트가 남긴 부산물이라 신뢰 등급이 다르고, 지워도 비즈니스 지식이 사라지지 않는다.

이 콘텐츠를 아래에서 지탱하는 것이 설정 파일 네 종이다.

위쪽이 콘텐츠이고 아래쪽이 설정이라는 배치가 이 슬라이드의 요지다. 콘텐츠는 사람과 AI가 함께 쓰고, 설정은 AI의 행동 규칙만 담는다.

원자료 안에 표기가 어긋나는 지점이 하나 있다. 레이아웃 트리는 .dev/를 개발 도구와 스크립트 폴더로 적는데, 문서 분리 슬라이드는 같은 폴더를 AI가 남기는 기록으로 규정한다. 둘 중 어느 쪽을 채택할지는 자료가 정해주지 않는다.

AI 도구 다섯 종의 배치

구조 단계의 나머지 절반은 도구를 어디에 놓을지 정하는 일이다. 발표는 Claude Code의 구성 요소를 다섯 종으로 나눈다.

앞의 네 종이 기능 단위이고 마지막 하나는 배포 단위다. 그래서 plugins는 새로운 능력을 더하지 않고 이미 만든 능력을 남에게 옮기는 수단이다. 발표가 자기 harness를 plugins-for-claude-natives 저장소로 공개해 둔 것도 같은 이유다.

경계 설정

경계 설정은 AI가 무엇을 알고, 무엇을 할 수 있고, 무엇을 하면 안 되는지를 정하는 작업이다. 세 질문에 각각 다른 수단이 대응한다.

세 수단의 성격이 다르다는 점이 설계의 핵심이다. CLAUDE.md는 지시라서 모델이 따르지 않을 수 있고, 훅은 코드라서 예외 없이 실행된다. 발표가 권하는 조합은 둘을 겹쳐 쓰는 이중 안전장치다. CLAUDE.md에 "직접 main push 금지"를 쓰고, 동시에 훅으로 git push --force를 차단하는 방식이다. 지시가 무시되어도 코드가 남아 막는다.

맥락 관리

맥락 단계의 원칙은 세 가지다. progressive disclosure로 필요한 것만 필요할 때 보여주고, .claude/rules/로 상황별 규칙을 세분화하고, User와 Project와 Folder 각 레벨에 맞는 정보를 배치하는 Scope 계층을 지키는 것이다. 세 원칙 모두 컨텍스트를 아끼려는 같은 목적에서 나온다.

세 계층 상속 구조

Claude Code의 설정 파일은 아래로 갈수록 범위가 좁고 우선순위가 높으며, 하위 파일이 상위를 자동 상속한다.

~/.claude/CLAUDE.md         (USER, 나만 적용, 모든 프로젝트)
└── my-app/CLAUDE.md        (PROJECT, 팀 공유, Git 커밋)
    ├── .claude/rules/      (주제별 분리, glob으로 조건부 적용)
    │   ├── code-style.md   (*.ts, *.tsx)
    │   ├── testing.md      (*.test.*, __tests__/**)
    │   └── security.md     (**/auth/**, *.sql)
    └── src/auth/CLAUDE.md  (FOLDER, 이 폴더 작업 시에만 자동 로드)

상속 규칙은 가장 좁은 범위가 우선한다는 한 줄로 요약된다. 발표는 이 규칙을 코딩 컨벤션 예시 세 개로 보여준다.

세 레벨에 무엇을 담을지도 구분된다. User에는 내 작업 습관과 선호하는 코딩 스타일과 공통 규칙을, Project에는 이 프로젝트의 기술 스택과 컨벤션과 중요한 제약을, Folder에는 특정 모듈의 특수한 규칙을 넣는다. Project 파일만 Git에 커밋되어 팀과 공유된다는 점에서 개인 설정과 팀 설정의 경계도 이 계층이 담당한다.

분량에 대한 발표자의 조언은 최대 200줄 정도를 유지하며 계속 업데이트하라는 것이다. 이유는 성능이다. 너무 길어지면 AI 성능이 급격히 저하된다고 못박는다. 즉 CLAUDE.md는 쌓아 두는 문서가 아니라 상한을 정해 관리하는 문서다.

자료 안에 CLAUDE.md 분량 기준이 세 번 나오는데, 값이 다르고 각각 다른 상황을 가리킨다.

세 값의 관계는 참조 구조를 얼마나 갖췄는지에 달려 있다. 지침을 CLAUDE.md 안에 두면 200줄 상한에 부딪히고, 밖으로 내보내면 같은 지침을 유지하면서도 파일이 30줄까지 줄어든다.

규칙 폴더와 조건부 로드

CLAUDE.md가 길어지면 주제별로 잘라 .claude/rules/로 옮긴다. 이 폴더에 .md 파일을 놓으면 Claude Code가 자동으로 읽고, 파일명이나 파일 상단에 glob 패턴을 넣으면 해당 파일을 다루는 작업에서만 로드된다.

# .claude/rules/ 구조
code-style.md    # 항상 로드
testing.md       # 항상 로드
react-*.md       # *.tsx 작업 시만
api-design.md    # routes/ 작업 시만

조건부 로드가 있어야 규칙을 늘리면서도 컨텍스트를 아낄 수 있다. 규칙이 스무 개여도 지금 다루는 파일에 걸린 것만 올라오기 때문이다. 발표가 드는 실제 규칙 파일 예시는 다음과 같다.

세 예시의 공통점은 규칙이 측정 가능한 형태로 적혀 있다는 것이다. "테스트를 잘 쓰자"가 아니라 커버리지 80% 이상이라고 적혀 있어야 에이전트가 자기 산출물을 스스로 판정할 수 있다.

Progressive disclosure

progressive disclosure는 지침을 한 파일에 몰아넣지 않고 조건과 참조 파일을 짝지어 두는 패턴이다. SKILL.md나 CLAUDE.md 안에 어떤 상황에서 어떤 문서를 읽어야 하는지만 적는다.

핵심 아이디어는 프롬프트에 "이 상황에서는 이 문서를 읽어"라는 가이드를 주면 AI가 동적으로 필요한 문서만 읽는다는 것이다. 지침의 총량은 그대로 두고 한 번에 올라오는 양만 줄이는 방식이다.

폴더 구조로는 스킬 하나가 SKILL.md와 references/ 하위 문서들로 나뉘고, 프로젝트 쪽에서는 CLAUDE.md를 핵심만 30줄로 유지하면서 docs/architecture.md와 docs/conventions.md로 포인팅한다. 앞에서 CLAUDE.md의 상한을 200줄로 잡은 것과 비교하면, 참조 구조를 제대로 갖춘 경우에는 지도 역할만 남아 훨씬 짧아진다는 뜻이다.

세션 맥락 관리

컨텍스트는 채우는 것만큼 비우는 것도 관리 대상이다. 발표는 /context로 확인한 사용량에 따라 조치를 정하는 기준을 제시한다.

세 가지 전환 수단은 목적이 서로 다르다. 무엇을 남기고 무엇을 버리는지가 기준이다.

발표자 본인의 기준은 임계점보다 이르다. 20~30%가 되면 새로 시작하고, 아예 다른 맥락의 작업으로 넘어갈 때는 /clear를 쓰고, 같은 주제를 이어가야 할 때는 handoff로 맥락 파일을 만들어 넘긴다. handoff가 /compact와 다른 점은 요약이 대화 이력 안에 남는 대신 파일로 나온다는 것이다. 그래서 새 세션은 백지에서 시작하면서도 필요한 맥락만 골라 받는다.

주기적 점검

스킬과 MCP는 컨텍스트를 소비한다. 발표는 이 둘이 생각보다 많은 자리를 차지하고 pollution을 만들 수 있으므로 안 쓰는 것은 주기적으로 정리하라고 권한다. 슬라이드에 실린 /context 화면은 Opus 4.6에서 컨텍스트 100만 토큰 가운데 6만 1,200 토큰을 쓰는 상태를 카테고리별로 분해해 보여준다.

이 분해가 보여주는 것은 설정이 대화보다 먼저 자리를 차지한다는 사실이다. 메시지를 한 줄도 주고받지 않은 시점에 이미 시스템 프롬프트와 도구 정의와 스킬이 2만 토큰 넘게 들어와 있다. MCP 도구는 요청 시점에 로드되므로 이 목록에는 잡히지 않는다.

CLAUDE.md가 비대해질 때의 처방은 점검을 AI에게 맡기는 것이다. 발표가 제시하는 프롬프트는 CLAUDE.md와 .claude/rules를 분석해 논리적으로 문제가 없는지, 중복되거나 서로 어긋나는 내용은 없는지 확인해 달라는 요청이다. 규칙 관리 자체가 에이전트에게 위임할 수 있는 작업이라는 뜻이다.

계획 수립

계획 단계의 기본 흐름은 계획, 실행, 검증 세 칸이고 검증에서 미달이 나오면 피드백이 다시 계획으로 돌아온다.

01 계획(Plan) → 02 실행(Execute) → 03 검증(Verify)
     ↑                                    │
     └───────── 미달 시 피드백 ────────────┘

한 번에 완벽하게 만드는 것이 아니라 반복해서 수렴하는 구조라는 점이 이 도식의 요지다. 미달 피드백이 실행 단계가 아니라 계획 단계로 향한다는 점이 중요하다. 결과가 기준에 못 미쳤다면 구현이 아니라 계획에 빠진 것이 있다는 판단이다.

발표는 계획을 건너뛰는 습관을 안티패턴으로 지목한다. 두 방식을 나란히 놓으면 차이가 드러난다.

두 방식의 차이는 사람이 개입하는 시점이다. 앞쪽은 결과물이 나온 뒤에 검수하고, 뒤쪽은 결과물이 나오기 전에 계획을 승인한다. 계획과 실행을 분리하면 검수 횟수가 줄고 결과의 예측 가능성이 올라간다는 것이 발표의 결론이다.

역질문 유도

계획이 부실해지는 근본 원인은 사람 쪽에 있다. 사람은 자기 머릿속의 전제를 프롬프트에 다 담지 못한다. 그래서 AI가 질문을 해야 빠진 맥락이 드러난다.

AskUserQuestion은 이 역질문을 유도하는 패턴이다. 슬라이드에 실린 예시는 결제 시스템 리팩토링 요청이며 네 번의 주고받음으로 진행된다.

사용자  나 결제 시스템을 리팩토링하려고 해.
        너가 지금 이해한 게 뭔지 정리해주고,
        모호한 점이 없도록 내게 계속 질문해서 명확하게 해줘

AI      이해한 것: 결제 모듈의 기존 구조를 개선하려는 것
        질문 1: 현재 PG사 연동이 단일인가요, 멀티인가요?
        질문 2: 구독 결제도 포함되나요?
        질문 3: DB 스키마 변경도 허용 범위인가요?

사용자  멀티 PG, 구독 포함, DB 스키마는 건드리지 마

AI      명확해졌습니다. 그러면 계획을 세우겠습니다

요청 문장에는 세 질문의 답이 하나도 들어 있지 않다. 단일 PG인지 멀티인지에 따라 추상화 층이 달라지고, DB 스키마를 건드릴 수 있는지에 따라 작업 범위가 갈린다. 사용자가 답을 준 뒤에야 AI가 계획 작성으로 넘어간다.

세 질문 모두 요청 문장에는 없었지만 구현 방향을 완전히 바꾸는 항목이다. 이런 항목이 계획 단계에서 드러나지 않으면 실행이 끝난 뒤 재작업으로 돌아온다. 발표가 권하는 방법은 스킬 프롬프트에 미러링과 질문을 명시적으로 요구하는 문장을 박아 두어, 매번 부탁하지 않아도 인터뷰가 작동하게 만드는 것이다.

커스텀 계획 스킬

기본 Plan Mode는 계획과 실행을 분리해 준다. 발표가 지적하는 한계는 사람이 모든 걸 프롬프트에 담을 수 없다는 점이며, 그 한계를 느낄 때 인터뷰와 요구사항 도출과 플랜 파일 생성까지 자동화하는 전용 스킬을 만든다.

/specify가 그 예시이고 네 단계로 구성된다.

1. 목표 확인: 사용자의 의도를 미러링한다
2. 인터뷰: 모호한 지점을 질문으로 끌어낸다
3. 요구사항과 태스크 도출
4. 플랜 파일로 저장한 뒤 /execute로 실행

이 흐름이 만드는 변화를 발표는 implicit에서 explicit으로의 이동으로 표기한다. 머릿속에만 있던 요구사항이 파일로 나온다는 뜻이다. 파일이 되면 사람이 검토할 수 있고, 검토를 통과한 파일이 실행 지시가 되므로 실행과 계획 사이에 해석의 여지가 줄어든다.

실행 패턴

실행 단계의 첫 결정은 몇 명에게 시킬지다. 발표는 세 패턴을 제시하고 각각의 구성과 비용을 붙인다.

발표는 90% 사례가 Single이나 Subagent로 충분하다고 못박는다. Team Mode의 토큰 비용이 약 7배라는 점을 감안하면, 에이전트 간 직접 소통이 실제로 필요한 경우에만 쓰는 것이 합리적이라는 판단이다.

패턴 선택은 작업의 의존 관계에 따라 갈린다. 발표가 드는 세 시나리오는 프롬프트와 내부 동작까지 함께 제시된다.

세 시나리오를 가르는 기준은 작업 사이에 순서가 있는지, 서로 독립적인지, 중간 결과를 주고받아야 하는지다. 랜딩 페이지 분석은 서로 볼 필요가 없어 병렬이 되고, 설계와 구현은 설계 결과가 구현의 입력이라 소통 채널이 필요하다.

Ralph Loop

Ralph Loop는 완료 기준을 먼저 정하고 충족할 때까지 에이전트가 스스로 반복하는 구조다. 흐름은 완료 기준 합의, 작업, 기준 충족 여부 판정 세 칸이고 미달이면 작업으로 되돌아간다.

슬라이드의 예시는 랜딩 페이지 제작이다. 완료 기준으로 모바일 반응형과 Lighthouse 90점 이상과 카피 3번 이상 퇴고를 걸어두면 다음처럼 진행된다.

4회차 기록이 이 패턴의 성격을 보여준다. 매 회차 다른 항목이 걸리기 때문에 기준을 하나만 걸었다면 나머지가 통과하지 못한 상태로 종료되었을 것이다. 사람이 한 일은 기준 정하기 한 번이고 나머지 반복은 에이전트가 처리한다.

자율 실험 루프

Auto Research는 karpathy/autoresearch 패턴으로, 사람이 방향만 정하고 에이전트가 밤새 실험을 반복하는 구성이다. 루프는 코드 수정, 실행, 평가, 판단 네 단계가 자동으로 이어지며 반복된다.

사람의 입력은 program.md에 적는 연구 방향 하나다. 발표는 이 파일이 스킬과 같은 역할을 한다고 설명한다. 절차와 판단 기준을 문서로 고정해 두면 에이전트가 그 문서를 지침으로 삼아 실행한다는 점에서 성격이 같다는 뜻이다. 이 구성으로 시간당 약 12개 실험을 자율 수행하며 무인 운영이 가능하다.

Ralph Loop와 Auto Research의 공통 구조는 종료 조건을 사람이 정하고 반복을 에이전트가 맡는다는 것이다. 차이는 종료 조건의 성격이다. Ralph Loop는 완료 기준을 충족하면 멈추고, Auto Research는 성능 개선이라는 방향만 있고 종료가 정해져 있지 않다.

검증

검증 단계는 결과물을 어떻게 믿을 것인가라는 질문에 답한다. 발표는 네 원칙을 한 페이지씩 배정해 다룬다.

기준이 있어야 검증이 가능하다

Sprint Contract는 작업 전에 무엇을 만들고 어떻게 검증할지 합의하는 것이다. 기준 없이 시키면 AI가 끝없이 작업하거나 대충 끝냈다고 보고한다. 두 실패 모드가 모두 종료 판정의 부재에서 나온다.

실행 절차는 세 단계다.

1. 완료 조건을 먼저 정한다. "이 3가지가 되면 끝"을 시작 전에 합의한다.
2. 조건을 측정 가능하게 쓴다. "잘 되게"가 아니라 "테스트 통과 + 빌드 성공"으로 적는다.
3. 미달이면 다시 실행한다. 기준이 있으므로 자동 반복이 가능해진다.

세 번째 항목이 앞의 Ralph Loop와 이어지는 지점이다. 기준이 측정 가능한 형태로 적혀 있어야 판정을 사람이 하지 않아도 되고, 판정이 자동화되면 반복도 자동화된다.

컨텍스트를 나누고 관점을 분리한다

두 번째 원칙의 출처는 Anthropic의 "Harness design for long-running application development"다. 결과물을 만드는 Generator와 결과물을 평가하는 Evaluator를 분리하는 것이 요지이며, 같은 컨텍스트에서 만들고 평가하면 안 된다고 못박는다.

분리가 필요한 이유는 자기 평가의 편향이다. 발표가 인용하는 문장은 세 개다.

• "자기 작업을 평가하면 quality가 mediocre해도 자신있게 칭찬한다"
• "만든 AI와 확인하는 AI를 분리하는 것이 가장 강력한 레버"
• "Evaluator를 회의적으로 튜닝하는 게, Generator를 자기비판적으로 만드는 것보다 훨씬 쉽다"

세 번째 인용이 실무 지침에 해당한다. 만드는 쪽을 자기비판적으로 만들려는 시도보다 평가하는 쪽을 회의적으로 조정하는 편이 쉽다는 판단이다. 즉 개선 노력을 Evaluator 쪽에 배치하라는 뜻이다.

모델도 나누고 역할도 나눈다

세 번째 원칙은 검증을 다른 모델에 맡겨 맹점을 교차로 잡는 것이다. 발표자가 실제로 쓰는 배치는 다음과 같다.

Opus와 Sonnet의 구분은 역할이 아니라 성능별 분업이다. 판단의 깊이가 필요한 자리에 Opus를, 같은 검사를 여러 번 돌려야 하는 자리에 Sonnet을 배치한다.

같은 페이지가 인용하는 문장은 검증 에이전트에 대한 경고다. 기본 상태의 Claude는 QA 에이전트로서 부족하다는 진술이며, 발표자는 여기에 검증 에이전트도 튜닝이 필요하고 기준을 구체적이고 회의적으로 설정해야 쓸 수 있다는 해석을 붙인다.

에이전트에게 눈을 달아주기

네 번째 원칙은 검증 범위를 코드에서 화면까지 넓히는 것이다. 코드만 검사하면 웹앱의 실제 사용 경험은 사람이 확인해야 한다.

세 수단의 공통점은 사람이 눈으로 하던 확인을 에이전트에게 옮긴다는 것이다. 검증 범위가 넓어지는 만큼 사람이 중간에 개입할 일이 줄어든다.

네 원칙이 막는 실패

네 원칙은 서로 다른 실패를 겨냥한다. 하나만 적용하면 나머지 실패가 남는다는 점에서 함께 써야 하는 묶음이다.

앞의 두 원칙이 판정 구조를 다루고 뒤의 두 원칙이 판정 범위를 넓힌다. 기준이 없으면 무엇을 검사할지 모르고, 관점이 분리되지 않으면 검사 결과를 믿을 수 없고, 모델과 감각이 하나뿐이면 검사가 닿지 않는 영역이 남는다.

안전장치

검증이 완벽하지 않다는 전제에서 발표는 실수해도 괜찮은 구조를 만들라고 권한다. 세 가지 장치가 서로 다른 시점에 작동한다.

세 장치의 작동 시점이 다르다는 점이 설계의 핵심이다. dry-run은 실행 전에, Runtime Gate는 실행 순간에, worktree 격리는 실행 후에 피해 범위를 제한한다.

개선

개선 단계는 harness가 스스로 자라게 만드는 구간이다. 전체 흐름은 작업, 관측, 패턴 발견, 스킬이나 규칙 추가, 더 나은 작업으로 이어진다.

관측 항목은 두 가지다. 세션 분석은 프롬프트 패턴과 스킬 및 agent 호출 빈도를 살펴 어디서 시간을 쓰는지, 어디서 실패하는지를 찾는다. AI Slop 감지는 작업 중에 쌓인 불필요한 코드와 중복 설정과 안 쓰는 규칙을 찾는 일이다.

관측 결과를 harness에 반영하는 규칙은 숫자로 고정되어 있다.

3번이라는 기준이 하는 일은 판단을 자동화하는 것이다. 자동화할 가치가 있는지 매번 고민하지 않고 반복 횟수로 결정하므로, 개선이 의지가 아니라 절차가 된다.

단순화

harness는 늘리는 것만으로 좋아지지 않는다. 발표는 단순화를 개선의 절반으로 두고 세 원칙을 제시한다.

• 안 쓰는 건 치운다: 필요 없어진 스킬과 MCP와 규칙은 바로 삭제한다. 쌓이면 AI slop이 된다.
• 모델이 좋아지면 harness를 재평가한다: 예전에 필요했던 가드레일이 지금은 불필요할 수 있다.
• 과설계 신호를 인식한다: 설정이 너무 복잡하면 뭔가 잘못된 것이며 점점 단순해져야 정상이다.

두 번째 원칙의 근거로 발표는 Anthropic의 문장을 인용한다. harness의 공간은 모델이 좋아져도 줄어들지 않고 이동할 뿐이라는 진술이다. 모델이 스스로 하게 된 일에 걸어 둔 가드레일은 걷어내고, 새로 생긴 빈틈에 설계를 옮기라는 지침으로 읽힌다.

자가 진단

발표는 harness가 잘 작동하는지 판단하는 신호 네 개와 실패 징후 네 개를 제시하며, 각 항목에 원인 진단을 붙여 다음 조치를 지목한다.

두 표를 가르는 기준은 복잡도의 방향이다. 좋은 harness는 점점 단순해지며 복잡해지고 있다면 뭔가 잘못된 것이라는 진단이 발표의 결론이다. 규칙 수나 스킬 수가 늘어난다는 사실 자체는 성과가 아니라는 뜻이다.

관측을 자동화하는 도구로는 session-wrap 플러그인이 제시된다. Claude Code 세션이 끝난 뒤 내용을 분석해 세 가지를 뽑아낸다. 반복 작업 패턴을 감지해 스킬 후보로 제안하고, 세션 중 실수를 정리해 규칙 후보로 제안하고, CLAUDE.md와 docs/에서 업데이트가 필요한 항목을 감지한다. 앞의 3번 규칙을 사람이 세지 않아도 되게 만드는 장치다.

단계별 도구 카탈로그

발표는 여섯 단계 중 네 단계 뒤에 바로 설치해 쓸 수 있는 도구 목록을 붙였다. 소속이 서로 다르므로 어디서 오는 도구인지 구분해 두는 것이 좋다.

목록의 절반이 발표자 팀에서 만든 harness plugin이고 나머지가 Anthropic 공식 plugin과 외부 도구다. 계획 단계의 /clarify와 개선 단계의 session-wrap은 harness plugin이 아니라 plugins-for-claude-natives 저장소에서 온다.

여섯 단계 사이의 연결

여섯 단계는 나란히 놓인 항목이 아니라 앞 단계의 산출물이 뒤 단계의 입력이 되는 사슬이다. 자료 안에서 단계를 넘어 이어지는 연결이 네 군데 드러난다.

세 번째 연결이 이 자료의 핵심 구조다. 자율 반복은 모델 능력이 아니라 판정 가능한 기준에서 나온다. 완료 조건이 측정 가능한 문장으로 적혀 있으면 판정을 사람이 하지 않아도 되고, 판정이 자동화되면 반복도 자동화된다. 그래서 계획 단계에서 기준을 흐리게 적은 harness는 실행 단계에서 자율성을 얻지 못한다.

네 번째 연결은 harness가 시간과 함께 좋아지는 경로다. 개선 단계의 산출물이 다시 구조와 맥락으로 들어가므로, 같은 실수를 반복할 때마다 환경이 한 겹 두꺼워진다. 발표가 이 구조를 순환으로 그린 이유도 여기에 있다.

다른 harness 프레임과의 대응

2025년과 2026년에 같은 전환을 다룬 자료들이 harness를 저마다 다른 개수의 구성 요소로 나눴다. walkinglabs 코스(2025)가 가장 앞서고, 이 자료와 Osmani의 에세이는 2026년 자료다. 아래 대응은 각 자료가 명시한 매핑이 아니라 세 분해 방식을 나란히 놓고 읽은 해석이다.

세 프레임이 모두 검증을 독립 요소로 세운다는 점이 공통점이다. 반면 계획과 개선을 별도 단계로 올린 것은 이 자료의 특징이다. 다른 두 자료는 루프가 도는 방식과 그 안의 장치에 집중하고, 사람이 개입해 계획을 승인하는 국면과 harness 자체를 갱신하는 국면을 따로 떼지 않는다.

반대로 이 자료에 대응 단계가 없는 항목도 있다. 실행 사이에 상태를 남기는 State와 persistent state가 그렇다. 이 자료에서는 .dev/ 폴더와 handoff 파일이 같은 역할을 하지만 여섯 단계 중 하나로 올라오지는 않고 구조와 맥락 단계에 나뉘어 들어간다.

결과

발표가 제시하는 수치는 전부 외부 사례 인용이다. 네 회사가 한 페이지에 나란히 놓인다.

네 사례의 공통점은 모델을 고정한 상태에서 결과가 바뀌었다는 것이다. LangChain 사례가 가장 명확하다. 모델을 그대로 두고 harness만 바꿔 벤치마크 점수가 13.7%p 올랐고 순위가 30위에서 Top 5로 이동했다. 셀프 검증 루프와 둠 루프 탐지는 모두 모델 능력이 아니라 모델을 도는 방식에 대한 설계다.

OpenAI와 Anthropic 사례는 비용 구조를 보여준다. OpenAI 쪽에서 5개월이라는 기간이 코딩이 아니라 환경 설계에 쓰였다는 점, Anthropic 쪽에서 9달러짜리 시도가 실패하고 200달러짜리 harness가 성공했다는 점이 그렇다. 간소화 버전이 124달러로 같은 품질을 냈다는 대목은 harness 비용도 최적화 대상이라는 것을 시사한다.

Stripe 사례는 규모의 문제로 읽힌다. 주당 1,000 PR을 무인으로 머지하려면 매 스텝에 검증 게이트가 걸려 있어야 하고, 각 에이전트가 필요한 컨텍스트만 받아야 한다. harness 없이는 도달할 수 없는 운영 규모라는 것이 발표의 해석이다.

네 사례를 묶는 명제는 하나다. 모델 교체로 5%를 개선하기보다 harness 설계로 15%를 개선하는 편이 현실적이라는 것이다.

한계

자료가 직접 밝히는 주의점

발표가 스스로 단서를 붙인 대목은 네 곳이다.

두 번째와 세 번째 항목이 이 자료의 실무 감각을 보여준다. harness를 촘촘하게 만드는 것이 목표가 아니고, 설계자가 자기 harness를 이해하지 못하면 관리가 끊긴다는 인식이다.

독자 관점에서 남는 제약

아래는 자료가 명시한 한계가 아니라 자료 밖에서 본 제약이다.

• 2차 자료 의존: 네 회사의 수치는 외부 블로그와 강연 인용이고 발표자가 1차 측정한 값이 아니다. 재현성과 세부 조건은 원 출처에서 확인해야 한다.
• Claude Code 생태계 종속: 모든 도구와 패턴이 Claude Code 기준이다. 다른 코딩 에이전트에는 개념만 이식되고 구현은 다시 설계해야 한다.
• 개인 워크플로 중심: 발표자 본인의 harness 구성이 기준점이며, 팀이나 조직 단위의 거버넌스(권한, 공유, 버전 관리)는 다루지 않는다.
• Team Mode의 실패 모드 부재: 토큰 비용이 약 7배라는 점은 언급되지만 실패 시 디버깅이나 복구 패턴은 제시되지 않는다.
• harness 자체의 측정 부재: 좋은 harness는 단순해진다는 주장이 정성적이다. 규칙 수, 스킬 호출 빈도, 검증 패스율 같은 정량 지표로 재는 프레임워크가 없다.
• 이동 경로의 사례 부재: harness의 공간이 이동한다는 인용은 있지만 어디로 이동하는지의 사례 연구는 없다.
• 비개발 영역 근거 부족: SEO 감사와 콘텐츠 제작과 리서치도 대상이라고 언급하고 /geo-audit 예시를 들지만 상세한 케이스 스터디가 없다.
• 라이브 데모 구간의 공백: 발표자 본인 harness의 시연 자리에는 제목만 남아 있어 실제 내용을 자료로 확인할 수 없다.

사람에게 남는 역할

발표의 마무리는 harness가 자동화될수록 사람이 무엇을 하는지에 답한다. 세 가지 과제가 여섯 단계 중 구조와 맥락과 개선에 배치된다.

세 과제 모두 한 번 끝나는 작업이 아니라 유지 작업이라는 공통점이 있다. 계획과 실행과 검증은 상당 부분 에이전트에게 넘어가지만, 환경을 만들고 갱신하고 정리하는 일은 사람에게 남는다는 배치다.

발표의 마지막 문장이 이 관점을 압축한다. AI가 코드를 쓰는 시대에 사람의 역할은 "잘 짜기"에서 "잘 일하는 환경을 만들기"로 바뀐다는 것이다.

핵심 용어

관련 페이지

• Agent Harness Engineering 개괄과 학습 경로: 이 자료를 포함해 harness engineering을 다룬 여러 자료를 한 장의 지도로 묶은 상위 진입점. 이 페이지는 그 지도에서 여섯 단계 실행 절차를 제공하는 자리에 놓인다.
• Loop Engineering (Addy Osmani, 2026-06-07): Addy Osmani가 같은 전환을 loop engineering이라는 이름으로 정리한 글. 구성 요소 카탈로그와 verification distance 원칙이 이 자료의 실행 및 검증 단계와 겹친다.
• Learn Harness Engineering: harness를 Instructions, State, Verification, Scope, Lifecycle 다섯 하위 시스템으로 나눠 프로젝트로 실습시키는 코스. 이 자료의 여섯 단계와 다른 분해 방식을 비교해 볼 수 있다.
• Awesome Harness Engineering: harness 자료 393개를 문제 단위로 묶은 awesome-list. 이 페이지의 단계별 도구 카탈로그를 더 넓은 생태계로 확장할 때 참고한다.
• You Can Learn AI Agent Harness & Loop Engineering In 19 Min | LLM Ops, Eval, Tracing, RAG: harness와 LLMOps를 하나의 비유로 묶은 입문 강의. 이 자료의 개념을 비전공자에게 설명할 때 쓸 수 있는 대응 자료다.
• Harness Updating Is Not Harness Benefit: Disentangling Evolution Capabilities in Self-Evolving LLM Agents: harness를 갱신하는 능력과 harness에서 이득을 얻는 능력이 서로 다르다는 것을 측정한 연구. 이 자료의 개선 루프가 모든 모델에서 같은 효과를 내지 않는다는 반례를 제공한다.
• Agent Lightning v1.0: Towards Harnessed Agentic RL: harness를 걸친 agent를 학습 루프에 연결하는 프레임워크. 사람이 설계하는 harness와 학습으로 개선하는 harness의 경계를 보여준다.
• Memory Intelligence Agent (MIA): Manager, Planner, Executor 역할 분리로 품질을 올리는 멀티에이전트 연구. 이 자료의 실행 패턴 분류와 같은 방향이다.
• Beyond Semantic Similarity: Rethinking Retrieval for Agentic Search via Direct Corpus Interaction: 에이전트가 원본 코퍼스를 직접 다루게 만드는 접근. 작업 환경을 풍부하게 제공한다는 이 자료의 문제의식과 이어진다.
• GBrain 생태계 자료 지도와 학습 경로: 이 자료가 먼저 써 보라고 권한 gstack이 속한 생태계 개괄.

외부 참조

• team-attention/harness: 강의자료(materials/slides)와 기본 체크리스트(harness-checklist.md)
• team-attention/hoyeon: 발표자 개인 harness 전체 구성과 verify 레퍼런스
• plugins-for-claude-natives: Team Attention에서 자주 쓰는 플러그인 모음. /clarify와 session-wrap이 여기 있다
• karpathy/autoresearch: 자율 실험 루프
• garrytan/gstack, obra/superpowers, Yeachan-Heo/oh-my-claudecode: 발표가 먼저 써 보라고 권한 도구 세 종
• anthropic.com/engineering/harness-design, openai.com/index/harness-engineering: 자료에 명시된 인용 출처