Claude Code 위에 9개 에이전트 체제를 구축하여, 거버넌스 인시던트(governance incident) 19건, trigger 리스트 7개 항목, Playbook 87개를 운용 중이다.

여기서 말하는 '자기 개선(self-improvement)'이란 '실패가 발생하면 수정하는 것(self-correction)'이 아니라, '실패하지 않았더라도 더 나은 구조를 도입하는 것(사전 제안 포함)'을 의미한다. 사후 대응만으로는 '자기 수정(self-correction)'에 그치지만, 사전 제안 경로가 더해져야 비로소 '자기 개선(self-improvement)'이 된다.

이 조직이 '자기 개선할 수 있다'고 말할 수 있는 이유는, 피드백의 입구가 에이전트 측에서 자발적으로 올라오도록 설계되어 있기 때문이다. 실패가 발생하면 사고 기록 파일로서 구조화되며, 그 형식이 trigger 리스트로 변환된다. 개선안을 발견하면 proposals: 필드를 통해 COO에게 전달하고, 사용자 승인을 거쳐 규칙이 업데이트된다. 네거티브(사고 기록)와 포지티브(proposals), 양쪽의 입구가 에이전트의 발화(trigger)로 설계되어 있다는 점이 '규칙을 인간이 일방적으로 써 내려가는 조직'과의 본질적인 차이다.

1. Claude Code 하네스의 핵심 — 전제·입구·그릇으로 보는 자기 개선 루프

이 하네스 설계의 핵심은 에이전트의 수나 전문화의 세밀함이 아니라, 에이전트 측에서 조직 규칙으로 피드백이 올라오는 구조에 있다. 조직 전체도를 설명한 뒤, 거버넌스 계층을 '전제·입구·그릇'의 3가지 카테고리로 설명한다.

조직 전체상: 이 거버넌스는 어떤 조직 위에 올라가 있는가

조직 구성은 다음과 같다.

위임은 COO를 기점으로 방사형으로 뻗어나가며, 기사 공개 플로우라면 COO → researcher → writer → reviewer/reader → writer → secretary의 연쇄가 된다. COO를 제외한 8개체가 서브 에이전트(sub-agent, Claude Code의 공식 용어)로서 동작하며, tools 제한과 Playbook으로 역할이 구분되어 있다.

거버넌스 계층의 3가지 카테고리 대응표

양쪽 입구 모두 에이전트 측에서 발화한다. 규칙을 사용하는 측이 '사용해 본 결과의 결함·개선안'을 구조화하여 상신하고, 그것이 다음 규칙이 되는 설계다.

전제: 4가지 권리 — 경로의 제도적 근거

CLAUDE.md의 '가치관 거버넌스' 절에 정의된 4개 조항이 입구와 그릇을 성립시키는 제도적 전제다.

이 4개 조항은 의도적으로 추상화되어 있다. '언제 제안을 올릴 것인가'의 구체적인 발화 조건은 별도의 레이어인 trigger 리스트에 위임한다. 헌법을 그대로 운용하면 auto mode(무인으로 연속 작업을 수행하는 모드)에서 발화 조건을 판정할 수 없어 기능하지 않게 되기 때문이다 (정비 경위는 'Claude Code의 헌법을 썼더니 하루 만에 법률이 된 이야기' 참조).

입구 (네거티브 FB): 사고 기록 (governance-incidents) — 위반·사고를 구조화하기

logs/governance-incidents/

디렉토리에는 규칙 위반, 스크립트 사고, 독단적 판단 사례가 파일로 축적된다. 이 디렉토리의 핵심은 기록 포맷의 표준화다. 포맷에는 「사고 개요 / 피해 범위 / 원인 (독단적 판단 or 트리거(trigger) 간과 or 규칙 미비) / 재발 방지책 / 규칙 업데이트 위치」에 더해, 「trigger 리스트 추가 후보」 섹션이 정의되어 있으며, 최근의 사고 기록에서는 이 섹션을 사용하여 trigger 변환 후보를 명시하고 있다.

이 섹션이 요체다. 자유 기술 형태로 방치하면 「재발 방지책을 작성하고 끝」나기 쉽다. 전용 섹션과 「트리거 / 왜 승인이 필요한가 / 확인 형식」의 3열 테이블 형식을 마련함으로써, 「이 사고로부터 이끌어낼 수 있는 if 문은 무엇인가」라는 변환 작업을 파일 포맷 수준에서 촉진한다. 사고를 기록하는 행위 자체가 그대로 trigger화 검토를 내포하는 설계다.

사고 유형이 기록되면, COO가 규칙 업데이트 위치를 확인하여 사용자에게 상신하고, 승인을 거쳐 trigger 리스트나 Playbook이 다시 작성된다. 네거티브 피드백 (Negative FB) 경로의 실체는 「사고 → 파일 기록 → trigger 변환 후보 명시 → 사용자 승인 → 규칙 업데이트」라는 연쇄다.

proposals:

필드 — 에이전트의 깨달음을 구조화하기

