Agent Harness Notes 02. shared-agent-harness를 떼고 프로젝트 경계를 다시 그린 이유

이 글의 핵심은 shared-agent-harness를 별도 저장소로 분리하고, 개인과 회사 도메인의 참조 방향을 고정한 과정입니다.

role/lane is shared, data/surface is isolated까지 정리하고 나면 그다음 질문은 피할 수 없었습니다.

그래서 실제로 어디까지를 shared로 두고, 어디까지를 개인과 회사의 저장소로 떼어낼 것인가.

원칙만으로는 충분하지 않았습니다. 개인 도메인과 회사 도메인이 같은 workspace 안에서 굴러가고, 같은 Claude가 문서와 코드와 회의 메모를 모두 읽을 수 있는 상태라면 언젠가는 사고가 납니다. Agent Harness Notes 01이 경계를 이해한 기록이었다면, 이번 글은 그 경계를 실제 폴더와 저장소 구조로 바꾼 기록입니다.

폴더를 나누는 것이 아니라 책임을 다시 그리는 작업이었습니다

처음에는 ai-survival-log 안에서 다 해결할 수 있을 거라고 생각했습니다.

wiki 문서도 있고, 프로젝트 계획도 있고, 운영 문서도 있고, 블로그 산출물까지 있었습니다. 여기에 회사용 섹션 몇 개만 더 만들면 되는 것 아닌가 하는 유혹이 있었습니다.

그런데 이 방식은 금방 한계를 드러냈습니다.

개인 도메인에서는 raw -> wiki -> output/blog -> site 흐름이 핵심입니다. 반면 회사 도메인에서는 authoring source와 execution surface, approval과 audit의 경계가 더 중요합니다. 같은 "작업"처럼 보여도 저장소가 책임져야 하는 계약이 아예 달랐습니다.

그제야 질문이 바뀌었습니다.

"어떤 프로젝트가 필요한가?"가 아니라 "어떤 책임은 절대 같은 저장소에 두면 안 되는가?"

이 질문으로 넘어가면서 구조가 다시 보이기 시작했습니다.

프로젝트를 쪼갠 이유는 역할이 아니라 계약이 달라서였습니다

최종적으로 남은 축은 개인 authoring, 사이트 presentation, 회사 authoring, 회사 execution, 공용 하네스였습니다.

• ai-survival-log
• ai-survival-log-site
• company-wiki
• company-assistant-ops
• shared-agent-harness

겉으로 보면 그냥 저장소가 늘어난 것처럼 보일 수 있습니다. 하지만 실제 기준은 역할이 아니라 계약이었습니다.

ai-survival-log

개인 도메인의 upstream authoring source입니다.

• 공부
• wiki 수집
• 블로그 초안
• publishable source

이 저장소는 사람이 읽는 지식 그래프와 글쓰기의 기준점을 유지합니다.

ai-survival-log-site

개인 도메인의 downstream presentation layer입니다.

• content rendering
• SEO/runtime presentation
• site-facing asset contract

여기는 source-of-truth가 아니라 보여주는 층입니다.

company-wiki

회사 도메인의 authoring source입니다.

• 회의록
• 기획
• 검수 기록
• 테스트 계획과 결과
• 실행 전 판단 맥락

회사에서 무엇을 왜 하려는지 설명하는 문서는 여기에 남아야 합니다.

company-assistant-ops

회사 도메인의 execution surface입니다.

• approval
• audit
• Gmail/Calendar/Sheets handoff
• follow-up execution

즉 company-wiki가 판단과 맥락을 남기는 저장소라면, 여기는 실제 실행을 감싸는 저장소입니다.

shared-agent-harness

이 저장소가 핵심이었습니다.

처음에는 이걸 별도 저장소로 빼는 것이 과한 것처럼 느껴졌습니다. 하지만 공용 role, lane, cross-validation, workflow gate, domain-context 정책을 개인과 회사 저장소 둘 다에 중복 정의하기 시작하면, 그 순간부터 drift가 생깁니다.

그래서 결국 공용 운영 원칙은 한곳으로 모아야 했습니다. 그게 shared-agent-harness였습니다.

shared-agent-harness는 interface이면서도 단순 문서 저장소는 아니었습니다

이 저장소를 떼어낼 때 가장 조심했던 건 두 가지였습니다.

첫째, 여기가 모든 것을 다 실행하는 오케스트레이터처럼 비대해지면 안 됩니다. 둘째, 반대로 문서만 잔뜩 있는 추상 저장소가 되어도 안 됩니다.

그래서 정의를 이렇게 잡았습니다.

shared-agent-harness는 공용 운영 인터페이스이자 정책 레이어입니다. 그리고 아주 제한된 범위의 공용 executable surface만 가집니다.

여기에는 다음이 들어갑니다.

