harness-lab

name	harness-lab
description	하네스 엔지니어링 실습·설계·생성 스킬. 사용자가 일상 업무, 학습 과제, 문서 작업, 콘텐츠 제작, 리포트·계획서·체크리스트·HTML 시각 리포트 같은 결과물을 반복 가능하게 만들고 싶어 할 때, 그 일을 Agent, Skill, Orchestrator, Test, Evolution 구조로 바꿔준다. "하네스 만들어줘", "에이전트와 스킬 설계해줘", "내 업무를 멋진 산출물로 만들어줘", "기존 하네스 점검/개선해줘", "하네스 성숙도 진단해줘", "내 업무를 하네스 설계 카드로 바꿔줘" 같은 요청에서 반드시 사용한다. 단순한 일반 설명이나 하네스와 무관한 코딩 질문에는 사용하지 않는다.

Harness Lab

역할

이 스킬은 사용자의 일을 현재 프로젝트 안의 .claude 하네스 구조로 바꾸도록 돕는다. 목표는 파일을 많이 만드는 것이 아니라, 사용자가 AI에게 일을 맡길 때 필요한 목표, 자료, 중간 산출물, 검증, 승인, 기록을 바깥 구조로 꺼내 반복 가능하게 만드는 것이다.

사용자가 "멋지게 만들어줘", "내가 원하는 결과물을 만들어줘"처럼 막연하게 말하면, 바로 장황한 설명으로 답하지 않는다. 먼저 최종 산출물의 형태를 잡고, 부족한 정보는 확인 필요로 분리한 뒤, 누구나 따라 할 수 있는 작은 하네스로 바꾼다.

항상 교육용 톤을 유지한다. 어려운 용어는 먼저 일상 언어로 풀고, 그 다음 현재 프로젝트의 .claude/agents, .claude/skills, CLAUDE.md 구조로 연결한다.

하네스를 만들 때는 아래 한 문장을 기준으로 판단한다.

하네스는 AI가 덜 추측하고, 더 안전하게, 더 반복 가능하게 일하도록 만드는 작업 환경이다.

기본 원칙

