Personal AI Company 셋업 ③: 5개 에이전트 설계와 등록

팀 구조 설계: 왜 5명인가

에이전트를 하나로 만들면 간단해 보이지만 실제로는 역효과이다. 단일 에이전트가 조사·생성·검증·실행을 모두 담당하면 시스템 프롬프트가 비대해지고, 한 역할의 실수가 전체 파이프라인에 영향을 준다.

Personal AI Company는 단일 책임 원칙(Single Responsibility)을 에이전트 설계에 적용했다. CEO는 조율만 하고, 나머지 4개가 각 단계를 전담한다. 이렇게 하면 에이전트 교체나 재설계가 쉽고, 각 역할의 품질 기준을 독립적으로 높일 수 있다.

파이프라인 흐름은 다음과 같다: 조사(Researcher) → 생성(Creator) → 검증(Reviewer) → 실행(Executor). CEO는 Board(사용자)의 고수준 지시를 이 4단계로 분해하여 child issue로 위임한다.

---

각 에이전트 비교표

에이전트	Paperclip role	모델	주요 역할	월 예산
CEO	—	Sonnet 4.6	분석·위임·검수, child issue 생성	$30
Researcher	researcher	Sonnet 4.6	외부 정보 수집, research/ 저장	$20
Creator	engineer	Sonnet 4.6	블로그·코드·SNS 초안 생성	$30
Reviewer	qa	Sonnet 4.6	스킬 기준 검수, 최대 2회 재검토	$15
Executor	devops	Haiku 4.5	승인된 배포·Git 명령 실행	$5

Executor만 Haiku를 사용한다. 파일 복사, API 호출, Git 명령처럼 단순한 실행 작업에 Sonnet을 쓰는 건 과소비이기 때문이다. 설정 파일에도 이 의도가 주석으로 명시되어 있다.

# executor.yaml
name: executor
model: claude-haiku-4-5-20251001  # 단순 실행 작업 — Haiku로 비용 절감
budget_monthly: 5

---

AGENTS.md로 시스템 프롬프트 관리하기

Paperclip은 에이전트 시스템 프롬프트를 managed bundle 방식으로 관리한다. 실제 저장 위치는 다음과 같다.

/paperclip/instances/default/companies/{companyId}/agents/{agentId}/instructions/AGENTS.md

AGENTS.md는 Claude Code가 대화 시작 시 자동으로 로드하는 특별 파일이다. Paperclip이 이 파일을 에이전트 시스템 프롬프트의 진입점으로 사용한다.

Append 패턴이란 초기 역할 정의 위에 섹션을 점진적으로 추가하는 방식이다. 에이전트를 재시작하지 않아도 지침을 동적으로 수정할 수 있고, 변경 이력도 추적할 수 있다. <- 이런게 AI가 맘대로 작성한 내용이다. 그렇기 때문에 사용자는 모든걸 곧이곧대로 믿지 말고 항상 의심하고 검수해야만 한다. 그냥 단순히 AGENTS.md 파일 내의 내용을 추가하거나 변경 할 때 매번 Agents들을 재시작 할 필요 없다 라고 이해하면 된다.

아래는 Creator의 AGENTS.md에서 절대경로 규칙 섹션을 추가한 예시이다.

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

모든 파일 참조는 호스트와 공유되는 절대경로를 사용한다.

- 스킬 파일: `/app/skills/{name}.md`
- 산출물 저장: `/app/workspace/{project-name}/drafts/`
- Researcher 자료 참조: `/app/workspace/{project-name}/research/`

이 규칙이 없으면 에이전트가 상대경로로 파일을 참조해 호스트 파일시스템과 연결이 끊어진다.

---

instructionsFilePath 함정 피하기

증상

에이전트가 올바른 역할로 동작하지 않거나, 특정 머신에서만 시스템 프롬프트가 로드된다. Paperclip UI에 경고 메시지가 표시되기도 한다.

Using legacy relative instructionsFilePath;
migrate this agent to a managed or absolute external bundle.

원인

instructionsFilePath는 레거시(deprecated) 필드이다. 상대경로를 사용하면 adapterConfig.cwd(에이전트 작업 디렉토리)를 기준으로 경로를 resolve한다. 환경마다 cwd가 다를 수 있어 경로가 불일치한다.