• role 정의
• lane 정의
• cross-validation 정책
• workflow gate
• domain-context 정책
• approval/validation 관점

그리고 지금은 여기에 더해 안전한 artifact 생성 정도만 엽니다.

즉 shared-agent-harness는 연결된 도메인 저장소들이 어떤 원칙으로 움직여야 하는지를 고정해주는 정책 레이어 역할만 맡습니다.

문제는 코드 분리보다 설계 source 분리였습니다

저장소를 실제로 만든 뒤에 더 까다로운 문제가 나왔습니다.

다른 데스크탑에서 company-wiki, company-assistant-ops, shared-agent-harness만 가져가도 정말 운영이 가능한가.

처음 답은 아직 아니다였습니다.

이유는 단순했습니다. 코드와 폴더는 분리됐지만, 왜 이런 구조인지에 대한 상위 판단은 여전히 ai-survival-log/wiki/projects에 더 많이 남아 있었기 때문입니다.

즉 실행 가능한 껍데기는 생겼지만, 운영 판단의 원문은 아직 upstream 위키에 더 많았습니다.

그래서 구조 변경은 두 번째 단계를 필요로 했습니다.

저장소를 만드는 것만이 아니라, 각 저장소가 실제 operational source가 되도록 문서 source까지 다시 정리해야 했습니다.

그래서 operational source와 history source를 다시 나눴습니다

이 시점부터 작업의 성격이 바뀌었습니다.

이전에는 저장소를 나누는 작업이었다면, 이후에는 어떤 문서가 현재 운영 기준이고 어떤 문서가 히스토리인지 등급을 다시 정하는 작업이 됐습니다.

정리하면 이렇게 됐습니다.

• shared-agent-harness — 공용 운영 원칙의 detached operational source
• company-wiki — 회사 authoring 규칙의 detached operational source
• company-assistant-ops — 회사 execution/approval/audit 규칙의 detached operational source
• ai-survival-log/wiki/projects — 설계 히스토리와 판단 배경을 보관하는 history source

이 구분이 중요했던 이유는, 다른 데스크탑에서 회사 운영에 필요한 저장소만 열었을 때도 "지금 뭘 따라야 하는지"가 헷갈리지 않게 만들기 위해서였습니다.

단순히 문서를 복사한 것이 아니라, 각 저장소가 자기 문서만으로 자기 책임을 설명할 수 있게 만드는 과정이었습니다.

실제로는 문서 분리보다 review gate를 먼저 세웠습니다

그런데 operational source와 history source를 다시 나누는 과정 자체가, 또 누군가의 판단이었습니다.

구조를 바꾸는 동안에도 검수 구조가 먼저 있어야 했습니다.

블로그 초안에서 시작한 2-agent cross-validation을 결국 운영 문서와 구조 변경에도 그대로 적용하게 된 이유가 여기에 있습니다.

같은 모델을 같은 체크리스트로 두 번 돌리는 것을 교차검증이라고 부를 수는 없습니다. 가능하면 다른 surface를 쓰고, 최소한 다른 review path를 거쳐야 했습니다.

이 원칙이 없으면 구조 변경이 진행될수록 오히려 판단이 자기복제되기 쉽습니다.

결국 detached workspace migration은 폴더를 만드는 작업이 아니라, review gate를 가진 구조를 새로 세우는 작업이 됐습니다.

지금 돌아보면 핵심은 "분리"보다 "참조 방향"이었습니다

이번 작업을 끝내고 나서 보니, 정말 어려웠던 건 저장소 개수를 늘리는 일이 아니었습니다.

어느 저장소가 누구를 참조해야 하는지, 그리고 어떤 문서가 현재 운영 기준인지 고정하는 일이 더 어려웠습니다.

정리하면, 개인 도메인 A(ai-survival-log, ai-survival-log-site)와 회사 도메인 B(company-wiki, company-assistant-ops)는 데이터와 권한 측면에서 독립적입니다. 하지만 둘 다 공용 운영 원칙은 shared-agent-harness를 참조합니다.

즉, shared-agent-harness는 중심이지만 다른 도메인 저장소들의 domain contract를 덮어쓰지는 않습니다. 공용 운영 원칙만 공유하고, 실제 source-of-truth는 각 저장소가 자기 도메인 안에서 유지합니다.

이번 작업의 결과는 멀티 프로젝트 구조 자체가 아니라, 참조 방향이 고정된 운영 구조였습니다.

그리고 그 작업이 끝나고 나서야 다음 질문이 생겼습니다.

여러 저장소로 나뉜 이 구조는 결국 무엇을 닮은 모양인가. 같은 시스템 안에서 도메인을 나누고 운영 원칙을 공유하는 방식은, 소프트웨어 엔지니어링이 오래전부터 다뤄온 경계 문제와 어떻게 겹치는가.

다음 글은 이 구조를 Bounded Context의 시선으로 다시 읽습니다.