# Personal AI Company 셋업 ④: Path B — 에이전트 간 파일 공유의 해법

Researcher가 조사를 마치고 "저장 완료"를 보고했다. Creator가 해당 파일을 읽으려 했는데 파일이 없다. 에이전트 로그에는 Write 도구 호출이 성공으로 기록되어 있다. 이 시리즈 4편에서는 이 현상의 원인과 해법, 절대경로 규칙의 필요성을 실제 프로젝트 구조를 기반으로 설명한다.

---

문제 인식: 에이전트는 왜 서로의 파일을 못 찾는가

per-agent sandbox의 구조

Paperclip의 각 에이전트는 독립된 실행 환경(sandbox)에서 작동한다. 에이전트가 실행될 때마다 격리된 git worktree 또는 operator branch가 할당되며, 상대경로(./workspace/)는 이 격리 디렉토리를 기준으로 resolve된다.

에이전트 A (Researcher) CWD: /paperclip/workspaces/run-20260518-001/
에이전트 B (Creator)    CWD: /paperclip/workspaces/run-20260518-002/

A에서 ./workspace/research/output.md
  = /paperclip/workspaces/run-20260518-001/workspace/research/output.md

B에서 ./workspace/research/output.md
  = /paperclip/workspaces/run-20260518-002/workspace/research/output.md

같은 상대경로가 물리적으로 서로 다른 파일을 가리킨다. Researcher가 상대경로로 저장했다면, Creator는 그 파일을 읽을 수 없다.

상대경로가 실패하는 두 가지 경우

에이전트의 Write 도구 호출이 성공으로 기록되어도 다른 에이전트가 파일을 찾지 못하는 경우는 두 가지다.

• 에이전트가 상대경로를 사용해 자신의 격리 sandbox에 저장했다.
• 격리 sandbox는 heartbeat 간 상태 유지를 보장하지 않아, 다음 실행에서 파일이 사라졌다.

두 경우 모두 공유 경로 미사용이 근본 원인이다.

---

Path B: 공유 워크스페이스 개념

host bind-mount란 무엇인가

/app/workspace/는 호스트 파일시스템의 특정 디렉토리를 모든 에이전트 컨테이너에 동일하게 마운트한 공유 경로다. 아래는 docker-compose 기반 설정 예시다.

# docker-compose.yml
services:
  paperclip:
    volumes:
      - /host/data/workspace:/app/workspace

컨테이너 내부에서 /app/workspace/를 읽거나 쓰면, 그 변경이 호스트 파일시스템(/host/data/workspace/)에 그대로 반영된다. 어떤 컨테이너에서 쓰든 같은 물리 위치에 기록된다.

/app/workspace/가 공유 채널이 되는 이유

모든 에이전트는 동일한 /app/workspace/ 마운트 포인트를 가진다. Researcher가 /app/workspace/blog-project/research/output.md에 저장하면, Creator는 같은 절대경로로 그 파일을 읽을 수 있다.

[Researcher sandbox]
/app/workspace/blog/research/output.md
  = /host/data/workspace/blog/research/output.md  ← 동일 물리 경로

[Creator sandbox]
/app/workspace/blog/research/output.md
  = /host/data/workspace/blog/research/output.md  ← 동일 물리 경로

에이전트가 어떤 격리 sandbox에서 실행되더라도 /app/workspace/는 항상 같은 물리 위치를 가리킨다.

Path A(sandbox) vs Path B(공유) 비교

구분	Path A — per-agent sandbox	Path B — 공유 워크스페이스
경로 형식	상대경로 (./workspace/)	절대경로 (/app/workspace/)
물리 위치	에이전트마다 다름	모든 에이전트 공유
에이전트 간 파일 공유	불가	가능
Heartbeat 간 영속성	보장 안 됨	보장됨
용도	임시 스크래치	공식 산출물 저장

---

절대경로 규칙: 5개 에이전트의 공통 약속