입구 (포지티브 피드백 (Positive FB)): 사고가 발생하기 전의 깨달음을 공유하는 입구 역할을 하는 것이 proposals: 필드다. 깨달음이 있다면 결과물의 YAML 헤더에 다음 형식으로 기술한다.

proposals:
- what: "Playbook X의 절차 3이 실제와 괴리됨"
  why: "명령어 `foo --bar`가 deprecated 되어 에러 발생"
...

COO는 이를 받아 정합성 체크를 수행하고 사용자에게 상신한다. 포맷이 없다면 깨달음은 구두로 묻힐 수 있지만, proposals:가 있으면 「구조화된 개선 신호」로서 반드시 COO의 눈에 들어온다.

global-rules.md에서는 Playbook과 실제 상황의 괴리, 스크립트 에러, 전제의 불일치를 「필수 기록」으로 정하고 있다. "깨달으면 기록한다"가 아니라 "해당 사안이 발생하면 필수 기록한다"라고 적혀 있는 것이 요점이다. 객관적 관측 사안으로 트리거(trigger)되도록 설계함으로써, 개선 신호가 에이전트의 주관적 판단에 의존하지 않게 된다.

그릇: trigger 리스트 · Playbook · global-rules.md — 규칙화된 결과가 쌓이는 곳

trigger 리스트는 「언제 헌법을 발화시킬 것인가」를 열거한 테이블이다. 현재 7개 항목.

이 7개 항목은 실제로 발생한 사고로부터 역으로 도출되었다. 설계 시점부터 망라된 것이 아니라, 사고 유형을 재발시키지 않기 위해 한 줄씩 추가한 결과가 지금의 형태다 (설계 사상과 타 사례와의 비교는 『CLAUDE.md에 「헌법」과 「trigger 리스트」를 적은 이유』 참조).

trigger 리스트 운용의 핵심은 확인 형식의 원칙으로 집약된다.

「무엇을 · 왜 · 부작용은」을 명시한다. 사용자가 1 / OK / 구체적 승인어를 반환할 때까지 실행하지 않는다. 침묵 ≠ 승인.

「침묵 ≠ 승인」이라는 문구는, 「명시적인 거부가 없다 = 진행해도 좋다」라는 해석을 차단하는 if 문이다. trigger 리스트 및 Playbook · global-rules.md는 사고 기록 (Negative FB)과 proposals (Positive FB) 어느 입구로부터도 업데이트를 받는다.

2. 3층 분업 설계 — 거버넌스를 지탱하는 분업 구조

3층 구조는 다음과 같다.