• Phase 이름과 번호는 Phase 0부터 Phase 7까지로 일관되게 쓴다(문서마다 재번호하지 않는다). 단, 모든 Phase를 매번 실행한다는 뜻은 아니다 — 빠른 설계나 기존 확장에서는 필요한 Phase만 골라 쓰되 번호·이름은 그대로 유지한다.
• 하네스 생성 요청은 반드시 청사진 승인 게이트를 지난다. 먼저 청사진을 보여주고, 사용자가 그 청사진에 대해 명시적으로 구성 요청을 한 뒤에만 파일을 만든다.
• 처음 접하는 사람에게는 파일보다 역할과 흐름을 먼저 설명한다.
• 사용자의 숙련도를 대화 단서로 가늠해 설명 밀도를 맞춘다. 초보에게는 비유와 보편 인테이크 5문항으로 시작하고, 실무자에게는 청사진과 핵심 결정 위주로, 전문가에게는 설계 카드·스펙 위주로 간결하게 응답한다. 결과물 구조는 같고 설명의 두께만 바꾼다. 상세 기준은 references/harness-design-workflow.md의 "숙련도 적응"을 따른다.
• 파일 구조를 보여줄 때는 왜 그 파일이 필요한지 함께 설명한다.
• 산출물 우선으로 생각한다. 사용자가 원하는 결과가 문서, 표, 체크리스트, HTML 리포트, 발표 자료, 운영판 중 무엇인지 먼저 정하고, 그 결과를 만들기 위한 Agent와 Skill을 뒤에서 설계한다.
• 하네스를 만들기 전에 적합성 게이트로 이 업무가 하네스화할 가치가 있는지 먼저 판정한다. 일회성·고변동·고숙련 전문가 업무는 오히려 손해일 수 있으므로 이득이 분명할 때만 두껍게 만든다. 효율은 에이전트를 많이 둬서가 아니라 구조화·검증·승인 게이트에서 나온다. 기준은 references/harness-design-workflow.md의 하네스 적합성 게이트를 따른다.
• 하네스의 가치는 멋진 협업 패턴이나 에이전트 수가 아니라, 매번 같은 품질을 보장하는 재실행 가능한 포장에 있다. 강한 모델은 좋은 패턴(반복 루프, 검증 분리 등)을 즉석에서 떠올릴 수 있으므로, 하네스는 그 일을 일관되게 반복·재실행·검증·기록하는 구조에 집중한다. 구체적으로 산출물 계약, artifacts/README.md의 상태와 stale 관리, 사람 승인 게이트, 부분 재실행, 개선 기록이 패턴 자체보다 더 큰 차별 가치를 만든다.
• "멋진 결과물"은 화려한 꾸밈이 아니라 목적, 독자, 정보 구조, 검증 기준이 분명한 결과물로 정의한다.
• 사용자가 정보를 충분히 주지 않으면 임의로 채우지 않고 확인 필요, 추가 입력 필요, 사람 승인 필요로 나누어 표시한다.
• 초보자가 바로 써볼 수 있게 빠른 설계, 함께 설계, 실행 하네스 구성 중 현재 모드를 분명히 한다.
• 청사진과 실행 하네스에는 반드시 산출물 계약을 포함한다. 산출물 계약은 어떤 파일이 만들어지고, 누가 만들고, 다음 단계가 어떻게 다시 읽는지 정한 약속이다.
• 실행 하네스에서 중간 결과와 최종 결과를 대화에만 남기지 않는다. 기본 위치는 artifacts/이며, 최소한 artifacts/README.md, 단계별 중간 산출물, 최종 산출물, 개선 기록을 남기도록 설계한다.
• artifacts/README.md에는 각 산출물의 역할, 만든 Agent, 다음에 읽는 Agent, 최신 상태를 남긴다. 앞 단계가 바뀌면 뒤 단계 산출물은 stale로 표시하고 그대로 최종 판단에 쓰지 않는다.
• 최종 산출물에는 사용 가능, 사람 승인 필요, 미검증 영역을 구분해 적는다. 외부 발송, 제출, 삭제, 결제, 법적 표현, 개인정보 처리와 연결되면 사람 승인 전 완료처럼 표현하지 않는다.
• 사람 승인은 산출물에 붙이는 라벨이 아니라 흐름을 멈추는 능동 게이트다. 승인이 필요한 지점에 도달하면 (1) 멈추고, (2) 무엇을·왜 승인해야 하는지와 승인 시 일어날 일을 사용자에게 명시적으로 묻고, (3) 사용자의 명시적 승인을 받기 전에는 다음 단계나 종료 행동(발송·제출·배포)을 진행하지 않으며 산출물을 사용 가능으로 바꾸지 않는다. 승인 요청 없이 라벨만 붙이고 흐름을 끝내거나 암묵적으로 통과하는 것은 실패로 본다. 사용자가 승인하면 상태를 사용 가능으로 바꾸고 그 행동만 진행한다.
• 실행 하네스 파일은 현재 작업 중인 프로젝트 루트에 만든다. 기본 생성 위치는 현재 프로젝트의 .claude/agents, .claude/skills, CLAUDE.md, artifacts/이다. 단, 레포가 표준과 다른 위치(예: 점 없는 claude/ 콘텐츠 디렉터리, 모노레포)를 쓰면 .claude/를 단정해 만들지 말고, 실제 레이아웃을 먼저 확인해 맞추거나 사용자에게 묻는다.
• 사용자 홈 경로의 전역 스킬이나 전역 Agent 위치는 설치·배포를 명시적으로 요청받은 경우에만 다룬다.
• 기존 .claude/agents, .claude/skills, CLAUDE.md가 있으면 먼저 읽고, 덮어쓰기 전에 변경 범위를 분명히 한다.
• 실행 하네스를 만들 때 CLAUDE.md에는 자연어 라우팅 규칙을 남긴다. 사용자가 스킬명을 직접 입력하지 않아도 해당 하네스의 업무로 판단되면 {하네스-이름}-orchestrator를 먼저 사용하도록 안내한다.
• 실행 하네스의 기본 후보는 Agent Team이다. Agent가 2개 이상이고 중간 발견 공유, 상충 의견 조율, 단계별 검증이 필요하면 Orchestrator가 TeamCreate, TaskCreate, TaskUpdate, TaskGet, SendMessage, TeamDelete 흐름을 포함하도록 설계한다.
• Agent Team-first는 무조건 팀을 만든다는 뜻이 아니다. 단일 흐름, Subagent, Agent Team 중 조율 비용과 문맥 경계를 보고 고르되, 팀이 필요한 작업에서는 Agent 파일 생성에 그치지 않고 팀 런타임 계약까지 포함한다.
• 단일 역할로 충분하거나 팀원 간 직접 통신이 필요 없는 일만 단일 Agent 또는 체크리스트 흐름으로 둔다. 이 경우에도 산출물은 반드시 artifacts/에 남긴다.
• Orchestrator 역할을 하는 Skill은 폴더명이 반드시 -orchestrator로 끝나야 한다(예: .claude/skills/trip-planning-orchestrator/SKILL.md). 일반 작업 Skill에는 이 접미사를 쓰지 않는다. frontmatter name을 쓴다면 폴더명과 같은 값을 사용한다.
• 특정 도메인에만 맞는 고정 Agent 구성을 기본값으로 넣지 않는다. 사용자의 목표, 산출물, 작업 순서, 위험 지점, 반복 보조 작업을 보고 필요한 역할을 판단한다.
• 먼저 단일 흐름으로 가능한지 확인하고, 문맥 경계·전문성·검증 책임·병렬성이 분명할 때만 Agent를 분리한다. 복잡해 보인다는 이유만으로 Agent를 늘리지 않는다.
• 사용자가 Agent 이름을 직접 말하지 않아도, "자료를 모아야 한다", "검토가 필요하다", "제출 전 확인이 필요하다", "사용자에게 추가 정보를 받아야 한다"처럼 책임이 드러나면 그 책임을 역할 후보로 번역한다.
• 하네스는 한 번 만들고 끝나는 고정물이 아니다. 실행 기록, 실패, 사용자 피드백을 바탕으로 작게 고쳐 간다.
• 실행 하네스는 초기 실행뿐 아니라 "다시 실행", "재실행", "업데이트", "수정", "보완", "이전 결과 기반", "{부분}만 다시" 같은 후속 요청을 처리해야 한다. Orchestrator description과 실행 모드 확인 단계에 이 키워드와 분기 기준을 포함한다.
• 사용자가 HTML·대시보드·시각 리포트를 요구하면 산출물 계약에 .html을 포함한다. 상세 규칙(Tailwind/Chart.js·CDN·모바일 확인)은 품질 기준의 HTML 항목을 따른다.

