이것은 무엇인가

Fable이 무료로 개방되었던 6월부터 7월 초 정도까지, 무엇을 시킬지 고민하던 중 7월 중순부터는 종량제(Pay-as-you-go)로 전환된다는 소식을 듣고 조금 아쉽게 생각하고 있었습니다.

그러던 중, 얼마 전 Pro 플랜에도 100달러 크레딧이 배포되었기에, "그럼 앞으로의 개인 개발이나 업무용을 위해 나만의 전용 개발 팀 군단을 만들어 볼까"라고 생각하여 Fable에 의뢰해 보았습니다.

한 일

Claude Code의 서브 에이전트(Sub-agent) 기능을 사용하여, 7가지 역할(Product Manager / Project Manager / Solution Architect / Designer / Developer / Quality Assurance / EM Support)을 정의하고, 프로젝트를 시작부터 완료까지 자율적으로 돌릴 수 있는 체제 구축을 의뢰했습니다.

저는 기본적으로 정규직으로 일을 하면서, 가끔 개인 개발이나 업무 위탁으로 EM, PM, Developer, Scrum Master 같은 일을 하는 경우가 많기 때문에, 어떤 현장에서도 재사용할 수 있도록 에이전트 정의는 프로젝트에 의존하지 않는 템플릿을 만들고자 했습니다.

왜 서브 에이전트로 "팀"을 만드는가

여러분도 알고 계시겠지만, Claude Code는 단독으로도 상당히 잘 작동하지만, 한 세션(Session)에 모든 것을 맡기면 여러 가지 번거로운 점이 있습니다.

• 컨텍스트(Context)가 비대해져 정밀도가 떨어진다
• "설계자"와 "구현자"가 동일하면, 사양의 모호함을 스스로 편의에 맞게 해석하여 진행해 버린다
• 품질 체크를 구현자 스스로 수행하면 형식적으로 흐르기 쉽다

등등, 나열하자면 끝이 없을 것 같습니다.

인간의 팀 개발에서 역할을 분담하는 것과 같은 이유로, AI에게도 분업을 시키는 것이 아웃풋(Output)의 질을 높입니다. (Anthropic Academy의 자료에도 그렇게 적혀 있었던 것 같습니다.)

그래서 그것을 실현하기 위해 팀을 만들어 보았습니다.

체제도

인간 (EM / PM / 개발자)
│
├── 상담 (프로젝트 외 · 독립)
...

모델 활용 측면에서는 판단·설계 계열은 Opus, 실행 계열(Developer / QA)은 Sonnet으로 설정하여 비용 효율을 높였습니다.

Anthropic이 제공하는 각 모델과 특징은 다음과 같지만, 모델 선정은 지금까지 Claude Code를 사용해 온 감각에 따라 결정했습니다. 선정에 특별히 명확한 이유는 없습니다.

설계상의 포인트인 오케스트레이션(Orchestration)을 어떻게 할 것인가?

Claude Code의 서브 에이전트에는 "서로 직접 대화할 수 없다"는 제약이 있는 듯하여, 즉 Project Manager가 Developer를 호출하거나 Developer가 QA에게 검증을 요청하는 등의 동작은 불가능한 것으로 보였습니다.

이 전제를 바탕으로 다음과 같은 설계가 이루어졌습니다:

• Project Manager는 "두뇌". 어떤 역할을 어떤 순서로, 무엇을 입력값으로 움직일지에 대한 계획을 문서로 출력한다.
• 메인 세션은 "손발". PjM의 계획에 따라 각 역할을 Task 도구로 순차적으로 기동한다.
• 전달은 모두 파일 기반. 각 역할은 워크스페이스(Workspace)에 성과물을 쓰고, 다음 역할은 그것을 읽는다.

.claude/documents/projects/{yyyy-mm-dd}_{slug}/
├── 00_request.md # 인간의 의뢰 (원문)
├── 10_product_brief.md # PdM
...

번호가 파이프라인(Pipeline)의 순서를 나타냅니다. 소규모 수정이라면 00 → 20 → 50 → 60 → 90으로 단축할 수 있도록 구성되어 있습니다.

또한, 파일 기반으로 만든 장점은 3가지입니다:

