title: "에이전트 아키텍처 격리 구조 재설계 플랜" type: architecture-redesign layer: L2 date: 2026-02-26T10:00:00+09:00 author: arch-plan-pl status: completed reviewed_by: null reviewed_at: null approved_by: null approved_at: null task_id: cfa706fb-8820-4042-ae10-e9be1f00f3e3 tags: [architecture, agent-isolation, skill-hierarchy, db-security, refactoring]

에이전트 아키텍처 격리 구조 재설계 플랜

배경 및 문제 정의

핵심 원칙: Agent ↔ PL 개념 완전 분리 (CEO 지시 2026-02-26)

Agent (전문 에이전트) 정의

• Claude Code의 built-in 전문 에이전트 (.claude/agents/ 폴더 기반)
• 멀티폴더/크로스프로젝트 업무 담당
• 마케팅, 리서치, SEO, 콘텐츠 등 도메인 전문 역할
• business-builder 전체 컨텍스트 접근 가능
• 소환: Task tool의 subagent_type 파라미터 (예: subagent_type: "content-marketer")
• 예: content-marketer, seo-specialist, research-analyst, market-researcher

PL (Project Leader) 정의

• 특정 프로젝트 폴더 기반 독립 세션
• 단일 프로젝트 내 개발/실행 담당
• 해당 프로젝트 CLAUDE.md만 로드 (자비스 지침 없음)
• 2가지 유형:
  • 개발 PL: 코드 수정/배포 가능, 해당 프로젝트 DB 직접 접근 허용
  • 사용 PL: API/서비스만 활용, DB 접근 불가, 코드 수정 불가
• 소환: Task tool subagent_type: "general-purpose" + team_name + name

혼용 금지 규칙

예시 (content-orchestration):

├── projects/content-orchestration/  ← 개발 PL 전용 (코드 수정, DB 접근, 배포)
└── projects/content-creator/        ← 사용 PL 전용 (API 호출만, 코드 수정 불가)

현재 문제 3가지 (CEO 직접 지시 2026-02-26)

문제 1: CLAUDE.md 오염 — PL이 자비스 지침을 로드

• 자비스가 소환하는 모든 PL이 business-builder/CLAUDE.md (389줄, 자비스 운영 지침 전체)를 자동 로드
• PL이 자비스 역할로 혼동 가능 (예: "너는 자비스 총괄이사이다" 지시를 PL이 받음)
• 불필요한 컨텍스트 과부하 → 토큰 낭비, 지시 충돌 리스크

문제 2: DB 보안 — 개발자와 사용자 격리 없음

• 동일 AI가 칸반 시스템을 개발하면서 동시에 psql로 직접 DB 조작
• 실제 사고: 2026-02-19 Prisma+Drizzle ORM 충돌로 테이블 삭제
• 칸반 개발 PL과 칸반 사용 PL 간 권한 구분 없음

문제 3: 스킬 공유 불가 — 자비스 전용으로만 관리

• 현재 .claude/skills/ 에 45개 스킬이 전부 자비스 전용
• PL과 공유할 스킬 (writing-plans, executing-plans 등)과 자비스 전용 스킬 (scheduler-tick-rules, vp-operations 등) 구분 없음
• 프로젝트별 전용 스킬 체계 없음

현재 구조

business-builder/
├── CLAUDE.md                        ← 389줄, 자비스 전용인데 모든 PL도 로드
├── .claude/
│   └── skills/                      ← 45개 스킬 전부 여기, 분류 없음
│       ├── session-start.md
│       ├── vp-operations.md         ← 자비스 전용
│       ├── scheduler-tick-rules.md  ← 자비스 전용
│       ├── pl-development.md        ← PL 공통
│       ├── coding-rules.md          ← PL 공통
│       └── ... (40+ 파일)
├── projects/
│   ├── apppro-kr/CLAUDE.md          ← ✅ 있음
│   ├── kanban-dashboard/CLAUDE.md   ← ✅ 있음
│   ├── richbukae-store/             ← ❌ CLAUDE.md 없음
│   ├── content-pipeline/CLAUDE.md   ← ✅ 있음
│   └── ... (23개 프로젝트)
└── ~/.claude/skills/                ← 8개 스킬 (글로벌)
    ├── pl-git-rules.md
    ├── vp-operations.md             ← 중복!
    ├── research-process.md          ← 중복!
    └── ...