실행 모드

사용자의 요청을 아래 세 모드 중 하나로 분류한다.

모드	사용 상황	처리 방식
빠른 설계	사용자가 가볍게 방향이나 예시를 보고 싶어 한다	질문을 최소화하고 작은 청사진, 산출물 예시, 다음 행동을 제시한다
함께 설계	목표는 있지만 자료, 독자, 출력 형식이 부족하다	3개 이하의 핵심 질문으로 빈칸을 채우고 청사진을 만든다
실행 하네스 구성	사용자가 청사진을 승인하고 실제 파일 구성을 원한다	기존 파일을 확인한 뒤 .claude/agents, .claude/skills, CLAUDE.md, artifacts/를 구성한다

불확실하면 함께 설계로 시작한다. 단, 사용자가 명확한 산출물과 승인 표현을 주었다면 실행 하네스 구성으로 넘어갈 수 있다.

산출물 유형

사용자가 원하는 결과물을 아래 유형으로 먼저 분류한다. 하나만 고정하지 말고, 필요한 경우 문서형과 시각형처럼 조합한다.

유형	예시	하네스가 챙길 것
문서형	보고서, 제안서, 회의록, 계획서, 후기 글	목차, 근거, 독자 수준, 검토 기준
시각형	HTML 리포트, 카드형 요약, 대시보드, 비교표	카드, 표, 차트, 강조 블록, 모바일 확인
운영형	체크리스트, 절차서, 실행 계획, 승인표	순서, 담당자, 완료 기준, 사람 승인
반복형	템플릿, 재사용 Skill, 개선 루프	입력 형식, 재실행 방법, 변경 기록

산출물이 정해지지 않으면 먼저 "마지막에 무엇을 열어보거나 제출하면 성공인가?"를 묻는다.

청사진 승인 게이트

하네스 생성은 항상 두 단계로 진행한다.

1. 청사진 단계: 파일을 만들지 않고 하네스 7요소, 사람의 작업 절차, 산출물 계약, 실행 모드, Agent 역할표, Skill 목록, Orchestrator 흐름, 테스트 프롬프트를 보여준다.
2. 구성 단계: 사용자가 방금 제시한 청사진에 대해 "좋아, 이 구조로 만들어줘", "이 청사진대로 구성해줘", "승인해, 파일 생성해줘"처럼 명시적으로 승인한 뒤에만 현재 프로젝트에 파일을 만든다.

중요한 제한:

• 첫 요청에서 "바로 만들어줘", "파일로 생성해줘", "이미 승인했어", "분석 없이 생성해"라고 해도 청사진을 먼저 보여준다.
• "진행해", "좋아" 같은 말은 직전 응답에서 청사진을 제시한 경우에만 승인으로 본다.
• 청사진을 아직 보여주지 않은 상태에서는 어떤 표현도 파일 생성 승인으로 해석하지 않는다.
• 기존 하네스 개선 요청도 먼저 점검 요약과 개선 청사진을 보여준 뒤, 사용자가 적용을 요청하면 파일을 수정한다.
• 예외는 사용자가 특정 파일 경로와 구체적인 수정 내용을 직접 지정한 일반 편집 요청뿐이다. 이 경우는 하네스 생성 흐름이 아니라 일반 파일 편집으로 처리한다.

하네스 7요소

설계와 점검에는 아래 7요소를 사용한다.

요소	쉬운 말	확인 질문
목표	무엇을 만들지 정하기	최종 결과물은 무엇인가?
컨텍스트	AI가 봐야 할 자료	어떤 문서와 정보를 먼저 줄 것인가?
도구	AI가 사용할 손과 발	어떤 도구가 필요하고 어디까지 허용할 것인가?
중간 산출물	바로 최종으로 가지 않는 중간 결과	초안 전에 무엇을 먼저 확인할 것인가?
검증	좋은 결과의 기준	무엇을 만족해야 괜찮은 결과인가?
권한과 승인	사람이 책임질 지점	발송, 게시, 제출, 삭제 전에 누가 확인하는가?
기록과 개선	다음번을 위한 기억	무엇을 저장하고 다음번에 고칠 것인가?

진행 방식

아래 순서를 기본 흐름으로 사용한다.

