Claude Code 하네스: 리서치부터 글쓰기까지, 하나의 구조로 확장하기

1편에서 monorepo-dev라는 하네스 하나로 에이전트, 스킬, 오케스트레이터의 기본 구조를 설명했습니다. 그때는 "풀스택 개발을 위임한다"는 하나의 사례에 집중했는데, 같은 구조를 다른 영역에도 적용해보면서 흥미로운 점을 발견했습니다. 하네스를 여러 개 만들다 보니, 반복되는 아키텍처 패턴이 보이기 시작한 것입니다.

현재 6개의 하네스를 운영하고 있습니다. 처음에는 각각 다른 문제를 풀기 위해 만들었는데, 뒤돌아보니 세 가지 패턴으로 분류할 수 있었습니다. 이번 편에서는 그 패턴을 먼저 정리하고, 실제 사례 다섯 개를 통해 하나의 구조가 얼마나 다양한 영역에 확장되는지를 살펴보려 합니다.

세 가지 아키텍처 패턴

하네스를 여러 개 만들면서 발견한 패턴은 세 가지입니다.

팬아웃/팬인은 같은 주제를 여러 관점에서 동시에 조사하고, 결과를 하나로 합치는 구조입니다. 각 에이전트가 독립적으로 움직이기 때문에 서로 대화할 필요가 없고, 서브 에이전트 모드로 충분합니다.

파이프라인은 A의 산출물이 B의 입력이 되는 순차 구조입니다. 앞 단계가 끝나야 뒤 단계가 시작됩니다. 조립 라인과 비슷합니다.

생성-검증은 만드는 역할과 검토하는 역할을 분리하는 구조입니다. 피드백 루프를 통해 품질을 끌어올립니다. 1편에서 다뤘던 monorepo-dev의 QA 에이전트가 바로 이 패턴이었습니다.

실제로는 이 셋을 조합해서 씁니다. monorepo-dev는 팬아웃과 생성-검증의 조합이었고, 뒤에서 다룰 data-pipeline은 파이프라인과 팬아웃을 함께 사용합니다. 패턴을 알고 나면 새 하네스를 설계할 때 "이 작업은 어떤 패턴에 가까운가"부터 생각하게 됩니다.

다섯 가지 사례

research: 다각도 리서치

팬아웃/팬인 패턴을 적용한 리서치 하네스입니다. 세 명의 에이전트가 각각 공식 문서와 뉴스, 논문과 스펙, 커뮤니티 반응을 독립적으로 조사합니다. 서로의 존재를 모른 채 각자의 영역만 파고들고, 리더가 결과를 모아서 교차 검증합니다. 한 소스에서만 나오는 주장은 걸러내고, 여러 소스에서 확인된 사실에 가중치를 주는 방식입니다.

이 하네스에 팬아웃이 맞는 이유는 단순합니다. 세 관점이 독립적이라서입니다. 공식 문서를 조사하는 에이전트가 커뮤니티 반응을 알 필요가 없고, 그 반대도 마찬가지입니다. "이 기술 조사해줘" 한 마디로 공식 입장, 학술적 배경, 실무자 반응이 동시에 나옵니다.

web-design: AI 냄새 제거

파이프라인과 생성-검증을 조합한 디자인 하네스입니다. AI가 만드는 디자인이 뻔하게 느껴지는 이유는 학습 데이터의 평균값으로 수렴하기 때문이라는 생각이 들었습니다. 이 하네스는 그 문제를 구조로 풀어봅니다.

첫 번째 에이전트가 실제 디자인 트렌드를 조사해서 구체적인 레퍼런스를 확보합니다. 모호한 "모던하게"가 아니라 색상 코드, 폰트명, 레이아웃 비율 같은 수치입니다. 두 번째 에이전트가 이 브리프를 기반으로 구현하고, 세 번째 에이전트가 결과물에서 AI가 자주 만드는 패턴을 감지합니다. 감지되면 수정을 요구하는 피드백 루프가 돌아갑니다. 파이프라인으로 단계를 밟되, 마지막에 생성-검증으로 품질을 잡는 구조입니다.

blog-analytics: 교차 분석

