여러 에이전트가 동시에 작성하는 화이트보드를 개별 파일과 단일 집약자로 파손 없이 구현하기

이 글은 시리즈 「자율 운영의 토대를 통째로 읽기: claude-code-repository-base 전격 분석」의 제 9회(총 10회)입니다. Claude Code에 매번 같은 지시를 할 필요가 없도록, 규칙(rule), 후크(hook), 스킬(skill), 도구(tool)를 한 세트로 모아 공개한 자작 리포지토리 kai-kou/claude-code-repository-base (MIT)을 만든 본인이 해설하는 연재입니다. 설계 의도뿐만 아니라, 실제로 작동시켜 확인한 결과(본인조차 알지 못했던 허점 포함)를 그대로 담았습니다. 게재되는 실행 결과와 수치는 모두 각 회 작성 시점에 다시 취합하고 검증했으며, 커밋 SHA는 매회 서두에 기재합니다.

제 리포지토리에서 재현하고 싶은 분들을 위해: 같은 리포지토리를 「어떻게 넣고, 어떻게 돌리고, 어떻게 추적할 것인가」의 절차서로 작성한 Zenn Book을 공개했습니다(유료 500엔・체험 읽기 가능).

시리즈 전체 목차

• 제 1회 Claude Code에 매번 같은 지시를 할 필요가 없도록, 운영의 토대를 리포지토리 하나로 통합하기
• 제 2회 git push origin main | tee log 로 보호(protection)가 통과하는 것을 막기 위해, 명령어 분할로 다시 차단하기
• 제 3회 베이스를 별도 리포지토리에 배포하는 2가지 경로를 dry-run으로 실행하기 (apply-to-repo.sh와 bootstrap.sh)
• 제 4회 Stop 후크(hook)를 5개 나열했더니 첫 번째 것만 읽히는 바람에, 라우터 하나로 통합하기
• 제 5회 컨텍스트 압축으로 작업이 사라지는 것을, 압축 전후의 2단계 WIP 커밋으로 방지하기
• 제 6회 sandbox.enabled를 true로 해도 클라우드에는 bwrap이 없어, 허가 목록을 벗어나 실행되다
• 제 7회 「확인해도 될까요?」를 6가지 유형으로 한정했더니, 그 외는 전부 자율 실행이 되다
• 제 8회 규칙과 교훈(lesson)을 계속 늘리지 않기 위해, 상주 바이트 예산과 「승격 = 물리 삭제」를 기계적으로 강제하기
• 제 9회 여러 에이전트가 동시에 작성하는 화이트보드를 개별 파일 + 단일 집약자로 파손 없이 구현하기 (본문) - 제 10회 10회를 다 읽었다면, 자신의 리포지토리에 가장 먼저 가져와야 할 3가지는 무엇인가 (공개 예정)

검증 시점: base kai-kou/claude-code-repository-base

(MIT) HEAD 40551b9

(2026-10-04 JST에 클론하여 확인)

여기부터는 제 5부 「구조와 출구」입니다. 제 8회까지는 규칙의 내용과, 규칙을 계속 늘리지 않기 위한 상한선을 다루었습니다. 이번에는 하나의 세션 내에서 여러 에이전트가 동시에 작동할 때의 구현 패턴을 다룹니다.

서브 에이전트를 병렬로 기동하여 같은 Markdown 파일에 의견을 추가하도록 하는 장면을 상상해 보세요. 3명이 동시에 「파일을 읽고, 끝에 추기하고, 다시 쓰기」를 한다면, 누군가의 추가 내용이 사라지거나, 작성 중인 상태의 파일이 남지 않을까요? base에는 이 걱정을 설계로 없애기 위한 tools/discussion_whiteboard.py라는 작은 도구가 들어 있습니다.