1. Phase 0. 현재 상황 확인: 사용자의 목표, 경험 수준, 기존 파일을 확인한다.
2. Phase 1. 도메인 분석: 사용자의 일을 사람이 하는 절차로 풀어쓰면서, 작업 유형·기존 자료나 코드베이스·반복 작업·위험 지점·기존 하네스 충돌·숙련도를 읽는다. 결과는 적합성 게이트, 역할 후보, 사람 승인 지점의 입력이 된다. 자세한 항목은 references/harness-design-workflow.md의 도메인 분석을 따른다.
3. Phase 2. 산출물 정의: 마지막에 무엇이 나오면 성공인지 정한다.
4. Phase 3. 실행 모드와 Agent Team 패턴 선택: 단일 흐름, Subagent, Agent Team 중 적절한 모드를 고르고 순차, 병렬, 작성-검토, 감독형 등 협업 방식을 정한다.
5. Phase 4. Agent 설계: 누가 어떤 역할을 맡을지 정한다.
6. Phase 5. Skill 설계: 각 역할이 어떤 작업법을 따를지 정한다.
7. Phase 6. Orchestrator 설계: 작업 순서, 전달물, 실패 시 대응을 묶는다.
8. Phase 7. 테스트와 개선: 테스트 프롬프트와 개선 기록을 만든다.

자세한 단계별 질문과 산출물은 references/harness-design-workflow.md를 읽는다.

Phase 0에서는 신규 구축, 기존 확장, 운영/유지보수 중 어디에 해당하는지 먼저 나눈다.

상황	처리 방식
신규 구축	청사진을 만든 뒤 승인되면 전체 하네스를 구성한다
기존 확장	기존 Orchestrator, Agent, Skill, CLAUDE.md를 읽고 필요한 Phase만 다시 설계한다
운영/유지보수	drift, 중복, 누락 테스트, 오래된 포인터, 모델 향상으로 불필요해진 과잉 조각을 점검하고 개선 청사진을 제시한다

기존 확장에서는 오케스트레이터를 무조건 새로 만들지 않는다. 기존 Orchestrator가 있으면 팀 구성, Task 계약, 산출물 경로, description 후속 키워드를 갱신하는 방식을 먼저 검토한다. 변경 유형별로 다시 볼 Phase는 references/harness-design-workflow.md의 기존 확장 매트릭스를 따른다.

사용 경로

사용자의 요청은 의도에 따라 아래 경로로 처리한다.

• 의견, 구성, 방향을 물으면 설계 의견과 예시를 중심으로 답한다.
• "하네스 성숙도 진단", "내 업무가 하네스에 맞는지 봐줘"처럼 묻는 요청은 설계 카드와 성숙도 기준으로 진단한다. 이때 references/harness-design-workflow.md를 읽는다.
• "에이전트와 스킬을 만들어줘", "하네스를 만들어줘", "설계해줘", "구성해줘" 같은 기본 요청은 먼저 청사진을 만든다.
• "멋진 결과물로 만들어줘", "보기 좋게 정리해줘", "리포트로 만들어줘", "대시보드로 만들어줘"처럼 산출물 중심 요청이면 산출물 유형을 먼저 정하고, 필요한 경우 references/examples.md에서 가까운 예시를 읽는다.
• 청사진 응답을 시작할 때는 "청사진부터 만들겠습니다"처럼 자연스럽게 말한다. "이번에는 실제 파일을 만들지 않고" 같은 방어적인 표현은 쓰지 않는다.
• 청사진에는 하네스 7요소, 사람의 작업 절차, 산출물 계약, Agent 역할표, 역할 선정 이유, Skill 목록, Orchestrator 흐름, 테스트 프롬프트를 포함한다.
• 청사진 끝에는 "이 구조로 실행 가능한 하네스를 구성해드릴까요?"처럼 자연스러운 표현으로 사용자 승인을 요청한다.
• 직전 응답에서 청사진을 제시했고, 사용자가 "좋아", "진행해", "이 구조로 만들어줘", "실제로 사용할 수 있게 만들어줘"처럼 승인하면 실행 하네스 생성으로 넘어간다.
• 실행 하네스 생성 단계에서는 사용자가 내부 파일 구조나 스킬명을 직접 말하지 않아도 의도를 판단한다. 기존 .claude/agents, .claude/skills, CLAUDE.md를 확인한 뒤 필요한 Agent, Skill, Orchestrator Skill과 CLAUDE.md 포인터를 만든다.
• 실행 하네스 생성 단계에서 Agent Team이 필요하면 references/agent-design.md(역할·팀 패턴)와 references/orchestrator-design.md(실행 계약·흐름)를 읽고, 산출물 구조가 필요하면 references/orchestrator-design.md를 읽는다.
• Skill description·본문·progressive disclosure 설계가 필요하면 references/skill-authoring-guide.md를 읽는다.
• 기존 하네스 개선, 점검, 동기화, drift 확인을 원하면 먼저 현재 구조, 중복, 빠진 테스트, 오래된 규칙, CLAUDE.md 포인터 불일치를 점검한다. 이때 references/testing-qa-evolution.md를 읽는다.

Agent Team 실행 기준

실행 하네스는 Agent Team 구성을 기본 후보로 설계한다. Agent Team은 여러 역할이 같은 작업을 나눠 맡고, 서로 중간 발견을 주고받으며, 공유 작업 목록과 파일 산출물을 통해 진행하는 방식이다.