목표 구조 (CEO 제안 기반)

~/.claude/
├── CLAUDE.md                        ← 글로벌 규칙 (Node.js, git, CLI)
└── skills/
    ├── pl-git-rules.md              ← 모든 PL 공통
    ├── coding-rules.md              ← 모든 PL 공통
    ├── planning-rules.md            ← 모든 PL 공통
    └── ...

business-builder/
├── CLAUDE.md                        ← 자비스 전용 (250줄 → ~50줄 글로벌 + 자비스 별도)
├── .claude/
│   └── skills/
│       ├── jarvis-only/             ← 자비스 전용 스킬
│       │   ├── vp-operations.md
│       │   ├── scheduler-tick-rules.md
│       │   └── ...
│       ├── shared/                  ← 모든 PL 공유 (=글로벌 후보)
│       │   ├── writing-plan.md
│       │   ├── db-access-rules.md
│       │   └── ...
│       └── reference/               ← 참조 전용 (스키마, 카탈로그)
│           ├── db-schema.md
│           ├── available-agents.md
│           └── ...
└── projects/
    └── {project}/
        ├── CLAUDE.md                ← 프로젝트 전용 (기술스택, 경로, 규칙)
        └── .claude/skills/          ← 프로젝트 전용 스킬 (필요 시)

태스크 목록

Task 1: 스킬 45개 분류 (3계층 분류표 작성)

목표: 현재 .claude/skills/ 45개 파일을 글로벌 / 자비스 전용 / 프로젝트 전용으로 분류

분류 기준:

• 글로벌 (~/.claude/skills/): 모든 PL이 알아야 하는 공통 규칙 (git, 코딩, 문서 작성)
• 자비스 전용 (jarvis-only/): 자비스 오케스트레이터만 필요한 규칙 (스케줄러, VP 보고, 팀 관리)
• 공유 참조 (shared/): PL이 참조할 수 있지만 필수는 아닌 것 (DB 스키마, 에이전트 카탈로그)
• 프로젝트 전용: 특정 프로젝트에서만 필요한 것

분류표 (현재 45개 스킬):

실행 방법:

1. 분류표 확정 후 디렉토리 생성
2. 파일 이동 (git mv)
3. CLAUDE.md 내 스킬 참조 경로 업데이트

검증 방법:

• 모든 스킬 파일이 정확한 위치에 존재하는지 ls 확인
• CLAUDE.md 내 경로 참조가 깨지지 않는지 grep 검증

Task 2: business-builder/CLAUDE.md 리팩토링

목표: 389줄 자비스 전용 지침 → 글로벌 부분(~50줄)과 자비스 전용 부분 분리

현재 CLAUDE.md 구조 분석:

주의: jarvis-core.md 자동 로드 메커니즘 (수정 추가 2026-02-26):

• Claude Code는 .claude/skills/jarvis-only/ 서브폴더를 자동 로드하지 않음
• 자비스 세션 시작 시 session-start.md 스킬 업데이트 필요
• session-start.md에 "자비스 세션 시작 즉시 jarvis-core.md 스킬 호출" 절차 추가
• 이를 통해 자비스 전용 지침이 매 세션마다 확실히 로드됨

리팩토링 결과물:

2-A. business-builder/CLAUDE.md (신규, ~50줄)

글로벌 공통 규칙만 남김:

# Business Builder 프로젝트 공통 규칙

## 프로젝트 구조
business-builder/projects/{프로젝트명}/ 하위에 각 프로젝트 폴더.

## DB 보호 규칙
- app_user: DML 전용, neondb_owner: 마이그레이션 전용 (승인 후에만)
- drizzle-kit push 절대 금지
- 프로젝트별 DB 분리 원칙

## API 키 관리
- 루트 `.env` 파일에 보관, .gitignore 포함
- 프로젝트별 `.env`에는 해당 프로젝트 전용 키만