• 컨텍스트 분리 (Context Separation): 각 역할은 필요한 문서만 읽기 때문에 토큰(Token) 효율이 좋다.
• 재개 용이성 (Resumability): 세션이 끊겨도 성과물 파일이 남아 있으므로 중간부터 재개할 수 있다.
• 감사 가능성 (Auditability): 인간이 언제든 중간 성과물을 보고 리뷰할 수 있다.

각 역할의 설계 방침

에이전트 정의 공통 포맷

모든 역할에 대해 frontmatter (name / description / model / allowed-tools)에 이어 다음과 같은 섹션을 갖도록 했습니다:

• Role: 한 문장으로 된 역할 정의
• Responsibilities: 구체적인 책무
• Inputs / Outputs: 무엇을 읽고 무엇을 쓰는지
• Collaboration Protocol: 타 역할과의 협업 규칙
• Escalation: 인간에게 판단을 요청하는 기준
• Style: 언어 및 포맷 지정

Product Manager

프로덕트 비전과 전략을 가지며, 인간의 요청을 MoSCoW 방식으로 우선순위를 정한 Product Brief로 변환한다. 중요한 점은 수락 기준(Acceptance Criteria)을 "QA가 객관적으로 검증할 수 있는 형태"로 작성하는 것이다.

Project Manager

• 프로젝트의 계획, 진행, 완료 판정을 담당한다. 앞서 언급했듯이 오케스트레이터(Orchestrator)의 두뇌 역할을 하며, dispatch plan(어떤 역할을, 어떤 순서로, 무엇을 입력값으로 하여 기동할지)을 문서로 출력한다.
• 실제 기동은 메인 세션이 수행한다.

Solution Architect

• Product Brief와 Project Plan을 바탕으로 아키텍처를 설계한다.
• ADR(Architecture Decision Record)을 통해 기술 선정 근거를 남기는 것이 포인트다.
• "기존 아키텍처의 진화를 우선하며, 교체는 최후의 수단으로 한다"라는 규칙도 포함되어 있다.

Designer

• 실제 비주얼 디자인은 claude.ai/design에서 인간이 수행한다는 전제로 작성한다.
• 이 에이전트는 그 전 단계인 디자인 기반(반응형 방침, 타이포그래피, 디자인 토큰, 그라운드 룰)을 책정하고, claude.ai/design에 붙여넣을 프롬프트를 생성하기 위한 것이다.

Developer (Sonnet)

• 계획, 아키텍처, 디자인에 따라 구현한다. 비용 효율성을 위해 Sonnet을 할당했다.

• 중요한 제약 사항:

  • 품질 게이트(format / lint / typecheck / test)를 스스로 실행하고, 결과를 원문 그대로 보고하도록 했다. (실패를 숨기고 완료 보고를 하는 것을 명시적으로 금지하고 있다.)
  • git 쓰기 작업(commit / push)은 금지한다. 인간이 실행하도록 설정했다. (이상한 커밋을 만들지 않기를 원하기 때문이다.)
  • 아키텍처와 현실이 어긋날 경우, 임의로 다른 설계로 진행하지 않고 차이점을 보고서에 기록하도록 했다.

• 품질 게이트(format / lint / typecheck / test)를 스스로 실행하고, 결과를 원문 그대로 보고하도록 했다. (중복 내용)

Quality Assurance (Sonnet)

• 구현의 독립 검증. Developer의 보고를 신뢰하지 않고, 수락 기준을 근거(커맨드 출력)와 함께 검증하는 역할을 담당한다.
• 코드는 읽기 전용이다. 아무리 경미한 수정이라도 스스로 고치지 않고, 보고서에 작성하여 Developer에게 반려(Send back)하도록 했다.
• 반려 횟수는 최대 2회로 제한한다. 이를 초과하면 인간에게 에스컬레이션(Escalation)하여 무한 루프를 방지한다.

EM Support

• 프로젝트 파이프라인에는 참여하지 않는, 독립적인 EM(Engineering Manager)의 상담 상대.
• 정규직이나 업무 위탁 업무에서 발생할 수 있는 조직 계획, 육성, 피드백, 평가 등에 대한 브레인스토밍(打ち合わせ)을 위해 사용하는 서브 에이전트.
• 파이프라인 미참여를 명시하여, 인사 정보가 프로젝트 문서에 혼입되는 것을 방지하고 있다.