Agent Team으로 간주하려면 Agent 정의 파일만 있으면 안 된다. Orchestrator Skill 안에 팀 생성, 작업 등록, 메시지 규칙, 파일 산출물, 최종 통합, 팀 정리 절차가 있어야 한다. 구체적인 계약은 references/orchestrator-design.md를 따른다.

Agent Team을 쓰기 좋은 경우:

• Agent가 2개 이상이고 각자 보는 자료나 판단 기준이 다르다.
• 한 Agent의 발견이 다른 Agent의 작업 방향을 바꿀 수 있다.
• 생성자와 검토자가 실시간으로 피드백을 주고받아야 한다.
• 병렬 조사 뒤 합의된 최종 결과가 필요하다.
• 진행 상태와 의존 관계를 명확히 추적해야 한다.

Orchestrator Skill에는 팀 생성(TeamCreate) → 작업 등록(TaskCreate) → 상태 관리(TaskUpdate/TaskGet) → 발견·충돌 공유(SendMessage) → 각자 결과를 artifacts/에 저장 → Orchestrator가 통합하고 사람 승인 지점 확인 → TeamDelete 정리의 흐름을 담는다. 승인이 필요한 위험 행동(발송·제출·배포·삭제)은 실행하지 않고 팀 정리 후 사용자에게 승인을 요청한 뒤 멈춘다. 단계별 상세 계약은 references/orchestrator-design.md의 Orchestrator 실행 흐름을 따른다.

팀 재구성이 필요하면 이전 팀의 결과를 먼저 artifacts/에 저장한 뒤 팀을 정리하고 새 팀을 만든다. 대화 메시지는 조율에 쓰고, 다음 단계가 반드시 읽어야 하는 내용은 파일 산출물로 남긴다.

단일 Agent 또는 체크리스트 흐름은 예외다. 작업이 짧고, 다른 역할과 토론할 필요가 없고, 결과만 만들면 되는 경우에만 사용한다.

팀 규모는 작게 시작한다. 소규모 하네스는 2-3명, 중규모는 3-5명, 큰 작업도 보통 5-7명을 넘기지 않는다. 한 팀원이 맡는 Task는 3-6개 안에서 유지하고, 너무 많으면 Phase를 나누거나 팀을 재구성한다.

실행 하네스 구성 기준

실행 하네스를 만들 때는 아래 위치를 사용한다.

목적	위치	쉬운 비유
프로젝트 안내	CLAUDE.md	프로젝트 안내판
Agent 정의	.claude/agents/{agent-name}.md	팀원 역할 카드
작업 Skill	.claude/skills/{skill-name}/SKILL.md	작업 매뉴얼
결정적 검증 스크립트	.claude/skills/{skill-name}/scripts/	링크·숫자·섹션·금지어처럼 객관 점검을 코드로 거는 자동 채점기
Orchestrator Skill	.claude/skills/{harness-name}-orchestrator/SKILL.md	전체 진행표
산출물 지도	artifacts/README.md	어떤 결과가 어디에 있고 다음 실행이 무엇을 읽어야 하는지 알려주는 지도
중간 산출물	artifacts/ 또는 사용자가 정한 폴더	작업 기록지
최종 산출물	artifacts/final.md 또는 사용자가 정한 경로	사용자가 실제로 가져다 쓸 결과
개선 기록	artifacts/improvement-log.md 또는 CLAUDE.md 변경 이력	다음번에 하네스를 고칠 근거

CLAUDE.md에는 전체 실행 규칙을 길게 복사하지 않는다. 하네스 존재, 자연어 라우팅, 주요 위치, 변경 이력처럼 새 세션에서 길을 찾는 데 필요한 포인터를 둔다.

산출물 구조는 references/orchestrator-design.md를 따른다. 작은 하네스라도 입력, 중간 결과, 검토, 최종 결과, 개선 기록이 어디에 남는지 보여야 한다.

핵심 용어

처음 설명할 때는 아래 용어를 일상 언어로 먼저 풀어준다.

• Agent: 일을 맡은 팀원
• Skill: 팀원이 따르는 작업 매뉴얼
• Orchestrator: 일의 순서와 전달을 관리하는 팀장
• Test Prompt: 결과가 괜찮은지 확인하는 연습 문제
• Evolution: 실제로 써본 뒤 규칙을 고치는 회고
• Context Boundary: 같은 정보를 계속 함께 봐야 하는 일과 따로 떼어도 되는 일을 나누는 경계
• Harness Thickness: AI에게 자유를 더 줄지, 체크리스트와 검증으로 더 촘촘히 잡을지 정하는 두께
• Degrees of Freedom: 작업이 깨지기 쉬운 정도에 맞춰 지시 강도를 조절하는 것. 창작은 넓게, 결정적 단계는 "이대로 실행"으로 좁게
• Context Reset: 컨텍스트가 길어지면 요약으로 계속 이어붙이기보다, 다음 단계가 읽을 핸드오프 산출물을 남기고 깨끗한 컨텍스트로 다시 시작하는 것
• Handoff Artifact: 다음 단계나 다음 팀이 그대로 이어받도록 현재 상태, 결정, 남은 할 일을 적어 남기는 인수인계 파일
• ADR(설계 결정 기록): 큰 구조 결정 하나를 [결정 / 버린 대안과 이유 / 가정·트레이드오프 / 재검토 조건]으로 남기는 기록. 변경 이력이 "무엇이 바뀌었나"라면 ADR은 "왜 이렇고 무엇을 포기했나"를 담아 덜어내기 진단의 근거가 된다. 작성 형식은 references/testing-qa-evolution.md의 "개선 기록과 ADR 형식"을 따른다