## Git 정책
- 지침/스킬 변경 시 즉시 commit + push
- push 전 `git pull --rebase origin main` 필수

## Obsidian 동기화
- 플랜: /Users/nbs22/ObsidianVault/projects/plans/
- 설계 문서: /Users/nbs22/ObsidianVault/projects/docs/
- 문서 저장 후 Obsidian cp 누락 금지

## 의사결정 권한
| 기술/구현 | PL 자율 |
| 전략/기획/QA | VP 결정 |
| 비용/비즈니스 | CEO 승인 |

## 금지 사항 (공통)
- Vercel CLI 단독 배포 금지 (GitHub repo 연결 필수)
- 샘플/더미 데이터 10개 초과 생성 금지
- .vercel.app 링크 외부 노출 금지

2-B. .claude/skills/jarvis-only/jarvis-core.md (신규)

자비스 전용 내용 전부 이관:

• 조직 구조, 4대 원칙, OKR 철학, 역할 정의
• 운영 규칙 0~6, 총괄이사 역할 경계, PL 프로세스
• 스킬 참조 체계, 자비스 전용 금지사항

실행 방법:

1. jarvis-only/jarvis-core.md 작성 (자비스 전용 내용 이관)
2. business-builder/CLAUDE.md 리팩토링 (글로벌 공통만 잔류)
3. 자비스 세션에서 jarvis-core.md 스킬을 참조하도록 세션 시작 절차 업데이트

검증 방법:

• 리팩토링 후 CLAUDE.md 줄 수 확인 (50줄 이하 목표)
• PL을 프로젝트 디렉토리에서 소환 → CLAUDE.md에 자비스 전용 지침이 없는지 확인
• 자비스 세션에서 jarvis-core.md 스킬 로드 확인

Task 3: CLAUDE.md 없는 프로젝트에 최소 CLAUDE.md 생성

목표: 23개 프로젝트 중 CLAUDE.md 없는 6개에 최소 CLAUDE.md 생성

현재 상태:

• ✅ CLAUDE.md 있음 (17개): ai-directory, ai-flower-bouquet, apppro-kr, auto-trading, bni-ppt-platform, content-orchestration, content-pipeline, crm-system, flower-message, jarvis-system, kakao-chatbot, kanban-dashboard, marketing-dashboard, nara-marketplace, obituary-notification-service, prompt-shop, rag-knowledge-base
• ❌ CLAUDE.md 없음 (6개): ai-architect-global, ai-architect-package, ai-prompt-architect, chatgpt-course, richbukae-store, youtube-pipeline

프로젝트 CLAUDE.md 표준 템플릿 — 개발용 (dev PL):

# {프로젝트명} — 개발 PL 전용

## 프로젝트 개요
{한 줄 설명}

## 기술 스택
- 프레임워크:
- 언어:
- DB:
- 배포:

## 프로젝트 경로
`/Users/nbs22/(Claude)/(claude).projects/business-builder/projects/{name}/`

## GitHub Repo
{repo URL}

## 빌드 & 실행
```bash
npm install
npm run dev
npm run build

환경 변수

.env 파일 참조

개발 PL 권한

• 코드 수정/배포 가능
• psql CLI 직접 접근 허용 (해당 프로젝트 DB만)
• DB 스키마 변경 시 VP 승인 필수
• 타 프로젝트 파일 수정 금지
• 작업 완료 후 반드시 commit + push

**프로젝트 CLAUDE.md 표준 템플릿 — 사용용 (use PL)**:

```markdown
# {프로젝트명} — 사용 PL 전용

## 프로젝트 개요
{한 줄 설명} — API/서비스 활용 전용

## 사용 가능한 API
- `{base_url}/api/{endpoint}` — {설명}

## 사용 PL 제한
- API 엔드포인트만 사용 가능
- psql/SQL 직접 실행 절대 금지
- DB URL/토큰 접근 불가
- 코드 수정 절대 금지
- 프로젝트 소스 코드 열람 금지

실행 방법:

1. 6개 프로젝트 각각의 기존 코드/구조 확인
2. 템플릿 기반으로 프로젝트별 CLAUDE.md 작성
3. 기존 17개 CLAUDE.md에 "PL 규칙" 섹션 누락 시 추가

검증 방법:

• for d in projects/*/; do test -f "$d/CLAUDE.md" && echo "OK $d" || echo "MISSING $d"; done
• 모든 23개 프로젝트에 CLAUDE.md 존재 확인

Task 4: DB 보안 정책 명문화 + 적용

목표: 칸반 개발 PL vs 칸반 사용 PL 간 DB 접근 권한 구분

현재 문제:

• 칸반 시스템을 개발하는 PL이 직접 psql로 DB 조작 가능
• 다른 프로젝트 PL도 동일한 DB 접근 가능
• 2026-02-19 사고: ORM 충돌로 테이블 삭제

보안 정책 3계층:

업데이트할 파일: .claude/skills/db-access-rules.md

추가할 섹션:

## 9. 역할별 DB 접근 권한

### 칸반 개발 PL (kanban-dev 역할)
- psql CLI 직접 접근 허용
- Drizzle ORM으로 스키마 변경 가능 (단, VP 승인 후)
- `neondb_owner` 사용 가능 (마이그레이션 시에만)
- 프로젝트 경로: `projects/kanban-dashboard/`

### 칸반 사용 PL (모든 다른 PL)
- API 엔드포인트만 사용:
  - `https://business-builder-kanban.vercel.app/api/tasks`
  - `https://business-builder-kanban.vercel.app/api/reports`
  - `https://business-builder-kanban.vercel.app/api/subtasks`
- psql/SQL 직접 실행 절대 금지
- DB URL/토큰 접근 불가

### 자비스 총괄이사
- DB 직접 접근 절대 금지 (기존 규칙 유지)
- task-mgr PL에게 DB 조회/변경 위임

프로젝트별 DB 접근 매핑:

실행 방법:

1. db-access-rules.md에 역할별 접근 권한 섹션 추가
2. 각 프로젝트 CLAUDE.md에 DB 접근 규칙 명시
3. PL 스폰 시 역할(kanban-dev vs 일반) 명시하도록 자비스 지침 업데이트

검증 방법:

• db-access-rules.md 내용에 3계층 권한 명시 확인
• 테스트: 일반 PL 소환 → psql 접근 시 CLAUDE.md에서 금지 안내 확인

Task 5: project-sessions 스킬 업데이트

목표: 프로젝트별 독립 Claude Code 세션 관리 절차 보완

현재 상태: project-sessions.md 존재하지만 실제 스크립트 존재 여부 미확인 + 격리 구조 미반영

보완 사항:

1. 세션 스폰 시 CLAUDE.md 로딩 범위 명시

   • 프로젝트 세션은 projects/{name}/ 디렉토리에서 시작
   • 해당 디렉토리의 CLAUDE.md만 로드 (business-builder/CLAUDE.md 로드 안 됨)
   • 글로벌 ~/.claude/CLAUDE.md + ~/.claude/skills/ 는 로드됨

2. 자비스 → 프로젝트 세션 통신 프로토콜 보완

   • 메시지 형식 표준화
   • 응답 타임아웃 설정
   • 에러 핸들링 (세션 크래시 시 재스폰)

3. 세션별 권한 매트릭스 추가

   | 세션 | DB 접근 | 타 프로젝트 수정 | git push |
   |------|---------|----------------|----------|
   | kanban-dev | psql 직접 | ❌ | ✅ |
   | apppro-claude | apppro DB만 | ❌ | ✅ |
   | richbukae-claude | 없음 | ❌ | ✅ |
   

실행 방법:

1. project-sessions.md 업데이트 (격리 구조 반영)
2. 스크립트 존재 확인 → 없으면 생성 목록 정리
3. 세션별 권한 매트릭스 추가

검증 방법:

• project-sessions.md에 격리 규칙 명시 확인
• 스크립트 파일 존재 확인 (scripts/spawn-project-claude.sh 등)

Task 6: ~/.claude/skills/ 글로벌 스킬 정리

목표: 현재 글로벌 스킬 8개 중 중복 제거 + Task 1 분류 기반으로 이동

현재 ~/.claude/skills/ 상태 (8개):

1. design-system-extraction.md
2. new-app-project.md
3. obsidian-vault.md ← business-builder/.claude/skills/와 중복
4. okr-queue-manager.md ← business-builder/.claude/skills/와 중복
5. pl-git-rules.md
6. research-process.md ← business-builder/.claude/skills/와 중복
7. secretary-task-management.md
8. vp-operations.md ← business-builder/.claude/skills/와 중복

처리 계획:

Task 1에서 글로벌로 분류된 스킬 이동:

• coding-rules.md → ~/.claude/skills/
• pl-development.md → ~/.claude/skills/
• planning-rules.md → ~/.claude/skills/
• writing-plan.md → ~/.claude/skills/
• db-access-rules.md → ~/.claude/skills/
• token-budget.md → ~/.claude/skills/
• kpi-design.md → ~/.claude/skills/
• openrouter-policy.md → ~/.claude/skills/
• brevo-email-policy.md → ~/.claude/skills/

실행 방법:

1. 중복 4개 삭제
2. Task 1 글로벌 분류 스킬 9개 복사 (business-builder → ~/.claude/skills/)
3. 복사 후 business-builder 원본은 유지 (자비스 참조용)

주의: ~/.claude/skills/는 git 관리 대상이 아님. 변경 시 별도 백업 필요.

검증 방법:

• ls ~/.claude/skills/ 로 최종 목록 확인
• 중복 파일 없는지 diff 확인

Task 7: 검증 + 문서화

목표: 신규 구조가 실제로 격리 동작하는지 테스트

테스트 시나리오:

1. PL 격리 테스트

   • richbukae-store 프로젝트 디렉토리에서 PL 소환
   • CLAUDE.md에 "너는 자비스 총괄이사이다" 문구가 없는지 확인
   • 자비스 전용 스킬 (vp-operations, scheduler-tick-rules)에 접근 안 되는지 확인
   • 글로벌 스킬 (coding-rules, pl-git-rules)은 접근 가능한지 확인

2. DB 보안 테스트

   • 일반 PL 소환 → psql 접근 시도 → CLAUDE.md 금지 규칙 확인
   • kanban-dev PL 소환 → psql 접근 허용 확인

3. 자비스 기능 유지 테스트

   • 자비스 세션에서 jarvis-core.md 스킬 로드 확인
   • VP 보고, 텔레그램, 스케줄러 틱 등 기존 기능 정상 동작 확인

문서화:

• 리팩토링 전후 비교표 (파일 수, 줄 수, 스킬 분류)
• 신규 구조 다이어그램
• PL 스폰 시 체크리스트 업데이트

실행 방법:

1. Task 1~6 완료 후 테스트 PL 소환
2. 각 시나리오 수행 + 결과 기록
3. 비교 문서 작성

검증 방법:

• 3개 테스트 시나리오 모두 통과
• 기존 자비스 기능에 regression 없음

실행 순서 및 의존성 (수정: 2026-02-26, arch-execute-pl)

Task 1 (스킬 분류표 + 디렉토리 이동)
  ↓
[글로벌 로드 테스트] — ~/.claude/skills/ 자동 로드 검증
  ↓
Task 2 (CLAUDE.md 리팩토링 + jarvis-core.md 생성)  ←── Task 1 분류 기반
  ↓
Task 4 (DB 보안 정책 명문화)  ←── Task 2 리팩토링 후
  ↓
Task 6 (글로벌 스킬 정리)    ←── Task 1 분류 + 로드 테스트 결과 기반
  ↓
Task 3 (프로젝트 CLAUDE.md)  ←── Task 2 글로벌 형식 확정 후
  ↓
Task 5 (project-sessions)    ←── Task 3, 4 완료 후
  ↓
Task 7 (검증 + 문서화)       ←── 전체 완료 후

순서 변경 이유: ~/.claude/skills/ 자동 로드 검증 전에 스킬을 글로벌로 이동(T6)하면 역효과 가능. T1에서 분류 후 로드 테스트 → T2+T4 우선 실행 → 로드 검증 완료 후 T6 진행.

리스크 및 대응

리스크 1: 스킬 경로 변경으로 기존 참조 깨짐

영향: CLAUDE.md, 자비스 세션 시작 스크립트, VP 스크립트 등에서 스킬 경로를 하드코딩한 곳이 있을 수 있음.

대응:

• 이동 전 모든 파일에서 .claude/skills/ 경로 grep
• 이동 후 참조 경로 일괄 업데이트
• business-builder의 .claude/skills/ 원본은 삭제하지 않고 symlink 또는 redirect 파일 배치 가능

리스크 2: Claude Code가 ~/.claude/skills/ 를 자동 로드하지 않을 수 있음

영향: 글로벌 스킬로 이동했는데 PL이 참조할 수 없으면 역효과.

대응:

• Claude Code의 스킬 로딩 메커니즘 먼저 테스트 (Task 7에서 확인)
• 로드 안 되면 대안: business-builder 내에 shared/ 디렉토리로 분류하되 물리적으로는 이동하지 않음
• 최악의 경우 심링크로 양쪽에서 접근 가능하게

리스크 3: CLAUDE.md 리팩토링 중 자비스 세션 기능 장애

영향: CLAUDE.md를 변경하는 동안 자비스가 정상 동작하지 않을 수 있음.

대응:

• 기존 CLAUDE.md를 CLAUDE.md.backup 으로 백업 후 작업
• 단계적 리팩토링: 먼저 jarvis-core.md 작성 → 확인 → 그 다음 CLAUDE.md 축소
• git에서 언제든 rollback 가능

예상 규모

실행 결과 (2026-02-26)

Phase 1 (T1, T2, T4) — arch-execute-pl 완료

• T1: 스킬 45개 분류 완료 (jarvis-only/ 18개, shared/ 17개, root PL-common 10개)
• T2: CLAUDE.md 389줄 → 94줄 리팩토링 + jarvis-core.md 생성
• T4: db-access-rules.md 역할별 접근 권한 섹션 추가

Phase 2 (T6, T3, T5, T7) — arch-execute-pl2 완료

• T6: ~/.claude/skills/ 중복 4개 삭제 + 글로벌 스킬 9개 복사 → 13개 최종
• T3: CLAUDE.md 없는 6개 프로젝트에 최소 CLAUDE.md 생성 → 23/23 완료
• T5: project-sessions.md 격리 구조 반영 (PL 유형, 권한 매트릭스, 로딩 범위)
• T7: 전체 검증 통과

검증 결과

신규 구조 다이어그램

~/.claude/
├── CLAUDE.md                           (글로벌 — Node.js, git, CLI)
└── skills/ (13 files)                  (모든 PL 자동 로드)
    ├── coding-rules.md
    ├── pl-git-rules.md
    ├── pl-development.md
    ├── planning-rules.md
    ├── writing-plan.md
    ├── db-access-rules.md
    ├── token-budget.md
    ├── kpi-design.md
    ├── openrouter-policy.md
    ├── brevo-email-policy.md
    ├── design-system-extraction.md
    ├── new-app-project.md
    └── secretary-task-management.md

business-builder/
├── CLAUDE.md (94줄, 글로벌 공통)
├── .claude/skills/
│   ├── (10 PL-common files)            (business-builder PL 자동 로드)
│   ├── jarvis-only/ (18 files)         (자비스 Skill tool로만 접근)
│   │   ├── jarvis-core.md
│   │   ├── vp-operations.md
│   │   ├── scheduler-tick-rules.md
│   │   └── ...
│   ├── shared/ (17 files)              (참조용 — 에이전트/스키마/오피스)
│   └── external/ (15 files)            (외부 스킬)
└── projects/ (23개, 모두 CLAUDE.md 있음)
    ├── richbukae-store/CLAUDE.md       (개발 PL 전용)
    ├── kanban-dashboard/CLAUDE.md      (개발 PL 전용)
    └── ...

리뷰 로그

[완료]

• 전체 7개 태스크 실행 완료 (Phase 1: T1,T2,T4 + Phase 2: T6,T3,T5,T7)