5개 에이전트(CEO, Researcher, Creator, Reviewer, Executor)는 각각의 시스템 프롬프트에 동일한 절대경로 규칙 섹션을 가진다. 실제 시스템 프롬프트에서 발췌한 CEO의 규칙은 다음과 같다.

## ⚠️ 절대경로 규칙 (최우선)

모든 파일 참조는 호스트와 공유되는 절대경로를 사용한다.
본인의 격리 workspace(상대경로 ./workspace/)는 임시 스크래치 용도로만 쓴다.

| 종류              | 절대경로                                     |
|-------------------|----------------------------------------------|
| 스킬 파일         | /app/skills/{name}.md                        |
| Researcher 산출물 | /app/workspace/{project-name}/research/      |
| Creator 산출물    | /app/workspace/{project-name}/drafts/        |
| Reviewer 산출물   | /app/workspace/{project-name}/reviews/       |
| Executor 최종본   | /app/workspace/{project-name}/final/         |

CEO가 정의하는 {project-name}

CEO는 새 프로젝트 시작 시 {project-name}을 결정하고 위임 메시지에 명시한다. 나머지 에이전트는 CEO가 지정한 프로젝트명을 임의로 변경하지 않는다. 이 규칙 하나가 파이프라인 전체의 경로 일관성을 보장한다.

역할별 읽기/쓰기 경로 매핑

CEO:        읽기 — 모든 하위 디렉토리
Researcher: 쓰기 — /app/workspace/{project}/research/
            읽기 — /app/skills/
Creator:    쓰기 — /app/workspace/{project}/drafts/
            읽기 — /app/workspace/{project}/research/, /app/skills/
Reviewer:   쓰기 — /app/workspace/{project}/reviews/
            읽기 — research/, drafts/, /app/skills/
Executor:   쓰기 — /app/workspace/{project}/final/
            읽기 — drafts/, reviews/

---

실제 디렉토리 구조

research/ → drafts/ → reviews/ → final/ 4단계

디렉토리 구조는 파이프라인 단계와 1:1로 대응한다.

/app/workspace/{project-name}/
├── research/    # Researcher 산출물 → Creator, Reviewer가 읽음
├── drafts/      # Creator 산출물  → Reviewer, Executor가 읽음
├── reviews/     # Reviewer 산출물 → Executor가 읽음
└── final/       # Executor 최종본 → Board 승인 후 외부 발행

현 블로그 프로젝트 구조 예시

이 시리즈를 작성하면서 실제로 생성된 구조다.

/app/workspace/blog-personal-ai-company-setup/
│
├── research/
│   ├── 01-why-ai-company.md
│   ├── 02-paperclip-setup.md
│   ├── 03-agent-design.md
│   └── 04-shared-workspace.md
│
├── drafts/
│   ├── 01-why-ai-company.md
│   ├── 02-paperclip-setup.md
│   └── 03-agent-design.md
│
├── reviews/
│   ├── 01-why-ai-company.review.md
│   ├── 02-paperclip-setup.review.md
│   └── 03-agent-design.review.md
│
└── final/
    ├── 01-why-ai-company.md
    ├── 02-paperclip-setup.md
    └── 03-agent-design.md

CEO의 초기화 책임

CEO는 새 프로젝트를 시작할 때 Researcher에게 위임하기 전에 디렉토리 구조를 먼저 생성해야 한다. 이 단계를 빠뜨리면 Researcher의 첫 번째 저장에서 FileNotFoundError가 발생한다.

# CEO가 프로젝트 시작 시 실행
mkdir -p /app/workspace/blog-personal-ai-company-setup/{research,drafts,reviews,final}

---

트러블슈팅: 경로 관련 자주 만나는 오류

오류 1: 파일 없음 (상대경로 저장 불일치)

증상

FileNotFoundError: /app/workspace/blog-project/research/output.md not found

Creator가 Researcher 산출물을 찾지 못한다. Researcher가 완료 보고를 했는데도 파일이 없다.

