• 메타스킬이 일반 스킬과 어떻게 다른지 이해하고, hareness SKILL.md의 실제 파일구조를 통해 Progressive Disclosure와 자기 참조성이 어떻게 구현되는지 확인한다.
  • 6단계 파이프라인의 각 Phase에서 무엇을 실행하고 무엇이 산출되는지 파악하고, 하네스가 한 번 만들면 끝이 아니라 계속 순환하며 발전하는 이유를 이해한다.

메타스킬이란 무엇인가

  • 메타스킬: 스킬과 에이전트를 만드는 스킬이다.

메타스킬이 여는 6단계 파이프라인

  • 도메인 분석 → 팀 설계 → 정의 → 스킬 → 오케스트레이션 → 검증

Phase 1. 도메인 분석: 질문을 정제하는 단계

  • 정제할 항목
    • 도메인과 핵심 작업 유형: 데이터 분석 파이프라인인가, 콘텐츠 생성인가, 웹 앱 개발인가, 코드 리뷰인가.
    • 기존 에이전트와 스킬의 현황: .claude/agnets/와 .claude/skills/를 먼저 읽고 이미 있는 구성과 새 구성이 충돌하는지 확인
    • 프로젝트 코드베이스 탐색: 기술 스택, 데이터 보델, 모듈 경계를 파악한다. 이 경계선은 Phase 3에서 에이전트를 분리할 때의 기준선이 된다.
    • 사용자 숙련도 감지: 쓰는 용어와 질문 수준으로 기술 배경을 파악한다.
    • 기존 에이전트와의 충돌, 중복

Phase 2. 팀 아키텍처 설계

  • 내릴 결정은 2가지
  • 실행 모드: 에이전트 팀인가, 서브에이전트 인가, 하이브리드인가.
    • 기본은 에이전트 팀이지만 단일 작업, 결과 반환만 필요한 경우에는 서브에이전트가 더 가볍다.
    • Phase 마다 특성이 다르면 Phase 단위로 팀/서브를 섞는 하이브리드가 답이다.
  • 아키텍처 패턴: 에이전트 팀응ㄹ 성택했다면 여섯 가지 패턴 중에서 하나를 고른다.

Phase 3, 4. 에이전트와 스킬: 파일이 없으면 존재하지 않는다

  • Phase 3이 누가 일하는가(에이전트)를, Phase 4가 어떻게 일하는가(스킬)를 담당한다.
  • 에이전트 파일: .claude/agents/{name}.md
  • 스킬 파일: .claude/skills/{skill-name}/SKILL.md
  • 에이전트를 파일로 남겨야되는 이유
    • 재사용성: 파일이 여러 세션, 여러 팀에서 공유된다.
    • 팀 통신의 프로토콜의 명시: 누가 누구에게 언제 무엇을 보내는지를 에이전트 정의 안에 선언해야, 실행 중에 팀원끼리 직접 소통하는 구조가 유지된다. 프롬프트에만 담긴 지시는 자연스럽게 ‘리더에게 보고하는 모드’로 돌아가면서 리더 병목이 되살아나는 경향이 있다.
  • 스킬의 핵심 개념은 단계적 정보 공개(Progressive Disclosure)이다.

Phase 5. 오케스트레이션

  • 지금까지 만든 에이전트와 스킬을 실제 워크플로로 묶는다.
    • 핵심 “리더는 모니터이지 중재자가 아니다.”
  • 오케스트레이터 스킬: .claude/skills/{domain}-orchestrator/SKILL.md
  • Phase 5의 말미에는 2 가지 포인트가 있다.
    • Phase 5-4: CLUADE.md 하네스 포인터 등록이다. 새 세션에서도 오케스트레이터가 자동 트리거되도록 프로젝트 CLUADE.md에 포인터를 단다. 단, 트리거 규칙과 변경 이력만 기록하고 에이전트와 스킬 전체 목록을 두지 않는다.
    • Phase 5-5: 후속 작업 지원이다. 기존 하네스를 ‘다시 실행’, ‘재실행’, ‘업데이트’, ‘수정’, ‘보완’하는 경우를 대비한다. description에 이 키워드를 포함시키고, 오케스트레이터 Phase 1에 컨텍스트 확인 단계를 넣고, 에이전트 정의에 ‘## 재호출 지침’ 섹션을 두는 것이 Phase 5-5의 내용이다.

Phase 6. 검증

  • 잘 만들어졌는지 검증한다.
    • 6-1 구조 검증: 파일 위치, 프론트매터, 참조 일관성 확인
    • 6-2 실행 모드별 검증: 팀, 서브에이전트, 하이브리드별 체크
    • 6-3 스킬 실행 테스트: With vs Without
    • 6-4 트리거 검증: should-trigger 810개 + should-NOT-trigger 810개
    • 6-5 드라이런 테스트: Phase 순서 검증. 끊어진 링크 탐지
    • 6-6 테스트 시나리오 작성: 정상 시나리오 1개 + 에러 시나리오 1개 이상

Phase 0, 7: 순환 구조와 메타 하네스 루프

  • 하네스는 한 번 만들고 끝나는 산출물이 아니라 계속 관리하는 대상
  • Phase 0: .claude/agents/, .claude/skills/, CLAUDE.md를 먼저 분석하여, 이번 작업이 신규 구축, 기존 확장, 단순 유지보수 중 어디에 해당하는지 파악한다.
    • 기존 확장이라면 Phase 1을 건너뛰고 Phase 2부터 시작하는 방법도 있다.
  • Phase 7: 실행 후 피드백을 수집하고, 결과물 품질 문제를 스킬로, 역할 혼동을 에이전트 파일로, 순서 문제는 오케스트레이터로 각각 반영한다.

안티패턴

  • “메타스킬 한 번 돌리면 끝이다"라는 오해
    • 잘 설계된 팀이 나오려면 도메인 맥락이 충분히 주입돼야 하고, 첫 결과물은 Phase 6의 검증 절차를 거쳐야된다. 메타스킬은 손을 대신하는 도구이지, 판단을 대신하는 도구가 아니다.
    • 해결 방법: 메타스킬이 만든 파일을 사람이 직접 읽어 본다.
  • Phase 1을 건너뛰고 바로 Phase 3으로
    • 에이전트의 아키텍처를 결정하지 않고 작성부터하면 결함이된다.
    • 해결 방법: Phase 1의 다섯 항목(도메인, 기존 현황, 코드베이스, 숙련도, 추돌)을 짧더라도 모두 메모로 남긴다.
  • Phase 6의 Assertion이 스킬 유무와 무관
    • 스킬이 있어서 품질이 올랐다고 지레짐작 해버리면 객관적인 검증이 불가능해진다.
    • 해결방법: 단언을 ‘스킬 없이 달성하기 어려운 것’으로 줄인다. PDF 스킬이라면 “테이블 구조가 유지되는기”, “OCR이 한자까지 잡는가"처럼 구체 동작을 측정한다.