전문가 팀 만들기 — 하네스가 바꾸는 것

이 차시에서 준비할 것

에이전트 팀 기능이 켜져 있는지 새 터미널에서 확인하세요. 1 이 나와야 합니다.

echo $env:CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

이 차시에서 처음 나오는 말

이 차시에서 배우는 것

• 단일 프롬프트와 전문가 팀의 차이를 결과물 네 지점에서 직접 확인한다
• 그 차이가 중간 산출물에서 왔다는 것을 파일로 확인한다
• 내 업무의 전문가 팀을 직접 만들어 파일로 남긴다

1. 실험 조건 — 모르는 분야의 문서를 써야 한다면

입력은 나라장터에 실제로 올라온 과업지시서 1건입니다. 국가통합바이오빅데이터 사업의 병원 진료기록 연계 구축 건이고, 문서에는 이런 단어들이 이름만 나옵니다.

FHIR · KCD-8 · 심평원 EDI · 가명화 · ETL

보건의료 데이터를 모르는 사람이 이 문서로 제안서를 써야 합니다. 이것이 실험 조건입니다. 여러분도 업무에서 비슷한 상황을 겪습니다 — 낯선 부서의 요청, 처음 보는 규격, 이름만 아는 제도.

2. 결과 비교 — 차이가 남는 네 지점

두 결과물은 이미 저장소에 들어 있습니다. 직접 열어 비교합니다.

cd C:\harness-edu\harness; claude

cd ~/harness-edu/harness && claude

제안서A_단일패스.docx 와 제안서B_하네스.docx 를 둘 다 읽고,
아래 네 항목에서 무엇이 다른지 표로 비교해줘. 쪽수 말고 내용으로 비교해줘.

1. 배경지식 (모르는 분야를 어떻게 다뤘나)
2. 요구사항 대응 (빠뜨린 것이 있나)
3. 계약 조건 조항 대응
4. 검증 가능성 (숫자로 확인 가능한 약속이 있나)

한 줄 요약 — A는 과업지시서를 요약한 제안서, B는 과업지시서에 응답한 제안서.

2-2. 차이의 근원은 문장이 아니라 파일 하나

B의 모든 우위는 어디서 왔을까요? 더 좋은 문장을 써서가 아닙니다. 중간에 만든 파일 하나에서 나왔습니다. 직접 열어 봅니다.

artifacts/요구사항_인벤토리.md 를 읽고,
이 파일이 무엇을 정리한 것인지, 항목이 몇 개인지 알려줘.
그리고 이 파일이 없었다면 제안서에서 무엇이 빠졌을지 설명해줘.

REQ-01 ~ REQ-11   기능 요구사항 11건
DOM-01 ~ DOM-13   도메인 지식 항목 13건
CON-01 ~ CON-07   계약 조건 7건
DEL-01 ~ DEL-04   산출물 4건

이 지루한 작업 — 전부 뽑아서 번호를 붙이는 일 — 하나가 뒤의 모든 것을 만들어 냅니다.

2-3. 검증자 분리 — 잘 쓰는 것과 빠뜨리지 않는 것은 다른 능력

조건 조항 7건이 A에서 빠진 이유는 더 노력하지 않아서가 아닙니다. 글을 쓰는 사람의 시선으로는 계약 조건이 눈에 잘 안 들어옵니다.

하네스 4원리 중 네 번째 — 검증자는 분리한다
만든 주체가 자기 결과를 최종 승인하지 않습니다. 여러분이 만들 모든 팀에 검증 담당 한 명을 반드시 넣으세요.

2-4. A가 이기는 경우도 압니다

내부 검토용 초안, 참고용 요약이라면 A의 속도가 정답입니다. 하네스는 "조항 하나를 빠뜨리면 탈락하는" 고부담 문서에서 정당화됩니다. 3차시에서 배운 "이 일은 몇 단계짜리인가" 판단이 여기서 다시 쓰입니다.

3. 하네스의 구성물 열어 보기