비슷한 문제는 Claude Code 본체에서도 보고되었습니다. anthropics/claude-code Issue #29217 (2026-02-27 개설・미구현으로 종결)은, 여러 Claude Code 세션이 같은 디렉토리에서 동시에 작동할 경우, .claude.json에 대한 비원자적(non-atomic) 쓰기가 충돌하여 파일이 손상된다는 보고입니다. 보고자의 환경에서는 40분 동안 파손된 파일의 백업이 165개나 만들어졌습니다. 이는 에이전트가 토론용 파일에 쓰는 이야기는 아니지만, 본체 설정 파일에 관한 것입니다. 다만, 「여러 작성자가 같은 파일을 비원자적으로 덮어쓰면 손상된다」는 구조는 같기 때문에, 화이트보드 설계 코멘트에서는 동시 쓰기 파손의 함정 예시로 이 Issue를 언급하고 있습니다.

대상 독자는 Agent Teams나 서브 에이전트의 병렬 실행으로, 공유 파일에 대한 동시 쓰기가 손상되지 않을지 불안해하는 분들입니다.

Agent Teams의 네이티브 기능 사용법 자체는 이미 발표된 'Claude Code Agent Teams 완전 가이드'에서 총론적으로 다루었습니다. 이번에는 그곳에서 다루지 않았던 '같은 파일에 여러 작가가 존재하는 상태를 어떻게 만들지 않느냐'라는 1가지 도구 구현 패턴에 초점을 맞춥니다.

• base HEAD 40551b9을 scratchpad로 clone한 것 - Python 3.11.15 (Linux 클라우드 실행 환경)

• 데모는 content/discussions/를 오염시키지 않도록, tools/ 별도의 디렉터리에 복사된 샌드박스에서 실행

• 작가별로 1회의 게시물(post)을 하나의 고유한 파일로 만들고, 사람이 읽는 whiteboard.md는 집약자(orchestrator)만 생성(render)합니다. 같은 파일에 2명 이상의 작가가 존재하는 순간을 만들지 않는 설계입니다 - 각 파일의 쓰기는 tempfile.mkstemp → fsync → os.replace 순서로 진행하여, 작성 중인 파일이 보이지 않도록 합니다 - --self-test는 24개의 프로세스로 동시에 post한 후 render하며, 건수와 모든 게시물의 본문, 외부 기재가 사라지지 않는지 확인합니다. 집필 시점의 실행은 종료 코드 0이었습니다. 자체 테스트 통과와 실제 운영에서 파손이 한 번도 일어나지 않은 것은 별개의 주장입니다. 후자는 확인하지 않았습니다.

• 이 자체 구현은 네이티브 Agent Teams가 동등한 메커니즘을 갖추게 되면 대체될 전제 하의, 유효기간이 있는 부품입니다.

동시 쓰기에서 발생하는 파손은 크게 2가지로 나뉩니다.

작성 중인 상태가 보이는 것(torn write): 쓰기 도중에 다른 프로세스가 읽으면, 절반만 작성된 내용을 읽어버립니다. -
업데이트가 사라지는 것(lost update): 2명이 같은 파일을 읽고 각각 추가하여 되돌리면, 나중에 작성한 쪽이 앞의 추가 내용을 덮어씁니다.

Issue #29217에서 제안되었던 수정은 임시 파일에 쓰고 리네임하는 방법과, flock을 이용한 잠금(lock)의 조합이었습니다. 전자는 첫 번째 경우에 효과적이며, 후자는 두 번째 경우에 효과적인 대책입니다. 화이트보드에서는 첫 번째 경우를 원자적 쓰기로 처리하고, 두 번째 경우는 애초에 같은 파일을 2명이 수정하지 않도록 하여 피했습니다. 잠금을 사용하지 않은 것은, 잠금의 미사용이나 해제 누락이 발생할 여지를 작가들 간의 약속이 아니라 파일 구성 측면에서 없애고 싶었기 때문입니다.

각 에이전트가 작성하는 것은 자신 전용 파일일 뿐이며, whiteboard.md에 쓰는 것은 render를 호출하는 집약자 1명뿐입니다. 어떤 파일을 보아도 작가는 1명밖에 없습니다.

툴 시작 부분의 docstring에 설계의 요점을 정리하여 적어두었습니다.