┌─ 거버넌스 층 (전제: 4가지 권리 / 입구: 사고 기록・proposals / 그릇: trigger 리스트・Playbook) ─ 전 계층을 관통하는 규율
├─ 오케스트레이션 층 (COO: 지시・위임・조정)
└─ 전문화 층 (8개 에이전트: architect / devops / researcher / 
...

레이어 1: 오케스트레이션 층 (COO)

COO는 사용자의 지시를 직접 받아 전문 에이전트에게 위임한다. coo-rules.md에서 "직접 수행해도 되는 작업"과 "위임해야 하는 작업"이 명확하게 구분되어 있다. 경미한 파일 수정 및 git 조작은 COO가 직접 실행하고, 설계・구현・장 단위의 집필은 각 에이전트에게 위임한다. 위임에는 오버헤드 (기동 비용・왕복 토큰 소비)가 따르므로, 가벼운 작업의 위임은 역효과를 낳는다. COO는 proposals:를 받아 정합성 체크를 수행하고 사용자에게 상신하는 "중계점"이기도 하다.

레이어 2: 전문화 층 (8개의 서브 에이전트)

전문화 층의 8개 서브 에이전트는 tools: 필드에서 사용할 수 있는 도구가 명시적으로 제한되어 있다. 예를 들어 architect 에이전트는 tools: Read, Grep, Glob, Write만 가지며, Edit도 Bash도 포함되어 있지 않다. 즉, 설계서만 쓸 수 있다. 코드 편집도 셸 명령 실행도 할 수 없다. 이는 사양이며, 설계와 구현을 분리하기 위해서는 설계 담당이 구현 도구를 "가지지 않는 것"이 구조적으로 필요하다. reader (감정 리뷰 담당) 역시 마찬가지로 Read/Grep/Glob/Write만 가능하며, 본문을 직접 수정할 수 없다.

권한 제한이 전문화를 강제하는 이 설계는 "역할의 일탈"을 구조적으로 방지한다. 프롬프트로 "설계만 수행해 주세요"라고 지시하는 것만으로는 에이전트가 작업 도중 "하는 김에 구현까지 해버리자"라고 판단할 수 있다. tools 제한은 그러한 판단 자체를 불가능하게 만든다.

설계 과제와 해결 대응 관계

하단 3개 행이 분업 조직을 "자기 개선이 가능한" 상태로 끌어올리는 설계다.

3. 왜 이 형태로 수렴했는가 — 자기 개선이 성립하고 있다는 증거

본 절에서는 자기 개선이 기능하고 있다는 증거를 네거티브 FB(Negative Feedback)와 포지티브 FB(Positive Feedback) 양쪽의 지표로 제시한다.

증거 1: 네거티브 FB가 기능하고 있다는 증거

logs/governance-incidents/ 디렉토리에는 발생한 사고 유형이 기록되어 있다.

• 거버넌스 인시던트 기록: 19건 - trigger 리스트 항목 수: 7개 항목

19건의 사례로부터 7가지 유형을 trigger 리스트로 도출해냈다. trigger 리스트의 7개 항목이 처음부터 7개였던 것은 아니다. 초기에는 5개 항목으로 운영을 시작했으며, 새로운 사고 유형이 나올 때마다 추가되어 온 "인크리멘털(incremental)한 구축"의 결과다. 사고 기록 포맷이 "trigger 리스트로의 추가 후보" 섹션을 포함함으로써, 이러한 변환 작업을 파일 수준에서 촉진하고 있다.

증거 2: 포지티브 FB가 기능하고 있다는 증거

proposals: 필드를 통한 개선 제안 역시 규칙 업데이트로 이어지고 있다.

• global-rules.md에 "Playbook 괴리・에러 회피 필수 기록" 섹션이 추가된 것 자체가 포지티브 FB의 결과다. 사고가 아니라 "Playbook이 불편하다"라는 인지가 규칙화되었다.
• devops의 settings.local.json 편집 권한이 "사전 승인 불필요・사후 보고 필수"로 운영화되었다. devops 스스로의 제안으로 운영 규칙이 바뀐 사례다.

두 사례 모두 "사고가 발생했기 때문에"가 아니라, "사용해 보니 이렇게 하는 것이 좋겠다"라는 에이전트 측의 깨달음이 올라와 규칙이 업데이트된 사례다.

보충: 이식성과 "수렴했다"라는 표현

이식성은 부분적이다. 이식 가능한 것은 프레임워크(4가지 권한, 사고 기록 포맷, proposals: 포맷, trigger 리스트 형식, tools 제한, 위임 이표)이다. 프로젝트 고유한 것은 내용(trigger의 구체적 항목, Playbook의 절차, 전문 에이전트의 분담)이다. trigger의 내용은 해당 프로젝트가 겪은 실패의 역사에 따라 결정되므로 이식할 수 없지만, "전제·입구·그릇"이라는 프레임워크 자체는 어디에서든 사용할 수 있다.

이 하네스(Harness)는 설계도로부터 역산하여 만들어진 것이 아니다. 헌법을 작성하는 것만으로는 auto mode에서 기능하지 않는다는 실제 관측을 통해, 사고 기록의 구조화와 proposals:가 필요해졌다. 운영 중 발생하는 사고와 깨달음을 하나씩 흡수하여 현재의 형태로 "수렴했다"라고 표현하는 것이 정확하다. 또한, 에이전트 군을 감싸는 제도 설계 전체를 "하네스 엔지니어링 (Harness Engineering)"이라고 부르는 용어가 2026년경부터 정착되고 있다. 본 기사의 설계도 그 맥락에 속한다.

결론: 하네스는 지금도 이 루프 안에 있다

네거티브(사고 기록)와 포지티브(proposals), 양쪽의 입구가 에이전트의 발화(trigger)로 설계되어 있다 — 이것이 "규칙을 인간이 일방적으로 써 내려가는 조직"과 "자기 개선할 수 있는 조직"의 분기점이다.

이 하네스는 "완성된 조직"이 아니다. 내일의 세션에서 새로운 사고 유형이 발견될 수도 있고, 새로운 proposals:가 올라올 수도 있다. trigger 리스트는 또 한 줄 늘어날 것이고, Playbook은 또 다시 쓰여질 것이다.

이 하네스는 지금도 이 루프 안에 있다.

관련 서적

본 기사에서 다룬 "전문화 계층", "거버넌스 계층"이라는 분업 개념은, 인간 소프트웨어 개발 팀을 대상으로 한 서적 『팀 토폴로지 (Team Topologies)』가 제시하는 Stream-aligned team (성과에 직결되는 전문 팀) / Enabling team (전문 지식을 다른 팀에 제공하는 지원 팀)과 유사하다. 이 책은 AI 에이전트 조직을 직접 다루지는 않지만, "책임 분할과 상호작용의 설계"라는 추상적 수준에서는 유추가 성립한다. 인간 팀 설계에 관한 논의를 에이전트 조직에 어떻게 이식할 것인가라는 관점에서 읽으면 시사점을 얻을 수 있다. Amazon

자기 개선 루프를 가진 AI 에이전트 조직을 만들기까지의 시행착오와 설계 원칙을 전자책으로 정리했습니다.

코드를 쓸 줄 모르는 내가 AI에게 "팀"을 갖게 하기까지 (서장·제1부 무료)

이 기사는 はてなブログ (Hatena Blog) 에서의 크로스 포스트입니다.

Discussion