팬아웃/팬인 패턴으로 블로그 통계를 분석하는 하네스입니다. 두 명의 에이전트가 각각 트래픽 데이터와 검색 데이터를 담당합니다. 분리한 이유가 있습니다. 두 데이터는 소스도 다르고, 분석 관점도 다릅니다. 하나의 에이전트에게 둘 다 시키면 컨텍스트가 비대해져서 분석의 정밀도가 떨어졌습니다.

각자 분석이 끝나면 리더가 두 결과를 교차합니다. "검색에서 잘 보이는데 클릭률이 낮은 글"이나 "트래픽은 높은데 검색 유입이 적은 글" 같은 인사이트는 두 데이터를 겹쳐봐야 나옵니다. "블로그 통계 보여줘" 한 마디로 이런 교차 분석이 가능해졌습니다.

blog-writing: 대화를 글로

생성-검증 패턴을 적용한 글쓰기 하네스입니다. 초안을 작성하는 에이전트와 SEO를 검토하는 에이전트가 한 팀으로 움직입니다. 앞선 리서치나 분석 하네스와 다른 점은, 이 둘이 에이전트 팀 모드로 실시간 소통한다는 것입니다. SEO 리뷰어가 "소제목에 키워드를 넣으면 좋겠다"고 피드백하면 작성자가 바로 반영해야 하기 때문입니다.

이 하네스에서 가장 신경 쓴 규칙이 있습니다. SEO와 페르소나가 충돌하면 페르소나가 우선한다는 것입니다. 검색 최적화를 위해 저자의 목소리를 바꾸는 건 본말이 전도된 일이라는 생각이 들었습니다. 작성자 에이전트는 시작할 때 저자의 글쓰기 가이드라인을 로드하고, 그 톤을 유지하면서 초안을 씁니다. 실은 지금 읽고 계신 이 글도 blog-writing 하네스로 작성한 초안입니다.

data-pipeline: 파이프라인 설계

파이프라인과 팬아웃을 조합한, 계층적 위임 구조의 하네스입니다. 네 명의 에이전트가 스키마 설계, ETL 로직, 데이터 검증, 모니터링을 순차적으로 담당합니다. 다만 순수한 파이프라인은 아닙니다. 스키마 설계가 끝나면 ETL과 검증 규칙 에이전트가 동시에 작업을 시작합니다. 스키마가 없으면 ETL 로직을 짤 수 없고, ETL과 검증이 없으면 모니터링할 대상이 없기 때문에, task 의존성이 자연스러운 실행 순서를 만들어줍니다.

이 하네스가 계층적인 이유는 앞 단계의 산출물이 뒤 단계의 전제 조건이 되기 때문입니다. 각 에이전트가 자기 역할에만 집중하면서도, 전체가 하나의 파이프라인 설계 문서로 수렴합니다.

만들면서 느낀 것들

처음 monorepo-dev를 만들 때는 오래 걸렸습니다. 그런데 패턴을 이해하고 나니 새 하네스를 구성하는 시간이 눈에 띄게 줄었습니다. "이건 팬아웃이 맞겠다", "여기는 파이프라인 뒤에 검증을 붙이자"처럼 뼈대부터 빠르게 세울 수 있게 되었습니다.

에이전트를 재사용할 수 있다는 점도 의미가 있었습니다. 한 번 잘 정의해둔 전문가는 다른 팀에도 투입할 수 있습니다. 그리고 완벽한 결과보다 격리가 중요하다는 걸 자주 느낍니다. 한 에이전트가 실패해도 다른 에이전트의 결과는 살아 있습니다. "전체 실패"보다 "부분 성공"이 훨씬 유용합니다.

컨텍스트 윈도우는 정말로 유한합니다. Progressive Disclosure 없이 모든 정보를 한꺼번에 넘기면 에이전트의 판단력이 흐려지는 걸 체감했습니다. 필요한 정보만, 필요한 시점에 제공하는 것. 이 원칙은 하네스 설계에서 가장 실용적인 교훈이었습니다.

돌이켜 생각해보면, 이 모든 것은 결국 사람 조직에서 이미 배운 원칙이었습니다. 역할 분리, 의사소통 프로토콜, 에러 격리. 좋은 팀을 만드는 원리는 그 팀원이 사람이든 AI든 달라지지 않습니다.