참조 문서

필요한 경우에만 아래 문서를 읽는다.

• references/harness-design-workflow.md: 청사진 승인 게이트, 하네스 7요소, Phase 0-7, 성숙도, 설계 카드, 하네스 두께가 필요할 때
• references/agent-design.md: Agent frontmatter·모델 선택·빌트인, 실행 모드, 팀 패턴, Agent 파일 구조, 생성자-평가자·반복합의 패턴이 필요할 때
• references/orchestrator-design.md: Orchestrator 실행 계약·흐름·Task·데이터 전달·에러, 청사진·artifacts/ 산출물 템플릿, Orchestrator·CLAUDE.md 템플릿이 필요할 때
• references/skill-authoring-guide.md: Skill description, workflow, output format, examples, progressive disclosure 기준이 필요할 때
• references/testing-qa-evolution.md: 테스트, with/without 하네스 A/B 비교, 벤치마크 두께 선택, 벤치마크 결과 저장, near-miss 트리거 검증, QA, assertion, drift, 유지보수, 개선 기록이 필요할 때
• references/examples.md: 일상 업무와 사업계획서 예시가 필요할 때

품질 기준

• 설명은 "왜 필요한가"를 먼저 말하고 "어떻게 만드는가"로 이어간다.
• 초보자에게는 용어보다 결과물 흐름을 먼저 보여준다. "Agent 4개를 만들겠습니다"보다 "조사, 작성, 검토, 최종 정리를 나눕니다"처럼 말한다.
• 사용자가 원하는 결과물이 흐릿하면 최소 질문으로 목적, 독자, 최종 형태를 확정한다.
• 산출물은 보기 좋을 뿐 아니라 실제로 쓸 수 있어야 한다. 검증 기준에는 내용 정확성, 누락 정보, 사용 가능성, 사람 승인 지점을 포함한다.
• 한 번에 너무 많은 에이전트를 만들지 않는다. 첫 실습은 보통 3-4개 역할이 적당하다. 다만 문서 작성, 프로젝트 운영, 제출 준비처럼 흐름이 긴 작업은 5-7개까지 허용하되, 왜 별도 역할인지 설명한다.
• Agent를 별도로 만들기 전에는 네 가지를 확인한다: 입력과 출력이 독립적인가, 다른 전문성이 필요한가, 반복해서 다시 쓰일 책임인가, 빠지면 품질이나 안전에 큰 문제가 생기는가. 답이 약하면 새 Agent 대신 Orchestrator 단계나 체크리스트로 둔다.
• 각 Agent에는 책임, 입력, 출력, 하지 말아야 할 일을 포함한다.
• 각 Agent frontmatter에는 name, description, tools, model을 역할에 맞춰 정한다. model은 작업의 추론 깊이로 고른다 — 규칙기반·정적·추출은 haiku, 의미 해석·분석·리뷰는 sonnet(대부분의 기본), 상충 해소·구조 판단·설계·리팩토링은 opus, 장시간 자율·다단계 검증은 fable. 전 에이전트 opus(과지출)도 무조건 생략(티어 무시)도 피하고, 균형 작업이면 sonnet 또는 생략(=inherit)한다. frontmatter에 type 필드는 없으며 빌트인 타입(general-purpose/Explore/Plan)은 subagent_type로 지정하되 빌트인이라도 .claude/agents/{name}.md 파일을 만들고 prompt에 역할을 inline하지 않는다. tools는 최소 권한으로 둔다. 자세한 루브릭은 references/agent-design.md의 Agent 모델 선택을 따른다.
• Agent frontmatter name은 소문자 영문과 하이픈을 사용하고, 파일명 및 Orchestrator의 호출 이름과 일치시킨다.
• Skill의 호출 이름은 .claude/skills/{directory} 디렉터리명을 기준으로 정해진다. frontmatter name을 쓴다면 표시 이름으로만 생각하고 디렉터리명과 충돌하지 않게 맞춘다. Skill과 Agent의 description은 소개문이 아니라 "무엇을 + 언제"를 3인칭으로 담는다.
• 생성하는 SKILL.md 본문은 500줄 미만으로 두고, 넘으면 세부를 references/로 빼고 포인터만 남긴다. 참조는 한 단계 깊이로, 100줄 넘는 참조에는 목차를 둔다.
• Task를 위임할 때는 목표·출력 형식·도구/출처·경계 네 가지를 모두 담는다. 모호한 한 줄 위임은 중복과 누락을 만든다.
• 파일 산출물을 맡기는 Agent에는 그 파일을 만들 Write 권한이 있는지 먼저 확인한다. 검토·QA처럼 "대상 수정 금지" 역할도 자기 판정 파일을 쓰려면 Write가 필요하다(최소 권한 = 쓰기 금지가 아니라 쓰기 대상 한정). 위임에는 저장 계약을 명시한다: 지정 경로에 저장, 실패 시 재시도 후 차단 보고, 저장한 척 본문 요약으로 대체 금지. 권한과 산출물이 어긋나면 저장 실패나 헛보고가 난다.
• 각 Skill에는 트리거, 절차, 산출물 형식, 품질 체크를 포함한다.
• Orchestrator에는 작업 순서, 파일 기반 산출물 계약, 실패 시 재시도 또는 사람 확인 조건을 포함한다.
• Agent Team 하네스의 Orchestrator에는 팀 구성, 작업 등록, 팀원 간 메시지 규칙, 파일 산출물 경로, 팀 정리 조건을 포함한다.
• Agent Team 하네스의 Orchestrator에는 TaskUpdate와 TaskGet을 통한 진행 상태 확인, 지연 감지, 작업 재할당 기준을 포함한다.
• Agent 파일에는 팀 안에서 어떤 메시지를 받고 보내는지, 어떤 산출물을 어디에 남기는지 적는다.
• 결과물을 만든 Agent가 자기 결과를 합격 처리하지 않는다. 생성과 평가를 분리하고, 위험도가 높으면 결과물과 합격 기준만 보는 별도 평가 Agent를 둔다. 평가 역할은 통과·탈락 예시로 기준을 고정해 회의적으로 튜닝하고, 자기평가 편향(스스로의 결과를 과대평가함)을 전제로 설계한다. 자세한 기준은 references/agent-design.md의 생성자-평가자 분리를 따른다.
• 평가자의 판정은 가능하면 외부 신호(테스트·체크리스트·결함 주입 회귀 세트·사람 승인)에 묶는다. 순수 자기평가만으로는 품질이 떨어질 수 있다. 통과까지 반복하는 검증 루프를 쓰면 종료 계약(통과·횟수 상한 2~3회·수렴 정체·예산)과 미통과 시 사람 승인 에스컬레이션을 함께 두고, 라운드가 품질을 떨어뜨리면 best로 롤백한다. 자세한 기준은 references/agent-design.md의 반복·합의·자기비판 패턴을 따른다.
• QA 또는 Reviewer Agent를 만들 때는 존재 확인보다 경계면 교차 검증을 우선한다. QA는 전체 완료 후 한 번만 실행하지 말고, 위험한 중간 산출물이나 모듈이 끝난 직후 점진적으로 실행하도록 설계한다. 필요한 경우 references/testing-qa-evolution.md를 읽는다.
• 실행 하네스의 Orchestrator는 artifacts/ 존재 여부를 먼저 확인하고, 기존 산출물이 있으면 초기 실행, 부분 재실행, 새 실행 중 하나로 분기하도록 만든다.
• Orchestrator는 부분 재실행 뒤 artifacts/README.md의 파일 상태와 승인 상태를 함께 갱신한다. 최종 산출물을 다시 만들지 않았다면 파일 상태는 stale 또는 needs-review로, 승인 상태는 필요에 따라 사람 승인 필요로 표시한다.
• 중간 산출물은 다음 단계가 바로 읽을 수 있는 파일명과 형식을 가져야 한다. "초안 작성", "검토"처럼 대화로만 지나가는 단계는 실행 하네스로 보지 않는다.
• HTML 시각 리포트를 만들 때는 artifacts/{name}.html처럼 명확한 최종 경로를 정하고, TailwindCSS를 쓰는 경우 카드·표·배지·경고 블록의 정보 구조를, Chart.js를 쓰는 경우 차트 데이터와 원본 산출물의 숫자 일치 여부를 검증 기준에 포함한다.
• 단일 HTML 산출물은 브라우저에서 직접 열어 볼 수 있어야 하며, 모바일 폭에서 텍스트 겹침, 표 넘침, 차트 깨짐이 없는지 확인하도록 안내한다.
• .claude 파일을 만들면, 자연어 요청 예시를 먼저 남기고 필요한 경우 직접 호출 예시를 함께 남긴다.
• 실행 하네스를 만들면, 생성된 파일의 역할을 팀원 카드, 작업 매뉴얼, 전체 진행표, 프로젝트 안내판처럼 일상 언어로 함께 설명한다.
• 특정 Agent가 특정 Skill을 항상 따라야 한다면 Agent 본문과 Orchestrator 흐름에 그 Skill 사용 조건을 적는다. skills frontmatter는 직접 Subagent로 호출할 때의 보조 설정으로만 제안하고, Agent Team 실행의 필수 전달 수단으로 보지 않는다.
• 결정적으로 검증 가능한 항목(링크 유효성, 숫자·합계 일치, 필수 섹션 존재, 금지어, 형식 규칙)은 LLM 검토에 맡기지 말고 scripts/의 자동 체크로 빼고, LLM 검토는 논리·톤·사실성처럼 판단이 필요한 영역에 집중시킨다. 객관 항목을 LLM에 맡기면 거수기 검증이 되기 쉽다. 단, 모든 하네스가 scripts를 만들 필요는 없다 — 반복되는 객관 점검이 있을 때만 둔다.
• 테스트는 최소 3개를 만든다: 정상 사례, 애매한 사례, 실패하기 쉬운 사례. 실무용 하네스라면 부정 테스트와 반복 테스트도 제안한다. 하네스에 결정적 검증·점검 단계가 있으면 결함 주입 회귀 테스트를 선택이 아니라 기본으로 넣어, 일부러 망가뜨린 입력을 그 단계가 실제로 잡는지 확인한다(거수기 검증 방지).
• 하네스의 가치를 증명할 때는 먼저 벤치마크 두께를 light, targeted, full 중에서 고른다. 작은 하네스는 대표 프롬프트 1개로 가볍게 비교하고, 큰 프로젝트는 전체 with/without 실행보다 바뀐 Phase, 핵심 산출물, 위험 지점만 비교하는 targeted를 우선한다. 비교 결과는 artifacts/evals/iteration-N/{eval-name}/ 아래에 저장하고, 완료 알림의 토큰·시간은 그 자리에서 기록한다. 양쪽에서 항상 통과하는 검증 항목은 차별력이 없으므로 더 도전적인 항목으로 바꾼다.
• Skill과 Orchestrator description은 should-trigger 8-10개와 should-not-trigger 8-10개로 검증하되, 명백히 무관한 문장이 아니라 경계가 애매한 near-miss와 기존 Skill 트리거 충돌에 집중한다.
• 검증 시 .claude/commands/를 생성하지 않았는지 확인한다. 이 하네스는 Agent, Skill, Orchestrator, CLAUDE.md, artifacts/를 기준으로 구성한다.
• 하네스 두께는 위험도에 맞춘다. 위험도가 곧 켜지는 검증과 사람 승인의 양이다. 개인 메모·아이디어는 얇게, 외부 발송·제출·결제·삭제·법적 표현·개인정보는 검증과 사람 승인을 두껍게 둔다.
• 하네스는 두꺼워지기만 하지 않는다. 점검할 때 각 Agent·Skill·검증이 "모델이 혼자 못 하는 것"을 채우는지 묻고, 모델이나 업무가 좋아져 불필요해진 조각은 하나씩 빼며 품질 영향을 확인해 제거 후보로 표시한다. 토큰만 쓰고 품질에 기여하지 않는 조각은 줄인다. 각 조각에 ADR(가정·재검토 조건)이 남아 있으면 그것을 기준으로 제거 여부를 판단한다.
• 실행 하네스를 구성한 직후에는 references/testing-qa-evolution.md의 하네스 테스트 체크리스트로 자가 점검한다. 커맨드 미생성, frontmatter와 이름 정합성, 모델 정합성(각 Agent의 model이 역할 루브릭과 맞고 한 팀이 전부 같은 모델은 아닌지), 산출물 지도, 승인 게이트의 능동 동작을 함께 확인한다.
• 자잘한 변경은 CLAUDE.md나 별도 개선 기록의 변경 이력에 날짜·변경 내용·대상·사유로 남긴다. 단, 큰 구조 결정(Agent Team vs 단일 흐름, 두께, 패턴 선택, 역할 분리)은 한 줄 사유로 끝내지 말고 ADR로 남긴다: 결정 / 버린 대안과 이유 / 가정·트레이드오프 / 재검토 조건. 변경 이력은 시간 순 추적, ADR은 결정의 근거로 역할이 다르므로 함께 쓴다.
• 개선 요청은 기록으로 끝내지 않는다. 사용자가 원하면 개선 기록을 읽어 .claude/agents와 .claude/skills에 반영하고, 변경 내용은 CHANGELOG.md 같은 변경 이력에 남기도록 제안한다.
• 마지막에는 사용자가 자기 일에 적용할 수 있는 작은 다음 행동을 제안한다.

피해야 할 것

• 하네스가 모든 문제의 정답인 것처럼 설명하지 않는다.
• 생성된 파일을 검토 없이 정답처럼 제시하지 않는다.
• Phase 번호, 명령 이름, 버전 설명을 문서마다 다르게 쓰지 않는다.
• 처음부터 디렉터리 구조와 YAML만 보여주지 않는다.
• 단순한 일에 에이전트를 과하게 늘리지 않는다.
• Skill description을 소개문처럼 흐리게 쓰지 않는다.
• CLAUDE.md에 모든 Agent와 Skill의 세부 규칙을 중복해서 붙여 넣지 않는다.
• 사람이 승인해야 할 외부 발송, 제출, 결제, 삭제, 배포를 자동 완료처럼 설계하지 않는다.
• 승인이 필요한 지점에서 사용자에게 묻지 않고 라벨만 붙이거나 암묵적으로 통과하지 않는다. 승인은 명시적으로 요청하고 답을 받은 뒤 진행한다.