하네스엔지니어링(revfactory)

1. 지켜야할 규칙

1. 디렉터리 구조 모든 에이전트와 스킬은 디렉터리 형식에 맞춰 정의된다.

    .claude/agents/{name}.md
    .claude/skills/{skill-name}/SKILL.md
    CLAUDE.md
   

2. 에이전트 정의 방법

    $ cat .claude/agents/{name}.md
    ---
    name: {agent_name}
    description: {에이전트의 역할}
    model: {모델}
    tools: {Bash, Read, Write 등...}
    ---
   
    # Commit Message Author
    ## 핵심 역할
    1.
    2.
    3.
    ...
   
    ## 작업 원칙
    -
    -
    -
    ...
   
    ## 입출력 프로토콜
    - 입력. 
    - 출력. 
    - 형식. 
   

• 주의1 모델은 생략가능하나, 서브에이전트의 모델이 부모 모델과 동일하게 선택된다. 재현가능성을 높이기 위해 유의할것

1. 스킬 정의 방법

    $ cat .claude/skills/{skill-name}/SKILL.md
    ---
    name: {SKILL_name}
    description: {스킬 내용 요약}
    allowed-tools: {Bash Read Write 등...}
    ---
   
    # {SKILL_name} Skill
    {스킬을 통해 수행하는 작업 요약}
    ## Workflow
    1.
    2.
    3.
    ...
   

• 주의1 description은 실제 사용되는 키워드를 넣어 명확하게 표현해야한다. 그렇지 않으면 스킬이 트리거되지 않을수 있다.

    책에서 발췌: 사용자의 평범한 한마디에 트리거되려면, 실제로 쓸 법한 자연어 표현을 description에 직접 넣어야 합니다.
  

• 주의2 스킬의 이름은 디렉토리 이름과 동일해야한다. 스킬 정의 문서는 SKILL.md 이다.
• 주의3 툴을 작성할때 에이전트는 tools, 스킬은 allowed-tools 이다.

1. 오케스트레이터(프로젝트 규칙)정의 방법

    $ cat CLAUDE.md
    # {프로젝트 요약}
    {프로젝트에서 수행하고자 하는 작업 요약}
   
    ## 규칙
    - {최종산출물의 형식}
    - 중간 산출물은 `_workspace/`에 둔다.
    - 에이전트는 `.claude/agents/`, 스킬은 `.claude/skills/`에 정의한다.
   

      * 주의1 책에서 이르기를 오케스트레이터는 `누가, 언제, 누구와, 무엇을 하는가` 를 책임진다고 설명하고, 실제 구현부는 CLAUDE.md 와 세션의 런타임(SKILL.md 의 Workflow)이라고 설명한다.
   

2. 책임 분산(단일 책임 원칙) “하네스는 누가(Agent), 어떻게(Skill), 언제·누구와(Orchestrator)라는 세 가지 요소로 나뉘며, 이들은 독립적으로 설계되고 실행 시점에만 맞물린다.”…책에서 발췌
   • 에이전트는 역할이다(누구인가).
   • 스킬은 절차이다(어떻게 하는가).
   • 오케스트레이터는 지휘자이다(언제,누가할것인가).

2. 시행착오와 경험

1. 에이전트간의 상호 호출을 결정하는 것은 SKILL.md 의 Workflow 에 정의된다.
2. 에이전트간의 소통은 메모리상에서 이루어지지 않고 파일을 통한다. -> 장점1: 중간 산출물을 남겨 사람의 개입이 용이함 -> 단점1: 파일 read/write 과정 자체가 병목이 될수 있다.
3. 일반적으로 SKILL.md 는 절차를 책임진다. 때문에 오케스트레이터의 역할을 침범하지 않으나, 예외적으로 메타스킬(작업 절차를 정의하는 스킬)에 대해서만 허용한다.
4. 책에서 제시한 6문제

    Q1. "PR 리뷰 시 반드시 보안 관점을 포함한다."
    Q2. "커밋 메시지는 Conventional Commits 형식으로 작성한다."
    Q3. "보안 리뷰어 → 성능 리뷰어 → 테스트 리뷰어 순서로 실행한다."
    Q4. "PDF 추출 실패 시 OCR로 재시도한다."
    Q5. "팀원 절반 이상 실패 시 사용자에게 확인을 받는다."
    Q6. "보안 리뷰어는 Read·Grep 도구만 쓸 수 있다." 
   

    A1. 에이전트(에이전트의 작업 원칙)
    A2. 스킬(형식 지식 - 절차 자산)
    A3. 오케스트레이터(실행 순서 설계) 
    68 Part 02 하네스 구성하기 — 에이전트·스킬· 오케스트레이터
    A4. 스킬(작업 내부의 에러 처리 절차)
    A5. 오케스트레이터(팀 단위 에러 정책)
    A6. 에이전트(도구 권한 - 최소 권한 원칙) 
   

   • 분류를 할때, 다음과 같은 기준을 적용한다.
   1. 정체성-에이전트
   2. 구체적인 절차-스킬
   3. 언제(어떤 조건에서)누가 일을 하는가-오케스트레이터

현재 진척도: ~70page