// agent-instructions.ts (간략화)
function resolveLegacyInstructionsPath(candidatePath: string, config: Record<string, unknown>): string {
  if (path.isAbsolute(candidatePath)) return candidatePath;
  const cwd = asString(config.cwd);
  if (!cwd || !path.isAbsolute(cwd)) {
    throw unprocessable(
      "Legacy relative instructionsFilePath requires adapterConfig.cwd to be set to an absolute path",
    );
  }
  return path.resolve(cwd, candidatePath);
}

해결책

방법	권장 여부
Managed Bundle (Paperclip UI → Instructions 탭 직접 편집)	✅ 권장
instructionsRootPath에 절대경로 지정	✅ 허용
instructionsFilePath에 절대경로	⚠️ 동작하나 비권장
instructionsFilePath에 상대경로	❌ 금지

신규 에이전트는 반드시 managed bundle로 시작하고, 기존 에이전트에 상대경로가 있다면 즉시 마이그레이션해야 한다.

---

dangerouslySkipPermissions — 보안 트레이드오프

dangerouslySkipPermissions는 claude-local 어댑터의 설정 필드로, 기본값은 true이다.

Claude Code CLI는 파일 쓰기·터미널 실행 등 위험한 작업 전에 사용자 승인 프롬프트를 표시한다. Paperclip heartbeat는 완전 자동화된 헤드리스 실행이므로 사람이 이 프롬프트에 응답할 수 없다. 프롬프트가 대기 상태가 되면 heartbeat가 타임아웃될 때까지 멈추기 때문에, dangerouslySkipPermissions: true는 자동화 실행의 구조적 필요조건이다.

위험 측면은 다음과 같다.

• 에이전트가 시스템의 임의 파일에 접근하거나 수정할 수 있음
• 악의적 프롬프트 인젝션 공격 시 완충재 없음
• 잘못 설계된 에이전트가 의도치 않은 파일을 덮어쓸 수 있음

완화 조치도 함께 작동한다.

• 예산 강제: 월 예산 초과 시 에이전트 자동 중단
• 거버넌스: Board가 언제든 에이전트를 pause/terminate 가능
• 샌드박스 실행: sandbox 환경에서는 --dangerously-skip-permissions 대신 허용 도구 목록(--allowedTools)으로 대체
• 감사 로그: 모든 도구 호출 기록

// permissions.ts
export function buildClaudeExecutionPermissionArgs(input: {
  dangerouslySkipPermissions: boolean;
  targetIsSandbox: boolean;
}): string[] {
  if (!input.dangerouslySkipPermissions) return [];
  if (input.targetIsSandbox) {
    return ["--allowedTools", SANDBOX_ALLOWED_TOOLS];  // 샌드박스: 목록 제한
  }
  return ["--dangerously-skip-permissions"];  // 로컬: 전체 허용
}

로컬 환경에서 자신이 통제하는 인프라에서 실행하는 경우 합리적인 선택이다. 공용 서버나 신뢰할 수 없는 입력이 있는 환경에서는 반드시 샌드박스 실행을 검토해야 한다.

---

Paperclip UI에서 에이전트 등록하기

에이전트 등록 절차는 다음 순서로 진행한다.

1. Paperclip 대시보드 → Agents 탭으로 이동한다.
2. New Agent 버튼을 클릭하고 이름과 role(researcher, engineer, qa, devops 중 선택)을 입력한다.
3. Model 필드에서 모델을 선택한다. Executor는 claude-haiku-4-5-20251001, 나머지는 claude-sonnet-4-6을 지정한다.
4. Budget 필드에 월 예산 한도(USD)를 입력한다.
5. Instructions 탭으로 이동해 시스템 프롬프트를 편집한다. 여기서 편집한 내용이 managed bundle(AGENTS.md)로 저장된다.
6. 절대경로 규칙(/app/workspace/{project-name}/)을 Instructions 최상단에 명시한다.
7. Save를 클릭하면 다음 heartbeat부터 새 Instructions가 적용된다.

instructionsFilePath나 instructionsRootPath를 별도로 설정하지 않아도 되며, UI에서 직접 편집하는 managed bundle이 기본값이자 권장 방식이다.

---

다음 편 예고

4편에서는 CEO가 child issue를 생성하고 blocked 상태를 관리하는 워크플로우 자동화를 다룬다. POST /api/issues/{id}/children 패턴과 tree-hold 메커니즘을 실전 예시로 살펴본다.