문제: 소유자는 두 템플릿에 분야별 전문가 서브에이전트·스킬과 리드
역할, 협업 매뉴얼을 넣으라고 했다. 지금 하네스는 장치의 자리만 있고
분야 지식과 분야 사이 협업 규칙이 없다. 무엇을 어떤 장치로 둘지
근거가 필요하다.
고른 방법:
- 조사 기록(docs/research/2026-11-11-harness-v2.md): 공식 문서 14쪽,
Anthropic 글 25편, 제작자 발언 13건(Cherny·Wu·Hollman·Shihipar 등),
공개 repo 6곳, 2차 3건, 이 기계 실측. 격차 표 17행.
- 설계(docs/experts.md): 분야 전문가는 paths를 건 지식 스킬(함정 → 점검표
→ 검증 순서), 서브에이전트는 분야가 아니라 일마다(렌즈를 받는 새 눈
reviewer 하나 + 있는 실행 검증), 리드는 메인 세션. 공용(플러그인)은
협업 장치만, 분야 지식은 각 템플릿에.
- 버린 대안: 분야마다 서브에이전트(첫 초안, 템플릿당 9개). Anthropic
2026-10-22·2026-01-23·2026-04-07 글과 현행 best practices가 분야·역할
분리를 반대하고, 에이전트 설명은 모든 세션과 서브에이전트마다 다시
든다. agent teams는 실험 기능이고 팀원에 skills가 실리지 않는다.
- docs/README.md에 이 repo에서 새로 정한 것 셋(12~14)을 더한다.
위험: 소유자 요청("분야별 서브에이전트")과 다르다. 이유를 설계 0절에
밝히고 평가(7절)에서 렌즈 리뷰어가 v1보다 못하면 다시 시험한다.
paths 스킬이 목록에서 빠지는 것은 CLI 바이너리 문자열로만 확인했다.
검증: 문서만. 링크와 출처 번호를 손으로 대조했다.
30 KiB
하네스 v2 조사 — Claude Code를 만든 사람들이 끝까지 쓰는 법
- 조사일: 2026-11-11 · 쓰는 곳: 설계
docs/experts.md의 근거(S#)와 격차(G#) - 방법: 공식 문서는 원문을 받아 읽었다. 블로그·repo는 원문을 받아 숫자를 원문 문자열과 대조했다(서브에이전트 넷에 나눠 맡기고, 결정에 쓴 주장은 이 세션에서 다시 열었다). 이 기계에서 직접 잰 것은 [실측]이다.
- 표시: [1차] Anthropic이 쓴 것이나 repo 파일 자체 · [2차] 남이 정리한 것 · [실측] 이 기계 · [미확인] 받지 못함
- 인용은 출처마다 짧게 하나 이하로 두고, 나머지는 우리말로 요지만 적었다.
1. 결론 — 조사가 설계를 바꾼 곳
| 처음 생각 | 조사 뒤 | 근거 |
|---|---|---|
| 분야마다 판정 서브에이전트(백엔드·프론트 각 9개) | 분야 전문가는 지식 스킬이고, 서브에이전트는 일마다(새 눈 리뷰 하나 + 실행 검증) | S26·S28·S29·S38: 분야·역할 분리는 조직도를 닮고, 조정에 토큰을 더 쓰고, 위임을 흔든다 |
| 전문가 스킬은 모델 호출형으로 목록에 | paths 지식 스킬: 그 파일을 만지기 전에는 목록에 없다 |
S1(목록 예산 1%), S13(지금 목록 33,093자), S12(CLI가 paths 스킬을 따로 둠) |
| 스킬 본문은 점검표부터 | 함정이 맨 앞, 그다음 검증 명령 | S30: 함정 절이 가장 쓸모 있고 검증 스킬이 품질에 가장 크게 효과. S9: 압축 뒤 스킬 앞부분만 다시 붙음 |
| High 발견은 리드가 다시 본다 | 반증해서 살아남은 것만(리드 직접 또는 "틀렸음을 보여라" 서브에이전트) | S15(code-review·claude-security), S27(Claude Code 팀 투표) |
| 리뷰-수정 반복은 발견 0까지 | 세 번까지, 두 번째부터 고친 diff만 | S27: 작성·리뷰 에이전트가 한 PR에서 50번 넘게 돎 |
| 전문가끼리 통신(agent teams) | 리드를 거치는 넘김 한 번 | S3·S4: 실험 기능, 대화형만, 팀원에 skills 미적용, 약 7배 토큰. S29: 서브에이전트는 서로 대화 못 함 |
평가는 claude plugin eval |
그 도구가 맞지만 이 기계는 헤드리스 인증이 없다 → 서브에이전트로 판을 흉내 내고 장부 eval 줄로 |
S7, [실측] claude auth status loggedIn false, desktop에 claude 없음 |
2. 출처 표
2.1 공식 문서 [1차] (날짜 표시 없음, 2026-11-11 열람 기준 현행)
| # | 문서 | 이 설계에 쓴 사실 |
|---|---|---|
| S1 | Skills | 목록 예산 = 컨텍스트 창의 1%(skillListingBudgetFraction), 넘치면 덜 쓰는 스킬부터 설명을 지움. description+when_to_use 1,536자에서 자름. paths는 맞는 파일을 다룰 때만 자동 로드. context: fork, disable-model-invocation, skillOverrides(플러그인 스킬엔 안 먹음), /skill-doctor |
| S2 | Sub-agents | 설명은 메인 컨텍스트에 늘 있다(내장 제외 합 15,000토큰 넘으면 시작 경고). frontmatter 전 목록(skills는 시작 때 본문 전부 주입, memory, isolation: worktree, background, effort, maxTurns…). 중첩 기본 3단계. 재개는 SendMessage. 같은 이름이면 managed > CLI > project > user > plugin. 플러그인 에이전트는 hooks·mcpServers·permissionMode 무시 |
| S3 | Agent teams | 실험 기능(CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1), 리드·팀원·공유 작업 목록·메일함. 대화형만, 팀 하나, 중첩 불가, 팀원에 정의의 skills 미적용. 팀원 3~5명 권장 |
| S4 | Costs | 계획 모드 팀원이 있으면 일반 세션의 약 7배 토큰. 장황한 일은 서브에이전트로, 지침은 스킬로 옮겨 줄이라고 권함 |
| S5 | Memory | CLAUDE.md가 있으면 AGENTS.md는 안 읽힘(그래서 @AGENTS.md). 파일당 200줄 아래. @import는 비용을 줄이지 않음. .claude/rules/의 paths. /doctor prompt-audit |
| S6 | Plugins — measure | claude plugin details의 always-on = 스킬·에이전트·명령의 이름+설명. 훅·MCP는 셈에서 빠짐 |
| S7 | Plugin evals | claude plugin eval: 기본 3회, with/without 두 팔과 Δ, 채점기 6종(regex·tool_used·tool_order·file_exists·llm·baseline), --max-cost-usd |
| S8 | Prompt caching | 바뀌지 않는 것이 앞. 스킬 호출은 메시지로 들어가 캐시를 안 깬다. 플러그인의 스킬·에이전트·훅 켜고 끄기는 캐시 유지, MCP 추가는 무효화. 모델 바꾸면 캐시 전부 |
| S9 | Context window | 압축 뒤 호출한 스킬은 스킬당 5,000토큰, 합 25,000토큰까지 다시 붙음(오래된 것부터 버림) |
| S10 | Features overview | "지시는 요청이지 보장이 아니다" → 꼭 지킬 것은 훅. 스킬 이름 충돌은 managed > user > project |
| S11 | Skill authoring best practices | 설명 1,024자, 본문 500줄 아래, 참조는 한 단계, 평가를 문서보다 먼저(시나리오 3개), Haiku·Sonnet·Opus에서 시험 |
| S23 | Prompting best practices | 최신 모델은 서브에이전트를 과하게 쓰는 경향. "CRITICAL/MUST" 같은 강조는 과다 호출을 낸다. 역할 한 문장은 권함 |
| S38 | Best practices | 결정적 지시(훅·권한)와 비결정적 지시(CLAUDE.md) 구분, 검증 수단을 줄 것, "같은 일을 넘긴다고 답이 나아지지 않는다", 옛 조언 목록(서브에이전트로 컨텍스트 보호하기 등) |
| S43 | Dynamic workflows | 계획을 코드(스크립트)로 옮겨 서브에이전트를 크게 돌리는 장치. 사용자가 고를 때 돈다 |
2.2 Anthropic 블로그·글 [1차] (최신순)
| # | 날짜 | 글 | 이 설계에 쓴 주장 |
|---|---|---|---|
| S39 | 2026-11-09 | Safely scaling multi-agent teams | 리드 1 + 헬퍼 999가 SQL·git으로만 조정. 헬퍼들은 어려운 일을 "불가"로 잘못 판정하기 쉽다(60개 중 47개). 작업이 독립 파일로 쪼개지는 극단적 경우 |
| S44 | 2026-11-06 | Components of agent memory | 기억의 맨 위 층은 작게. 여러 에이전트가 한 문서를 동시에 고치면 사실이 사라진다(57개 중 41개만 남음) → 한 파일 한 주인 |
| S26 | 2026-10-22 | When to fold subagents into your main agent loop | 스킬을 가진 단일 에이전트가 서브에이전트 설계보다 자주 품질이 높고 싸다. 팀·문제 유형마다 서브에이전트를 두면 구조가 조직도를 닮는다. 남길 조건 셋: 측정된 컨텍스트 비대, 버려도 되는 병렬, 도구 선택 실패·지시 충돌. 골든 예제 10개로 eval 시작, 여러 번 돌려라 |
| S27 | 2026-10-15 | How the Claude Code team does code review | 새 컨텍스트 서브에이전트가 diff 리뷰. 여러 에이전트가 찾고 다른 묶음이 투표해 동의할 때만 게시, 스타일 발견은 버림. 영역별 REVIEW.md(실패가 어떤 모습인지, 잔소리 상한, 증거 요구, 고칠 것 없으면 그렇다고). 작성·리뷰 에이전트가 50라운드 넘게 돎 → 상한 3, diff만 재리뷰. Cherny: 검증 수단이 결과를 2~3배 |
| S41 | 2026-09-28 | Automating eval design and hillclimbing | 루브릭은 1~5 척도가 아니라 확인 가능한 주장으로, 정답은 손 밖에, train/test 분리 |
| S34 | 2026-07-24 | New rules of context engineering for Claude 5 | 시스템 프롬프트를 80% 넘게 지워도 코딩 eval 손실 없음. 원인은 층끼리 부딪치는 지시. CLAUDE.md는 함정 위주 |
| S25 | 2026-06-18 | Steering Claude Code | 층마다 컨텍스트 비용과 강제력을 맞바꾼다. 절차는 스킬, 예외 없는 규칙은 훅·권한 |
| S30 | 2026-06-03 | How we use skills(Thariq Shihipar) | 사내 스킬 수백 개가 9개 범주로 묶임. 검증 스킬이 품질에 가장 크게 효과. 함정 절이 가장 신호가 큼. 설명은 요약이 아니라 트리거 조건. repo에 스킬을 넣으면 모두의 컨텍스트가 는다 |
| S42 | 2026-04-10 | Multi-agent coordination patterns | 검증자는 기준만큼만 좋다 |
| S29 | 2026-04-07 | How and when to use subagents | 파일 10개 넘는 조사·독립 작업 3개 이상이면 신호. 설명은 능력이 아니라 트리거. 로스터가 크면 위임이 흔들림, 대부분 팀은 몇 개로 정착. 서브에이전트끼리 대화 못 함 |
| S46 | 2026-04-30 | Prompt caching is everything | 세션 중 도구·모델 바꾸지 않기, 갱신은 메시지로 |
| S32 | 2026-03-24 | Harness design for long-running apps | 만드는 쪽과 평가하는 쪽을 나누고, 평가자를 회의적으로 다듬는 것이 쉽다. 계약은 파일로 주고받음 |
| S31 | 2026-03-05 | Skills explained | 여러 에이전트가 함께 쓸 전문성은 서브에이전트가 아니라 스킬에 |
| S40 | 2026-02-05 | C compiler with parallel Claudes | 병렬 팀은 검증기가 거의 완벽해야 한다. 잠금 파일 + git으로 조정 |
| S28 | 2026-01-23 | Building multi-agent systems | 같은 과제에 3~10배 토큰. 계획·구현·시험·리뷰로 나누면 조정에 토큰을 더 씀 → 컨텍스트 기준 분해, 기능 맡은 쪽이 시험도. API 계약이 있는 FE/BE는 좋은 경계. 검증 서브에이전트는 꾸준히 효과, 실패 모드는 이른 승리 선언 |
| S33 | 2026-01-09 | Demystifying evals for AI agents | 실제 실패에서 뽑은 과제 20~50개로 시작. 경로가 아니라 결과를 채점. 시행마다 깨끗한 환경. pass@k와 pass^k |
| S45 | 2026-01 | Complete guide to building skills(PDF) | 동시에 켠 스킬이 20~50개를 넘으면 점검 |
| S36 | 2025-11-26 | Effective harnesses for long-running agents | 진행 파일 + git + JSON 기능 목록. JSON이 마크다운보다 덮어쓰기에 강함 |
| S35 | 2025-09-29 | Effective context engineering | 신호가 큰 가장 작은 토큰 묶음. 서브에이전트 요약은 1,000~2,000토큰 |
| S37 | 2025-07-24 | How Anthropic teams use Claude Code | 세션 끝에 지침 개선을 제안하게 함(우리 회고 루프와 같은 방향) |
| S24 | 2025-06-13 | Multi-agent research system | 리드+서브에이전트가 단일보다 90.2% 나았지만 채팅의 약 15배 토큰. 위임에 목표·출력 형식·도구와 출처·경계 넷. 노력 규모 규칙(간단 1개, 비교 2~4개, 복잡 10개 이상). 의존이 많은 일·대부분의 코딩은 멀티 에이전트에 맞지 않음 |
| — | 2025-04-18 | Claude Code: Best practices for agentic coding(원 블로그) | [미확인] 주소가 S38로 옮겨짐. 갱신판 S38을 썼다 |
2.3 공개 repo (2026-11-11 GitHub API·원본 파일)
| # | repo | 별·마지막 push | 가져온 것 / 피한 것 |
|---|---|---|---|
| S14 | anthropics/skills | 192,807 · 11-06 | 가져옴: 스킬 있음/없음을 같은 턴에 돌려 평균±표준편차, 설명 최적화(should/should-not 20쿼리, 3회, 60/40 분할, 검증 점수로 고름). 피함: 33KB 본문 |
| S15 | anthropics/claude-plugins-official | 46,845 · 11-11 | 가져옴: 에이전트는 일 하나+판정 기준+출력 양식(2~9KB), 리뷰어 읽기 전용, 발견 → 독립 반증 → 통과분만(code-review, claude-security 검증자 셋), 변경을 보고 필요한 리뷰어만(review-pr), 분석 대상 안 지시문은 데이터(code-modernization). 피함: 범용 에이전트에 특정 사내 규칙, tools 제한 없음, 설명 안 <example>. 참고: anthropics/claude-code의 plugins/는 이제 README만 있고 원본은 여기 |
| S16 | obra/superpowers | 316,022 · 11-03 | 가져옴: 반환은 상태+한 줄, 이력 붙여 넣기 금지(디스패치 하나 42k자 중 99%가 이력), 설명은 "언제"만, 스킬 TDD(무지시 대조군, 여러 번). 피함: EXTREMELY_IMPORTANT 같은 강제 문구 |
| S17 | wshobson/agents | 42,412 · 11-09 | 피함: 에이전트 202개 중 187개 tools 제한 없음, 158개 설명에 PROACTIVELY, 같은 이름 복사본이 서로 다름. 오케스트레이터 명령이 정작 general-purpose를 80건 씀 |
| S18 | VoltAgent/awesome-claude-code-subagents | 26,482 · 11-02 | 피함: 없는 중앙 관리자에 JSON으로 묻는 통신 규약(126개), 지어낸 % 목표, "You are a senior X"(163개). 이슈 #300의 "버즈워드 극장" 비판을 메인테이너가 받아들임 |
| S19 | hesreallyhim/awesome-claude-code | 57,753 · 11-11 | 목록에 있다고 품질 검증은 아니다. revfactory/harness 등은 README만 봄 |
2.4 2차 자료
| # | 출처 | 쓴 것 |
|---|---|---|
| S20 | claude-code 이슈 #87515(2026-08-18), #106705(2026-11-02) | 에이전트 163~170개 → 목록 약 14k 토큰, 서브에이전트마다 다시 냄. 에이전트 목록 예산 장치 없음 |
| S21 | Zheng 외, EMNLP 2024 Findings(arXiv 2311.10054) | 시스템 프롬프트 페르소나는 사실형 질문 정확도를 올리지 못함(열린 작업에 바로 일반화는 못 함) |
| S22 | Garg, Orchestrator's tax(2026-07-16) | 한 번에 2~4개, 스킬은 서브에이전트에 자동 상속되지 않으니 명시적으로 넘길 것 |
2.5 이 기계에서 잰 것 [실측]
| # | 무엇 | 값 |
|---|---|---|
| S12 | 노트북 CLI 2.1.287 바이너리 문자열 | conditional skills stored (activated when matching files are touched) → paths 스킬은 맞는 파일을 만질 때까지 목록 밖 |
| S13 | 이 세션(데스크톱 앱 2.1.321) 기록 | 첫 호출 컨텍스트 78,316토큰. 스킬 목록 첨부 33,093자, 에이전트 목록 9개 3,681자, 지침 파일 5,122자. 앱 표시 스킬 9,549토큰(예산 1M의 1% = 10,000 근처) |
| — | claude plugin details superpowers |
always-on 약 706토큰, SessionStart 훅은 "비용 없음"으로 셈(실제로는 3,643자를 주입 — S6대로 훅은 셈에서 빠짐) |
| — | claude auth status(노트북), command -v claude(desktop) |
노트북 로그인 안 됨, desktop에 claude 없음 → claude -p·claude plugin eval을 지금 못 돈다 |
2.6 제작자 본인 발언
X 원문은 threadreaderapp·fxtwitter로, 강연·팟캐스트는 공식 전사가 없으면 제3자 전사로 봤다([1차·전사]). 소속: Thariq Shihipar는 2026 가을 Anthropic을 떠난 것으로 보이고, Cat Wu 퇴사(2026-11-03)는 보도뿐이라 확인하지 못했다. 둘의 상반기 발언은 당시 팀 입장으로 읽는다. 지금 팀 입장에 가장 가까운 것은 공식 문서 S38이다.
| # | 사람 · 날짜 | 출처 | 이 설계에 쓴 발언(요지) |
|---|---|---|---|
| C1 | Cherny·Wu · 2025-05-07 | Latent Space [1차] | 단순한 것부터, 모델 위의 가장 얇은 래퍼. 큰 일은 하나로 먼저 시험(Wu). 슬래시 커맨드는 프롬프트일 뿐 |
| C2 | Cherny·Wu · 2025-10-29 | Every 「AI & I」 전사 [1차] | 프론트·백엔드·QA 같은 페르소나 서브에이전트의 가치는 직함이 아니라 서로 섞이지 않은 컨텍스트 창이고, 페르소나 틀은 "너무 의인화". 코드 리뷰는 관점별 서브에이전트(지침 준수·git 이력·명백한 버그) → 중복 제거 → 서브에이전트 약 5개가 거짓 양성을 거름 |
| C3 | Cherny · 2026-01-02 | X 「my setup」 스레드 [1차] | 가장 중요한 팁: 검증 수단을 주면 결과가 2~3배. 서브에이전트는 PR마다 하는 일을 자동화(첨부 화면: build-validator, code-architect, code-simplifier, oncall-guide, verify-app). 팀 CLAUDE.md 2.5k토큰, 틀릴 때마다 추가. 포맷 PostToolUse 훅. --dangerously-skip-permissions를 안 씀 |
| C4 | Cherny(팀 팁) · 2026-01-31 | X 스레드 [1차] | 하루 한 번 넘게 하는 일은 스킬·커맨드로(/techdebt 등). 서브에이전트로 메인 창을 깨끗하게(→ 2026-11 공식 문서가 옛 조언으로 분류). 동시 worktree 3~5개 |
| C5 | Cherny · 2026-02-17 | YC Lightcone 전사 [1차·전사] | 개인 CLAUDE.md는 2줄. 비대해지면 지우고 틀리는 것만 다시. 모델을 상자에 가두지 말고 6개월 뒤 모델을 위해 만들라 |
| C6 | Cherny · 2026-03-04 | Pragmatic Engineer [1차·전사] | 서브에이전트는 받은 프롬프트 말고는 부모 창을 모른다. agent teams는 토큰을 많이 쓰고 모든 일에 필요하지 않다. 내 설정을 그대로 복사하는 것은 틀린 결론 |
| C7 | Hollman · 2026-05-19 | Code w/ Claude London 「Beyond the basics」, 전사 [1차·전사] | 스킬 설명은 매 세션 로드, 안정적으로 발동시키려면 문단(약 300~400토큰)까지 필요할 수 있다. 서브에이전트마다 부모 프롬프트에 한 줄 설명 비용. 훅은 창 밖에서 돌아 토큰 0, 린터 피드백은 막지 않고 방향만. 플러그인에 CLAUDE.md를 못 싣게 한 것은 싸 보이지만 비싼 추상화라서이고, 대신 SessionStart 훅으로 비용을 드러냄. 사내 도구는 MCP보다 CLI+사용법 스킬 |
| C8 | Cherny · 2026-05-24, 06-08 | X [1차] | 1순위 팁은 auto mode(권한 질문이 사라져 여러 세션을 돌리는 기본 블록). plan mode 대신 auto mode |
| C9 | Shihipar·Bidasaria · 2026-06-02 | X 아티클 dynamic workflows [1차] | 워크플로로 각자 창을 가진 Claude들을 조율하고 생성물마다 다른 에이전트가 기준표로 적대적 검증. 단 대부분 일에는 필요 없고 토큰이 크다. 모든 일에 리뷰어 패널을 붙이지 말라 |
| C10 | Cherny · 2026-07-08 | X /checkup [1차] | 본인 repo 진단: CLAUDE.md가 세션마다 약 10k토큰, 프로젝트 스킬 38개가 2,345세션 동안 한 번도 안 쓰임 |
| C11 | Cherny · 2026-07-15 | X [1차] | 모든 팀이 CLAUDE.md·REVIEW.md·스킬·문서로 분야 지식을 인프라로 만들어야 한다 |
| C12 | Shihipar · 2026-09-29 | Latent Space 「Claude Code's Next Era」 [1차·전사] | 이제 스킬이 나아졌는지 eval로 본다. 세션 도중 Claude가 스킬을 잊기도 한다. 새 프로젝트는 CLAUDE.md 없이 시작해도 된다 |
| C13 | Wolff · QCon SF 2025-11 | InfoQ 발표 [1차·전사] | 이 속도를 가능하게 한 것은 시험이다 |
시간에 따라 바뀐 조언: plan mode 먼저(2025-102026-02) → auto mode(2026-05). 서브에이전트로 메인 창 보호(2026-01) → 병렬·소음 격리·독립 리뷰에만(공식, 2026-11). CLAUDE.md는 틀릴 때마다 추가(2026-01) → 과잉 제약했다, 반복되는 실패만, 함정 위주(2026-07~09).
소유자가 쓴 2차 자료 대조: InfoQ 2026-01-10은 1차와 맞다(다만 1월 시점이라 plan mode·CLAUDE.md 조언은 이후 바뀜). jc-aiwiki의 Hollman 요약은 대부분 전사와 맞고, "MCP가 최악"은 전사에 없는 과장이다. GitHub 0xquinto/bcherny-claude는 재구성본이다(에이전트 이름 다섯은 Cherny 화면과 같지만 staff-reviewer와 커맨드 넷은 출처 없음). howborisusesclaudecode.com은 Anthropic과 상관없는 팬 사이트이고, 원문에 없는 인용이 하나 있다.
3. 주제별로 알게 된 것
3.1 context 최적화
- 시작 비용은 고정 부분(도구 정의·시스템 프롬프트)이 크고, 우리가 바꿀 수 있는 것은 스킬 목록·에이전트 목록·지침 파일·SessionStart 훅 출력이다(S13). 지금 스킬 목록이 예산 근처라, 새 스킬은
paths로 목록 밖에 두는 것이 가장 싸다(S1·S12). - 에이전트 목록에는 예산 장치가 없다(S20). 설명 합을 재고 줄이는 것밖에 없다.
- 호출한 스킬은 압축 뒤 앞 5,000토큰만 다시 붙는다(S9) → 중요한 것을 앞에.
- 캐시: 스킬 호출·플러그인 스킬 켜기는 캐시를 안 깬다. 세션 중
CLAUDE.md를 고치면 그 세션에는 적용되지 않는다(S8). - "서브에이전트로 컨텍스트를 보호하라"는 옛 조언이고, 지금은 병렬·소음 격리·독립 리뷰용이다(S38). 서브에이전트 요약은 1~2k토큰이면 된다(S35).
3.2 AGENTS.md·CLAUDE.md 나누기
CLAUDE.md가@AGENTS.md를 가져오는 v1 방식이 공식 경로다(S5). 루트는 함정·검증 명령·코드에서 안 보이는 결정만(S34·S38). 층끼리 부딪치는 지시가 실제로 품질을 깎았다(S34).
3.3 스킬·서브에이전트·훅 경계
- 스킬: 여러 에이전트가 함께 쓸 전문성, 메인에서 보이며 조종할 절차(S31·S26).
- 서브에이전트: 병렬 독립 작업, 다시 안 볼 긴 출력, 작성 과정을 못 본 새 리뷰어, 도구 제한(S29·S38). 분야·역할·팀마다 두지 않는다(S26·S28).
- 훅: 항상·절대 일어나야 하는 것(S10·S25).
3.4 리드와 오래 사는 에이전트
- 리드의 위임 품질이 성패를 가른다: 목표·출력 형식·도구와 출처·경계, 노력 규모 규칙(S24). 리드의 알려진 결함: 팀원을 기다리지 않고 직접 구현, 너무 이른 완료 판정(S3).
- 오래 사는 상태는 파일로: 진행 파일 + git + JSON(S36), 한 파일 한 주인(S44). 우리 쪽은 장부·공유 노트·하위 세션 보고가 이미 그 역할이다.
3.5 에이전트 사이 통신
- 서브에이전트끼리는 대화하지 못한다(S29). 통신은 리드를 거치거나 파일로(S32·S36), 팀이면 공유 작업 목록·메일함(S3), 세션 사이면 cross-session 메시지(텍스트만).
- 여러 에이전트가 한 문서를 같이 고치면 사실이 사라진다(S44).
3.6 평가
- 작게 바로: 골든 예제 10개(S26), 과제 20~50개(S33), 시나리오 3개(S11).
- 결과를 채점하고 경로는 채점하지 않는다, 여러 번 돌린다, 정답은 실행하는 쪽 손 밖에(S33·S41).
- 스킬은 발동(불릴 때 불리나)과 결과(있음/없음 차이)를 따로 잰다(S7·S14).
4. 격차 표
비교한 것: 소유자 입력 자료(2026-11-07, 영상 두 편과 Hollman·Cherny 자료 정리) · v1 설계 13절 결정 · 이 조사 · 지금 하네스(claude-harness 0.2.0, 두 템플릿 main).
| # | 주제 | 입력 자료 / 13절 결정 | 조사 결과 | 지금 하네스 | 격차와 조치 |
|---|---|---|---|---|---|
| G1 | 분야 전문성 | 소유자 2026-11-11: 분야별 전문가 서브에이전트·스킬 | 분야 전문성은 스킬, 분야 서브에이전트는 반대(S26·S28·S29·S31) | 템플릿마다 서브에이전트 셋(구조 리뷰·실행 확인·단순화), 분야 지식 스킬 0 | 큼. 분야 지식 스킬 19개(백엔드 10·프론트 9) + 렌즈 리뷰어 하나. 소유자 요청과 다른 점은 설계 0절에 밝힘 |
| G2 | 협업 규칙 | 소유자: 큰 그림 공유, 주고받기, 매뉴얼 | 위임 4요소(S24), 반증 필터(S15·S27), 라운드 상한(S27), 파일 주인 하나(S44) | 없음(위임 루프는 하위 세션 단위만) | lead 스킬 + 각 repo docs/work/experts.md |
| G3 | 스킬 목록 예산 | 13절 Q8: 안 쓰는 개인 스킬을 name-only·off |
예산 1%, 넘치면 덜 쓰는 것 설명부터 지움(S1) | 앱 표시 9,549토큰, 예산 10,000 근처(S13). Q8이 아직 적용 안 된 것으로 보임 | 새 스킬은 paths로 목록 밖. Q8 적용은 소유자 전역 설정이라 보고에만 |
| G4 | 에이전트 목록 비용 | 없음 | 예산 장치 없음, 서브에이전트마다 다시 냄(S2·S20) | 잰 적 없음 | docs/work/experts.md 6절에 재는 법. 템플릿 적용 때 합에 상한 시험 |
| G5 | 스킬 설명 | 입력 자료: Hollman "문단으로 300~400토큰, 발동 조건 포함"(2차). 13절 Q9: 모두 모델 호출 | 설명은 트리거 조건, 1,024자(S11), 강조·절차 요약 금지(S16·S23) | 플러그인 스킬 설명 405~575자 | 시험에 1,024자·금지어 검사를 더함. Q9를 지켜 새 스킬 셋도 모델 호출 |
| G6 | 발견 검증 | 위임 루프: High는 총괄이 코드에서 다시 확인 | 독립 반증·투표 후 통과분만(S15·S27) | 다시 보기만 | lead ⑤ 반증 |
| G7 | 리뷰-수정 반복 | 정리 프로그램: "리뷰 발견 0까지" | 상한 3, diff만 재리뷰, 부류로 묶기(S27) | 상한 없음 | lead ⑨. "발견 0까지"와의 관계: 세 번에 안 끝나면 설계 문제로 되돌려 다시 정한다 |
| G8 | 평가 | 입력 자료: 예측 → 실측 → 회고. 13절 Q11: repo 장부 | with/without, 여러 번, 정답 손 밖(S7·S14·S33) | 장부에 예측·실측만, 판 비교 칸 없음 | 장부 eval 줄과 compare, usage에 시작 컨텍스트·서브에이전트 반환 크기, harness-eval 스킬 |
| G9 | 헤드리스 실행 | 없음 | 발동 시험은 claude plugin eval(S7) |
노트북 CLI 로그인 안 됨, desktop에 claude 없음 | 소유자가 claude auth login. 그전에는 서브에이전트로 흉내 |
| G10 | 에이전트 사이 통신 | 소유자: 서로 주고받기 | agent teams는 실험·비쌈(S3·S4). 서브에이전트는 서로 대화 못 함(S29) | 없음 | 리드를 거치는 넘김 한 번. agent teams는 평가 뒤 |
| G11 | 오래 사는 에이전트 | 없음 | memory 필드 있음(S2). 상태는 파일로(S36·S44) |
하위 세션 + 공유 노트 + 장부 | memory는 쓰지 않고 지식 스킬 「함정」에 커밋. 세션 안에서는 SendMessage로 이어 묻기 |
| G12 | 루트 지침 | 13절 Q2: 20~40줄 | 루트는 함정·검증 위주(S34). 부딪치는 지시가 품질을 깎음 | 템플릿 루트 40줄 안 | template/AGENTS.md에 한 줄만 더함(40줄 시험 유지) |
| G13 | 캐시 | 입력 자료: "바뀌지 않는 것은 앞에"(확인 못 함이었음) | 맞음. Claude Code가 그 순서로 보낸다(S8) | — | 조치 없음. v1 2.2절 16번 판정을 "맞음"으로 고칠 거리(design-docs, 보고에만) |
| G14 | 페르소나 | 없음 | 역할 한 줄은 공식이 권함(S23), 긴 경력 소개는 근거 없음(S21) | 템플릿 에이전트는 이미 역할 한 줄 | 새 스킬·에이전트 모양에 규칙으로 |
| G15 | 검증 스킬 | Cherny: 검증 수단이 품질 2~3배(입력 자료, 2차) | 1차로 확인: C3 13번, S27, S30 검증 스킬이 가장 큰 효과 | verify-api·verify-app, desktop-gates |
지식 스킬마다 「검증」 절. 프론트 QA는 verify-app에 fe-qa를 실음 |
| G16 | v1 설계 2.2절의 "확인 못 함" | 2.2절 11·12번(Hollman 훅·설명 길이), 16번(캐시 순서), 19번(code-simplifier·verify-app 이름), 21번(plan mode 대신 auto mode) | 모두 1차로 확인: C7, S8, C3 첨부 화면, C8 | — | design-docs harness/01-harness-design.md 2.2절 판정을 "맞음"으로 고칠 거리(design-docs는 이 작업 범위 밖이라 보고에만) |
| G17 | 페르소나 서브에이전트 | 입력 자료 적용 초안: arch-reviewer·verify-app 등 역할 에이전트 | Cherny 본인: 가치는 섞이지 않은 창이지 직함이 아니다(C2) | 역할 에이전트 셋 | 렌즈 리뷰어(창은 새로, 분야는 렌즈로)가 C2와 같은 결론 |
5. 확인 못 한 것
- 2025-04-18 원 블로그 best practices(주소가 문서로 옮겨짐, 아카이브도 실패).
paths스킬이 목록에서 빠지는 것을 새 세션에서 직접 보지 못했다(바이너리 문자열로만, 헤드리스 인증 없음).claude plugin eval의 위임 채점(tool_used의tool: Agent)은 문서와 추론뿐이다.- revfactory/harness 등 커뮤니티 묶음 일부는 README만 읽었다.