트랙 B를 가능하게 한 파일들이 harness/ 폴더에 그대로 들어 있습니다. 무엇이 들어 있는지 봅니다.

이 폴더의 CLAUDE.md 와 .claude/agents/, .claude/skills/ 를 훑어보고,
각 파일이 무슨 역할인지 한 줄씩 정리해줘.

3-1. 담당자 다섯 명은 각각 무엇을 하나

3-2. 2차시에서 만든 용어집이 여기서 "스킬"이 됩니다

도메인 전문가가 똑똑해서 코드 전환표를 아는 게 아닙니다. medical-data-standards 스킬 파일에 사전이 들어 있어서 가능합니다. 그리고 그 사전은 다음 의료 사업에서 그대로 재사용됩니다.

2차시: 용어집을 파일로 → 결과가 안정됨
4차시: 그 파일을 특정 담당자에게 쥐여 줌 → 그 담당자가 전문가가 됨
이것이 Skill과 Agent의 결합입니다.

3-3. 팀을 짜는 여섯 가지 모양 (이름만 알아 두기)

팀 구조에는 정해진 패턴이 있습니다. 외울 필요는 없습니다 — 하네스 플러그인이 일에 맞는 모양을 골라 줍니다. 다만 결과물을 볼 때 "아, 이 모양이구나" 알아보면 좋습니다.

4. 사례 — 광고 AE의 전문가 팀

1차시부터 따라온 정하늘 대리가 자기 업무의 하네스를 만든 과정입니다. 프롬프트와 결과, 그리고 무엇을 고쳤는지까지 그대로 봅니다.

하네스 구성해줘.

도메인: 광고대행사 AE의 디지털 캠페인 주간 성과 보고.
      화장품 브랜드 1개, 5개 매체(네이버GFA·카카오모먼트·메타·구글애즈·틱톡) 운영.
입력: 매체별 성과 파일(엑셀/CSV) 5개, 지난주 리포트, 캠페인 목표(월 ROAS 350%)
산출물: 광고주 제출용 주간 요약 1장 + 이슈·다음 행동 목록
품질 기준: 숫자는 원본과 100% 일치, 매체별 용어는 사내 표준으로 통일,
         이슈는 하나도 빠지면 안 됨, 지난주 대비 증감이 반드시 포함될 것

에이전트는 3~5명으로 하고, 결과를 대조 검증하는 담당을 반드시 포함해줘.

매체별로 나뉜 담당 5명을 "데이터 정규화 담당" 1명으로 합쳐줘.
매체가 달라도 하는 일(용어 통일·VAT 환산·컬럼 매핑)이 같아.

그리고 수치 검증을 리포트 작성 담당이 겸하지 않게 분리해줘.
검증 담당은 원본 파일과 리포트를 항목별로 대조하고,
불일치나 누락을 찾으면 해당 담당자를 지목해 수정 요청하도록 정의해줘.

my-harness/
├ CLAUDE.md                        프로젝트 불변 규칙 (수치 불변·추측 금지)
└ .claude/
   ├ agents/
   │  ├ data-normalizer.md         5개 매체 데이터 정규화
   │  ├ performance-analyst.md     지표 계산·증감 분석
   │  ├ issue-planner.md           이슈 정리·다음 행동 제안
   │  ├ report-writer.md           광고주용 1장 집필
   │  └ qa-checker.md              수치 대조·누락 검증
   └ skills/
      └ media-glossary/            (2차시 용어집이 들어갈 자리)

4-1. 직접 해보기 — 준비된 데이터로

사례를 읽는 것만으로는 감이 안 옵니다. 정하늘 대리와 같은 데이터로 직접 팀을 만들어 보세요. 실습 저장소에 ad/ 폴더로 준비되어 있습니다.

파일 10개를 열어 컬럼명을 맞추고, VAT를 나누고, 목적별로 전환을 걸러내고, 캠페인 18개를 집계하고, 전주 대비까지 계산하는 일입니다. 손으로 하면 두 시간이 넘습니다 — 팀을 만들 이유가 있는 규모입니다.