원인
Researcher가 ./workspace/research/output.md(상대경로)에 저장했다. Creator는 위임 메시지에 적힌 절대경로 /app/workspace/blog-project/research/output.md를 읽으려 하지만 해당 위치에 파일이 없다.

해결책
Researcher 시스템 프롬프트의 ## ⚠️ 절대경로 규칙 섹션을 점검한다. 파일 존재 여부는 아래 명령으로 직접 확인한다.

ls /app/workspace/blog-project/research/

---

오류 2: 프로젝트 디렉토리 없음 (CEO 초기화 누락)

증상

FileNotFoundError: [Errno 2] No such file or directory:
'/app/workspace/new-project/research/output.md'

Researcher가 파일 저장을 시도하지만 디렉토리 자체가 없다.

원인
CEO가 새 프로젝트 시작 시 /app/workspace/{project-name}/ 하위 디렉토리를 생성하지 않았다.

해결책
CEO가 Researcher에게 위임하기 전에 프로젝트 디렉토리 구조를 먼저 생성한다.

mkdir -p /app/workspace/{project-name}/{research,drafts,reviews,final}

---

오류 3: sandbox 혼동 (성공 보고 후 파일 없음)

증상
Researcher가 "저장 완료"를 보고했다. 에이전트 로그에는 Write 도구 호출이 성공으로 기록되어 있다. 하지만 /app/workspace/project/research/를 확인하면 파일이 없다.

원인
에이전트가 상대경로(./workspace/research/output.md)로 파일을 저장했다. Write 도구 자체는 성공했지만 에이전트의 격리 sandbox에 저장됐다. 격리 sandbox는 공유 경로가 아니므로 다른 에이전트에서 접근할 수 없다.

해결책
에이전트 heartbeat 로그에서 실제 Write 도구 호출 경로를 확인한다. 경로가 /app/workspace/로 시작하지 않으면 절대경로 규칙 위반이다. Paperclip UI → 해당 에이전트 → Instructions 탭에서 절대경로 규칙 섹션을 점검하고 재저장한다.

---

오류 4: 프로젝트명 불일치

증상
/app/workspace/blog-personal-ai-company/research/에 파일이 있는데 Creator가 /app/workspace/blog-personal-ai-company-setup/research/를 찾는다.

원인
CEO 위임 메시지에 기재한 {project-name}과 에이전트가 실제로 사용한 디렉토리명이 다르다. 오타, 버전 불일치, 또는 에이전트가 임의로 프로젝트명을 변경했을 가능성이 있다.

해결책
CEO가 위임 메시지에서 {project-name}을 명확히 명시한다. 에이전트는 CEO가 지정한 프로젝트명을 임의로 변경하지 않는다.

# 실제 디렉토리 확인
ls /app/workspace/

---

오류 5: 스킬 파일 읽기 실패

증상
에이전트가 스킬 파일 없이 기본 행동으로 작업을 진행한다. 블로그 문체 규칙이나 코드 스타일 가이드가 무시된다.

원인
스킬 파일 경로가 상대경로이거나 오타가 있다.

해결책
스킬 파일 참조 시 반드시 절대경로를 사용한다.

올바름: /app/skills/blog-writing.md
잘못됨: ./skills/blog-writing.md
잘못됨: skills/blog-writing.md
잘못됨: ../skills/blog-writing.md

---

마치며: 절대경로 하나로 팀 협업이 성립한다

절대경로 규칙 하나가 5개 에이전트의 협업을 성립시킨다. 어느 한 에이전트가 이 규칙을 어기면 파이프라인 전체가 깨진다. 시스템 프롬프트에 ## ⚠️ 절대경로 규칙 (최우선)을 명시하고 모든 에이전트에 일관되게 적용하면, Researcher의 산출물이 Creator에게, Creator의 초안이 Reviewer에게, Reviewer의 검증본이 Executor에게 정확하게 전달된다.

다음 편에서는 이 파이프라인의 품질 게이트인 Reviewer 에이전트의 검수 기준과 실제 리뷰 산출물 구조를 살펴본다.