인간 게이트와 에스컬레이션

자율 실행을 원칙으로 하지만, 다음 사항은 반드시 인간이 판단하도록 했다:

모든 역할 공통 에스컬레이션 기준:

• 프로덕트 전략 판단
• 불가역적인 조작 (삭제, 결제, 공개)
• 신규 유료 서비스 및 크리덴셜(Credential) 추가
• 견적 150% 초과
• QA 반려 2회 초과
• 에이전트 간의 결과물 모순

품질의 메커니즘

품질은 "Developer가 노력한다"가 아니라, 구조적으로 담보하도록 설계했다.

• Developer는 품질 게이트를 스스로 실행하고 결과를 그대로 붙여넣는다 (속임수 금지).
• QA는 Developer의 보고를 읽지 않고, 독립적으로 동일한 체크를 실행한다.
• QA는 PASS / FAIL을 근거와 함께 제시한다. FAIL일 경우 Developer에게 반려한다.
• 2번 수정해도 통과하지 못하면 인간이 개입한다.

구현자와 검증자를 분리함으로써, 셀프 체크(Self-check)만 할 때보다 누락이 줄어들기를 기대하고 있습니다.

기존 가드레일(Guardrail)과의 관계

이 체제는 제가 만들었던 기존 보안 계층 위에 얹히는 형태로 정비했습니다:

• CLAUDE.md에서 git 쓰기 금지 · 운영 환경 배포 금지 · secrets 침범 불가 정의
• guard.sh (PreToolUse hook)에서 위험한 명령어를 차단
• settings.json의 거부(deny) 리스트로 금지된 도구 지정

에이전트 정의 측에서 이들을 완화하지 않도록 하고 있습니다.

다른 리포지토리로의 전개

에이전트 정의는 프로젝트에 의존하지 않도록 만들어 두었으므로, 전개 절차는 다음과 같습니다:

• .claude/agents/의 7개 역할(Role)과 .claude/skills/run-project/를 복사
• 전개 대상의 CLAUDE.md에 에이전트 표와 스킬 표를 추가
• 품질 게이트(Quality Gate) 명령어(test / lint 등)를 전개 대상의 CLAUDE.md에 정의

프로젝트 고유 정보(기술 스택 · 명령어 · 규약)는 에이전트 정의가 아니라, 전개 대상의 CLAUDE.md나 .claude/rules/에 작성하도록 하고 있습니다. 이를 통해 제가 자주 사용하는 Flutter나 Laravel 프로젝트에서도 동일한 에이전트 정의를 그대로 사용할 수 있는 형태로 만들었습니다.

고려한 점

• 서브 에이전트(Sub-agent)로부터의 태스크(Task) 중첩 실행은 환경 차이가 있기 때문에, PjM 직접 오케스트레이션(Orchestration) 방식은 채택하지 않았습니다. 향후 중첩이 안정되면 이행 가능한 설계로 만들어 두었습니다.
• claude.ai/design과의 연동은 API 연동 없이, Designer가 생성하는 프롬프트를 인간이 붙여넣는 수동 운용 방식으로 했습니다 (사소하지만, 예산이 없어서 편리함과 비용을 저울질하여 수동으로 하고 있습니다).
• 인사 정보의 혼입을 방지하기 위해, em-support 파이프라인에 참여하지 않음을 명시하고 있습니다.

소감

솔직히 AI에 관한 진화라고 할까, 새로운 정보가 너무 많아서 학습하거나 익히는 것이 매우 어렵다고 느끼고 있었습니다.

문서를 읽고 이해해 나가도, 새로운 정보가 매일같이 나오기 때문에 따라잡을 수가 없습니다.

그래서 이번 기회에 Fable을 사용하여 하네스(Harness) 설계 지원을 받아보게 된 것이었습니다.

아직 실제 프로젝트에서의 운용은 시작되지 않았기 때문에 실제로 어떻게 움직일지는 검증되지 않았으며, 솔직히 이것이 정답인지, 제가 인지하고 있는 AI나 하네스의 사고방식, 모델 선정 등이 맞는지도 솔직히 모르겠습니다. 우선 개인 개발 안에서 돌려보면서 조정해 나가려고 합니다. 끝.

Discussion