## 설계 (동시 쓰기 파손의 구조적 배제)
공식적인 함정: 여러 에이전트가 '동일 파일'에 동시 쓰기를 하면 파손할 수 있음
(claude-code Issue #29217). 본 툴은 Anthropic의 멀티 에이전트 연구 시스템이
...

참고한 Anthropic의 기사

일시 파일을 쓰기 위치와 같은 디렉토리에 만드는 이유는, os.replace가 동일한 파일 시스템 내에서의 교체(replacement)가 되도록 하기 위함입니다. 읽는 입장에서는, 교체 전의 오래된 내용과 작성이 완료된 새로운 내용 둘 중 하나만 볼 수 있습니다. post도 render도 그리고 meta.json 업데이트도 모두 이 함수를 거칩니다.

render는 entries/를 다시 읽어서 whiteboard.md를 매번 통째로 새로 만듭니다. 따라서, 게시물이 아직 1건도 없는 상태에서 render가 실행되면, 누군가가 직접 작성한 whiteboard.md를 빈 목록으로 덮어쓰게 됩니다. 이를 막는 가드(guard)를 넣었습니다.

# 크로버 방지: entries가 비어 있고 기존 whiteboard.md가 「외부 기재(표식 없음)의 비공백」이라면 덮어쓰지 않음
wb_path = board / "whiteboard.md"
if not entries and wb_path.exists():
...

render가 생성한 파일의 첫 줄에는 <!-- discussion_whiteboard:auto -->라는 표식이 들어갑니다. 표식이 없는 비공백 파일은 「render 외에 작성된 것」으로 간주하여 건드리지 않습니다.

역할 분담은 운영 규칙인 docs/rules/discussion-whiteboard-rules.md에 다음과 같이 적혀 있습니다.

자기 테스트 내용은 24개의 프로세스를 동시에 시작하여 post하게 하고, 모두 끝난 후에 render하는 것입니다.

N = 24
procs = [multiprocessing.Process(target=_worker, args=(i,)) for i in range(N)]
for p in procs:
...

각 워커는 투고자를 a / b / c의 3명으로 돌리고, 라운드를 1과 2로 나눕니다. render 후에 확인하는 것은 다음 4가지입니다.

• entries/의 파일 수가 24와 일치하는 것 -
  whiteboard.md에 「병렬 투고 #0」~「병렬 투고 #23」의 본문이 1건도 빠짐없이 들어가 있는 것 - 「라운드 1」과 「라운드 2」의 제목이 모두 있는 것
• 표식이 없는 whiteboard.md를 외부에서 작성한 의제로 render 해도, 그 내용이 사라지지 않는 것 (위의 크로버 방지 가드)

검증 시점의 HEAD로 실행한 결과입니다 (임시 디렉토리 이름은 생략하고, 24줄에 걸친 투고 파일 경로는 처음 2줄만 올립니다. init 후의 external 의제 출력 행은 생략했습니다).

$ python3 tools/discussion_whiteboard.py --self-test
✅ init: /tmp/tmpXXXX/selftest
whiteboard: /tmp/tmpXXXX/selftest/whiteboard.md
...

종료 코드는 0이었습니다. 코드 상에서, _self_test()가 0을 반환하는 것은 위의 4가지가 모두 통과했을 때만이며, 하나라도 실패하면 ❌ 메시지를 출력하고 1을 반환합니다.

자기 테스트는 함수를 직접 호출했기 때문에, CLI로 외부에서 실행했을 때의 모습도 확인했습니다. REPO_ROOT는 스크립트 위치로부터 결정되므로, tools/ 폴더 전체를 샌드박스로 복사하여 그곳에서 의제 demo를 만들고 3개의 post를 동시에 던졌습니다 (경로는 간략화했습니다).

entries/에는 3개의 파일이 각각 생성되어 있었습니다.

r01_1791083225_6548_ebe102_x_claim.md
r01_1791083225_6549_17a641_y_claim.md
r01_1791083225_6550_19b426_z_claim.md

각 파일의 내용은 HTML 주석 헤더와 본문만 포함하고 있습니다.

<!--entry
author: x
round: 1
...

렌더링된 whiteboard.md는 다음과 같습니다. 3개 모두 누락 없이 집약되었고, 게시물 수도 3개로 표시됩니다.

<!-- discussion_whiteboard:auto -->
# 🧑🏫 토론 화이트보드: 데모
- 주제 ID: `demo`
...

설계 주석과 운영 규칙에서는 파일명을 r01_<ns>_<pid>_<rand>_...로 작성하고 있습니다. 그런데 생성 코드는 timestamp():.0f, 즉 초 단위의 정수입니다. 데모의 3개 파일 모두 1791083225로 같은 초였고, 자체 테스트의 2줄도 같은 1791083261이었습니다.

그럼에도 불구하고 파일명 충돌이 없었던 것은 pid(6548 / 6549 / 6550)와 난수가 달랐기 때문입니다. 고유성을 담당하는 것은 시간이 아니라 pid와 난수이며, 시간은 정렬의 단서에 불과합니다. 주석의 <ns>라는 표기는 독자에게 '나노초 단위로 고유하다'고 오해하게 만들므로 수정해야 할 설명이라고 생각합니다.

이것은 정렬 순서에도 영향을 줍니다. render는 (round, ts, 파일명)으로 정렬하지만, ts 역시 초 단위이기 때문에 같은 초의 게시물은 파일명 순, 실질적으로는 pid의 문자열 순서로 정렬됩니다. 데모에서 x → y → z 순서로 배열된 것은 작성 순서가 아니라 pid 순입니다. 병렬적인 주장들 사이에는 선후 관계가 없으므로 실제 피해는 없지만, '표시 순서 = 게시물 순서'는 아닙니다.

이 초 단위의 충돌은 실제 토론 로그에서도 발생했습니다. 나중에 인용할 연재 기획 논의에서 lead가 작성한 합의(consensus)와 판정(verdict) 모두 파일명의 시간이 1788423864로, pid는 28306과 28307이었습니다. 별도의 프로세스였기 때문에 파일은 분리되었지만, 같은 프로세스가 같은 초에 2번 post한 경우에는 6자리 난수에만 의존해야 합니다. 6자리 16진수는 약 1,678만 가지이므로 충돌은 거의 일어나지 않지만, 충돌했을 때는 os.replace가 이전 게시물을 조용히 덮어씁니다. 0이 아니라는 점은 언급해 두겠습니다.

fsync하는 것은 임시 파일의 내용물에 대해서만이며, rename을 기록하는 디렉터리 쪽은 fsync하지 않습니다. POSIX 일반론으로 볼 때, 이는 '작성 중인 상태가 보이지 않음'은 보장하지만, 정전 직후에 rename 자체가 남아있다는 것까지는 보장하지 않습니다. 토론 도중에 다운되어도 곤란한 것은 마지막 1개의 게시물이 남는지 여부이므로, 현재 용도로는 허용합니다. 다만, 같은 함수를 '절대 손실해서는 안 되는 상태 파일'에 재사용할 것이라면, 디렉터리에 fsync를 추가해야 합니다.

코드를 다시 읽어보니, 자체 테스트 범위 밖이라고 알게 된 점이 두 가지 있습니다.

post와 render가 동시에 실행되는 경우: 자체 테스트는 모든 프로세스의 join()을 기다린 후에 render합니다. 임시 파일은 entries/ 안에 .tmp_로 시작하고 .md로 끝나는 이름으로 생성되므로, post 도중에 render가 *.md

여러 에이전트가 동시에 작성하는 화이트보드를 개별 파일과 단일 집약자로 파손 없이 구현할 때, 모든 내용을 모은 후 임시 파일을 가져올지 여부는 이번에 확인하지 못했습니다. 현재는 'render는 모든 사람의 post가 끝난 후에 집약자가 호출한다'라는 운영 규칙을 가지고 이 상황이 발생하지 않도록 하고 있습니다 -
프로세스 시작 방식: 자체 테스트에서는 함수 내에서 정의한 _worker를 multiprocessing.Process에 전달하고 있습니다. 이번에는 Linux 환경에서만 작동했기 때문에, 시작 방식이 기본값인 spawn으로 설정된 환경에서도 동일하게 통과하는지는 확인하지 못했습니다.

그리고 가장 중요한 경계가 있습니다. 자체 테스트가 성공했다는 것만으로 말할 수 있는 것은 '24개의 병렬 post와 그 이후의 render 과정에서 건수나 본문이 누락되지 않았다'라는 점까지입니다. 실제 운영 환경에서 화이트보드가 단 한 번도 손상된 적이 없다고는 할 수 없습니다. 왜냐하면 손상을 감지하고 기록하는 메커니즘을 넣지 않았고, 그렇지 않았다는 것을 보여주는 데이터가 없기 때문입니다.

base에서는 '에이전트 팀(agent team)'에 두 가지 모드를 준비해 두었습니다. docs/rules/agent-team-summary.md의 표를 그대로 인용합니다.

fan-out에서는 각 서브 에이전트의 결과가 메인 세션에 돌아올 뿐, 에이전트들끼리는 서로의 의견을 읽지 않습니다. 공유 파일이 필요하지 않기 때문에 화이트보드도 사용하지 않습니다. 화이트보드가 필요한 것은 참여자들이 다른 참가자의 주장을 읽고 반박하는 논의형(discussion-type)뿐입니다.

논의형 리뷰를 실행하는 .claude/skills/discussion-review/SKILL.md는 이 도구를 다음 순서로 호출합니다.

여기서 SendMessage를 '다음 라운드로 넘어가는 신호'에만 사용한 데에는 이유가 있습니다. 스킬 절차서에는 수신 측이 턴을 마친 후에는 서브 에이전트의 메시지가 사라진다는 실측 기록이 되어 있습니다. 전송은 성공을 반환하기 때문에, 도착했는지 여부는 보낸 쪽에서는 알 수 없습니다. 그래서 논의 내용은 모두 화이트보드라는 파일에 모으고, 메시지에는 아무것도 담지 않는 형태로 했습니다.

이 연재물의 분량이나 순서는 논의형 리뷰를 통해 결정되었습니다. 논의 로그는 content/discussions/base-series-planning-20260903/에 남아 있으며, 참여자 5명(series_architect/reader_value/evidence_auditor/pipeline_engineer/skeptic)와 lead의 게시물이 entries/에 12개의 파일이 있고, render 시점의 게시물 수도 12건이었습니다.

이번 제9회 역시 이 논의를 통해 폐기 후보가 되었습니다. 라운드 1에서 skeptic은 다음과 같이 주장했습니다.

폐기 이유: 구현 400줄・[강조어는 생략] 니치성. '다수 에이전트의 동시 작성'이라는 문제는 다른 프로젝트에 존재하는지 불분명함.
생존 조건: 'Agent Teams native whiteboard로 2027년에 대체될 것으로 예상됨'을 명시할 것. 단기적인 임시방편(workaround)으로 기사화한다면.

라운드 2에서 series_architect는 자체 테스트 실행 결과를 근거로 '유지 및 격상'이라고 반박하는 동시에, skeptic의 조건만은 받아들였습니다.

skeptic의 요구사항('2027년에 네이티브 대체될 것으로 예상됨을 명시')만을 채택하여 본문에 유효기간 주석을 넣는 것. lead의 판정(verdict)에서는 제9회의 demo_plan

에이전트가 동시에 작성하는 화이트보드를 개별 파일과 단일 집약자로 파손 없이 구현할 수 있다는 내용입니다. 원문에는 '네이티브 기능으로 대체 가능성'을 유효기간처럼 명시하고 있습니다. 이 글의 마지막에 유효기간 섹션이 있는 것은 이러한 반론과 판정 결과 때문입니다. 2027년이라는 구체적인 연도는 논의 과정에서 skeptic가 제시한 가정이며, 근거 있는 예측이 아니므로 본문에는 포함하지 않았습니다.

'같은 파일의 작성자를 항상 1명으로 유지한다'는 생각 자체는 에이전트에만 국한된 것이 아닙니다. 여러 프로세스나 작업(job)이 하나의 집계 파일을 업데이트하는 상황이라면, 작성자별 개별 파일과 집약 역할만 하는 집계 파일로 분리함으로써 잠금(lock) 없이 lost update를 방지할 수 있습니다. 개별 파일의 쓰기에는 임시 파일과 os.replace 조합을 사용하면 충분합니다.

게다가 이 구현에는 유효기간이 있습니다. Claude Code의 Agent Teams 공식 문서에 따르면, 2026-10-04 시점을 기준으로 이 기능은 experimental로 분류되어 있습니다. 같은 페이지에서 두 명의 팀원이 같은 파일을 편집할 경우 덮어쓰기가 발생하므로, 팀원별로 다른 파일을 담당하도록 권장하는 설명이 있습니다. 태스크 경쟁에는 파일 잠금(file lock)을 사용한다고도 언급되어 있습니다. 즉, 네이티브 기능 역시 작성자를 분리한다는 동일한 방향으로 설계되었습니다. 공유 논의 문서를 병렬로 작업해도 손상 없이 유지하는 메커니즘이 네이티브 측에 도입된다면, 이 도구는 역할을 다하게 되므로, 그때는 대체될 것을 전제로 사용하고 있습니다.

다음 10회차에서는 총 10회차를 돌아보며 자신의 리포지토리에 가장 먼저 가져가야 할 것이 무엇인지 정리할 예정입니다.

• 규칙과 교훈을 계속 늘리지 않기 위해, 상주(常駐) 작업 예산과 '승격 = 물리적 삭제'를 기계적으로 강제했습니다 (연재 제8회).

• '확인해도 될까요?'를 6가지로 제한하자, 그 외의 모든 것은 자율 실행이 되었습니다 (연재 제7회).

• sandbox.enabled를 true로 설정했음에도 클라우드 환경에는 bwrap이 없어 허용 목록을 우회했습니다 (연재 제6회).

kai-kou/claude-code-repository-base (MIT・검증 시점 HEAD 40551b9) -
tools/discussion_whiteboard.py (_atomic_write 및 render의 클로버 방지, --self-test의 N = 24) -
docs/rules/discussion-whiteboard-rules.md (파일 구성 및 명령어별 작성자) -
docs/rules/agent-team-summary.md (fan-out과 논의형 분배) -
.claude/skills/discussion-review/SKILL.md (논의형 리뷰 실행 절차) -
anthropics/claude-code Issue #29217 (.claude.json 동시 작성 손상 보고) - How we built our multi-agent research system (Anthropic)

• Orchestrate teams of Claude Code sessions (Claude Code Docs)

➡️

다음 예고: 제10회차에서는 10회차 내용을 모두 읽은 후, 자신의 리포지토리에 가장 먼저 가져가야 할 3가지가 무엇인지 최종 정리합니다. 총 10회차를 표로 되돌아보며 최소 비용으로 자신의 리포지토리에 도입할 3가지에 초점을 맞춥니다.

공개된 회차 (7편 · 어느 시점부터든 읽을 수 있습니다)

• 제1회 Claude Code에게 매번 같은 지시를 할 필요가 없도록, 운영 기반을 리포지토리 하나로 통합했습니다.
• 제2회 git push origin main | tee log에서 보호 규칙이 우회되었기 때문에, 명령어 분할로 막았습니다.
• 제3회 베이스를 별도 리포지토리로 배포하는 2가지 경로를 dry-run으로 실행합니다 (apply-to-repo.sh와 bootstrap.sh).
• 제4회 Stop Hook을 5개 연결했더니 첫 번째 것만 읽혔기 때문에, 라우터 하나로 통합했습니다.
• 제5회 컨텍스트 압축으로 작업 내용이 사라지는 것을, 압축 전후의 이중 WIP 커밋으로 방지했습니다.
• 제6회 sandbox.enabled를 true로 설정했음에도 클라우드 환경에는 bwrap이 없어 허용 목록을 우회했습니다.
• 제7회 '확인해도 될까요?'를 6가지로 제한하자, 그 외의 모든 것은 자율 실행이 되었습니다.

자신의 리포지토리에서 재현하고 싶은 분들은, 같은 리포지토리를 '어떻게 넣고, 어떻게 돌리고, 어떻게 추적할지'에 대한 매뉴얼로 작성된 Zenn Book(유료 500엔・미리보기 가능)을 참고해 주세요.