① 작업 폴더를 만들고 데이터를 넣습니다

하네스를 만들 폴더(my-harness)를 만들고, 그 안 input/ 에 데이터를 복사합니다. 원본은 그대로 둡니다.

mkdir C:\harness-edu\my-harness\input -Force
Copy-Item C:\harness-edu\ad\data\*.csv C:\harness-edu\my-harness\input\
Copy-Item C:\harness-edu\ad\매체_표준용어집.md C:\harness-edu\my-harness\
cd C:\harness-edu\my-harness
dir

mkdir -p ~/harness-edu/my-harness/input
cp ~/harness-edu/ad/data/*.csv ~/harness-edu/my-harness/input/
cp ~/harness-edu/ad/매체_표준용어집.md ~/harness-edu/my-harness/
cd ~/harness-edu/my-harness
ls

input
매체_표준용어집.md

② 이 폴더에서 Claude Code를 실행합니다

claude

③ 하네스를 만듭니다 — 데이터 위치까지 알려 줍니다

하네스 구성해줘.

도메인: 광고대행사 AE의 디지털 캠페인 주간 성과 보고.
      화장품 브랜드 1개, 5개 매체(네이버GFA·카카오모먼트·메타·구글애즈·틱톡) 운영.
입력: input/ 폴더의 매체별 성과 CSV 10개 (2주치, 252행, 캠페인 18개).
     매체마다 컬럼명·날짜 형식·VAT 기준이 다르고, 메타는 캠페인 목적에 따라
     Results 컬럼의 의미가 달라짐. 판단 규칙은 매체_표준용어집.md 에 정리돼 있음.
산출물: 광고주 제출용 주간 요약 1장 + 이슈·다음 행동 목록 (전주 대비 증감 포함)
품질 기준: 숫자는 원본과 100% 일치, 매체별 용어는 용어집 기준으로 통일,
         이슈는 하나도 빠지면 안 됨, CPA·ROAS는 반드시 재계산

매체_표준용어집.md 를 이 하네스의 스킬로 넣어줘.
에이전트는 3~5명으로 하고, 결과를 대조 검증하는 담당을 반드시 포함해줘.

④ 만든 팀을 바로 돌려 봅니다 (선택 — 시간이 되면)

방금 만든 팀으로 input/ 데이터를 처리해서 이번 주(W3) 주간 리포트를 만들어줘.

이 폴더는 7차시(내 하네스 만들기) 에서 다시 씁니다. 지우지 마세요.

5. 스스로 점검

• A와 B의 차이를 중간 산출물이라는 말로 설명할 수 있다
• "잘 쓰는 것과 빠뜨리지 않는 것은 다른 능력" 의 뜻을 안다
• 하네스가 정당화되지 않는 경우도 말할 수 있다
• 내 도메인 에이전트가 생성되었고 역할을 한 줄씩 말할 수 있다
• 팀에 검증 담당이 포함되어 있다
• 생성된 파일이 어디 있는지 안다

흔한 실패와 대처

6. 더 해보기 (선택)

• 평가위원 롤플레이 — 새 대화에서 AI에게 조달 평가위원 역할을 주고 A·B를 4개 항목으로 채점시켜 보세요. 점수 차가 어느 항목에서 벌어지는지 보면 하네스의 효과 지점이 분명해집니다.
• 인벤토리 파괴 실험 — 요구사항 인벤토리에서 조건(CON) 부분을 지우고 다시 돌려 보세요. 검증자가 원문 대조로 이를 잡아내는지가 하네스 견고성의 시험대입니다.
• 원본 교안 — harness/README.md 에 실험 설계와 심화 과제가 더 있습니다.

7. 다음 차시

깨끗하게 정리된 데이터로는 팀이 잘 돕니다. 그런데 실무 데이터는 깨끗하지 않습니다. 5차시에서는 15,144건짜리 지저분한 공공 데이터에 같은 방법을 적용해 보고, 처리 규칙을 스펙으로 못 박습니다.