AI 에이전트 개발 팀의 '헌법'을 어떻게 설계했는가 — 3계층 거버넌스의 기록

「안전한 전사(Safe Transcription)」 개발에서는 여러 개의 Claude Code 에이전트가 병행하여 작동하고 있습니다. lead, dev, PO, webmaster, qa, claude-code-guide — 역할이 다른 에이전트들이 동일한 리포지토리(Repository)를 다루는 구성입니다.

처음에는 가벼운 마음으로 시작했지만, 곧 어려움에 직면했습니다. 누가 무엇을 업데이트해도 되는지가 모호하여 동일한 파일을 동시에 수정해 충돌이 발생하거나, 리뷰 권한이 한곳에 집중되어 병목 현상(Bottleneck)이 발생하는 등의 문제가 연속되었기 때문입니다.

그때마다 "규칙을 추가한다"는 임시방편으로 대응해 오다 보니, 어느덧 팀의 규율이 3계층으로 정리되었습니다. 이 기사는 그 경위와 현재의 형태를 기록한 것입니다.

3계층 구조가 된 경위

현재의 거버넌스(Governance)는 역할이 다른 세 종류의 문서로 구성되어 있습니다.

계층	문서	역할
상층	AI_WORKFLOW.md	헌법 본체 (5대 원칙 · 역할 정의 · 기본 규칙)
중층	CONSTITUTION.md	운용 규범 (조문 단위의 조작 규약)
하층	state.json / HANDOFF.md	런타임 상태 · 인수인계

상층일수록 추상적이며 개정이 드물고, 하층일수록 구체적이며 빈번하게 업데이트됩니다. 처음부터 이렇게 설계한 것이 아니라, 충돌의 종류가 다르다는 것을 깨달을 때마다 계층이 나뉘어 갔습니다.

• "역할의 정의"와 "일일 업데이트"가 같은 파일에 섞이면, 상층의 안정성이 깨진다.
• "조문의 편집"과 "인수인계 기록"이 섞이면, 편집 권한을 설계할 수 없다.

계층이 나뉘어 있지 않았을 때는 HANDOFF.md를 보더라도 "이것이 규율인지 인수인계인지" 판별할 수 없었습니다.

자율 실행 규칙 — 누가 무엇을 편집해도 되는가

CONSTITUTION.md의 제2조에는 "자율 실행 규칙"이라는 섹션이 있습니다. 에이전트가 "확인 없이 실행해도 되는 것"과 "lead에게 판단을 구해야 하는 것"을 명시적으로 구분한 것입니다.

발췌하면 다음과 같은 분위기입니다.

2-1. 실행해도 좋은 것 (확인 불필요)
- 파일 읽기
- 로컬 파일 생성 · 편집
...

이 규칙이 있으면 subagent는 판단 없이 움직일 수 있습니다. "이것을 해도 되는가"를 매번 LLM에게 추론하게 하는 것보다, 확정적인 리스트가 더 빠르고 안전합니다.

충돌 #1: HANDOFF.md의 쓰기 충돌 (Issue #444)

첫 번째 큰 충돌은 HANDOFF.md의 쓰기 충돌이었습니다. 여러 에이전트가 동일한 파일을 동시에 Edit 하여, 나중에 작성된 내용이 이전 내용을 덮어써서 소실되는 사고가 발생했습니다.

원인은 명확했습니다. HANDOFF.md의 편집 권한을 lead와 webmaster 모두에게 부여했기 때문이었습니다. "상담역인 webmaster가 상황을 정리한다", "실행역인 lead가 판단을 기록한다"가 당초의 역할 분담이었으나, 결과적으로 누가 최종 책임자인지가 모호해졌습니다.

해결책은 간단했습니다. HANDOFF.md와 state.json의 편집을 lead 전임으로 지정하는 것이었습니다. webmaster는 GitHub Issue 조작에만 집중하도록 했습니다.

변경 전: webmaster → HANDOFF.md 관리 · state.json 업데이트 · Issue 조작
변경 후: webmaster → GitHub Issue 조작만 수행
변경 전: lead → git commit · deploy · (위임 중)
...

이로써 충돌은 구조적으로 사라졌습니다. 동시에 "책임 소재가 모호하다"는 또 다른 문제도 함께 해결되었습니다.

충돌 #2: 리뷰 권한의 일극 집중 (Issue #550)

운용을 지속하다 보니 또 다른 문제가 나타났습니다.

governance 관련 개정 PR이 늘어날 때마다 모든 것을 lead가 PR을 생성하고 리뷰하는 구조였기 때문에, lead가 메인 기능 개발과 governance 개정 모두를 직렬로 처리해야 하는 상황이 되었습니다. lead가 병목(Bottleneck)이 되어 기능 개발이 중단되는 현상이 발생했습니다.

이것 역시 해결책은 "권한의 재분배"였습니다.

파일	편집 권한
AI_WORKFLOW.md (헌법 본체)	lead 전임
CONSTITUTION.md (조문)	lead / PO / webmaster
.claude/agents/*.md (에이전트 정의)	lead / PO / webmaster
HANDOFF.md / state.json	lead 전임

핵심은, **"헌법 본체(AI_WORKFLOW.md)\

안전한 녹취(Safe Transcription)라는 서비스를 만들고 있습니다. 취재나 회의 음성을 저희 전용 서버에서 처리하며, Google이나 OpenAI와 같은 외부 AI 기업에는 전송하지 않도록 설계된 SaaS입니다. '사적인 대화를 외부 AI 서비스에 가볍게 넘겨도 괜찮은가?'라는 불안감에서 시작된 프로젝트입니다. 여러 개의 Claude Code 에이전트와 함께 개발하고 있습니다.

Discussion