docs(개발팀): Claude Code 콘솔(CLI) 병렬 실행 기술 검토 보고서 (PD님 지시)

CLI 병렬 세션 3가지 방법(동일 디렉토리/워크트리/일회성 질의), git 충돌 관리,
대화 로그 무결성 방안, PD님 실행 가이드 포함.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

공유/대화로그/조직운영/2026-04-16.md

@@ -80,3 +80,10 @@
 - **이유**: 대화 컨텍스트가 git에 저장되지 않는 문제 해결 + 조직 노하우 축적
 - **산출물**: SKILL.md P24, 본 파일이 첫 대화로그
 - **상태**: 완료
+
+<!-- #PD지시 #개발팀 #완료 #콘솔병렬실행 -->
+## [PM] Claude Code 콘솔(CLI) 병렬 실행 기술 검토
+- **요지**: PD님이 윈도우 앱에서 에이전트 작업 중 여러 CLI 터미널을 열어 병렬 업무 지시가 가능한지 기술 검토. 결론: **가능**. 3가지 방법 제시 — (1) 같은 디렉토리에서 복수 CLI (간단하지만 git 충돌 위험), (2) `--worktree` 플래그로 격리 (권장), (3) `-p` 일회성 질의 (가장 빠른 방법). 윈도우 앱과 CLI는 완전히 독립 세션이며 동시 실행 가능. 2026-04-14 데스크톱 앱 리디자인으로 앱 내에서도 병렬 세션 네이티브 지원 추가됨.
+- **이유**: 윈도우 앱에서 Agent 작업 중 PD님이 응답 대기해야 하는 문제 해소
+- **산출물**: `공유/소통/개발팀→PM/2026-04-16_콘솔병렬실행_기술검토_개발팀.md`
+- **상태**: 완료

공유/소통/개발팀→PM/2026-04-16_콘솔병렬실행_기술검토_개발팀.md

@@ -0,0 +1,287 @@
+# Claude Code 콘솔(CLI) 병렬 실행 기술 검토
+
+> **작성**: 개발팀 (PD님 지시)
+> **일자**: 2026-04-16
+> **목적**: PD님이 윈도우 앱에서 에이전트 작업 중 여러 콘솔(CLI)을 열어 병렬 업무 지시가 가능한지 기술 검토
+> **현재 환경**: Claude Code v2.1.110 / Windows 10 Pro / NerdNavisAi 레포 (단일 main 브랜치)
+
+---
+
+## 1. 결론 요약
+
+**가능합니다.** Claude Code CLI는 여러 터미널에서 동시 실행을 공식 지원합니다. 단, **같은 디렉토리에서 동시에 파일을 수정하면 git 충돌이 발생**하므로, `--worktree` 플래그를 사용한 작업 영역 격리가 권장됩니다. 아래에 3가지 방법을 난이도순으로 제시합니다.
+
+---
+
+## 2. 3가지 실행 방법 (난이도순)
+
+### 2-1. 방법 A: 같은 디렉토리에서 CLI 여러 개 (가장 간단, 주의 필요)
+
+**절차**:
+1. Windows Terminal 또는 PowerShell을 여러 탭/창으로 열기
+2. 각 터미널에서 동일 경로로 이동:
+   ```
+   cd "D:\NerdNavis\NerdNavisAi"
+   ```
+3. 각 터미널에서 독립 claude 세션 시작:
+   ```
+   claude
+   ```
+4. 각 터미널에 서로 다른 업무 지시
+
+**특성**:
+- 각 CLI는 **독립 세션** (세션 ID가 별도)
+- 각 세션이 별도의 대화 컨텍스트를 유지
+- `.claude/settings.json`, `CLAUDE.md` 등 설정은 공유 (동일 디렉토리)
+- MCP 서버도 각 프로세스가 독립 연결
+
+**위험 요소**:
+- 두 세션이 **같은 파일을 동시 수정**하면 나중에 저장하는 쪽이 먼저 저장한 내용을 덮어씀
+- 한쪽이 commit하고 다른 쪽도 commit하면 **git 이력이 꼬일 수 있음**
+- 같은 main 브랜치의 working tree를 공유하므로 `git status`가 양쪽 변경을 모두 보여줌
+
+**적합한 경우**:
+- **서로 다른 파일/영역**만 수정하는 작업 (예: 한쪽은 기획 문서, 다른 쪽은 코드)
+- 읽기 전용 작업 (분석, 검토, 질의응답)
+- 한 세션만 파일 수정, 나머지는 질의/분석용
+
+### 2-2. 방법 B: `--worktree` 플래그로 격리 (권장)
+
+**절차**:
+1. 터미널 1 (메인 작업):
+   ```
+   cd "D:\NerdNavis\NerdNavisAi"
+   claude
+   ```
+2. 터미널 2 (병렬 작업 - 워크트리 격리):
+   ```
+   cd "D:\NerdNavis\NerdNavisAi"
+   claude --worktree task-name
+   ```
+   이렇게 하면 `.claude/worktrees/task-name/` 디렉토리에 별도 작업 복사본이 생성되고, 별도 브랜치(`worktree-task-name`)에서 작업됩니다.
+
+3. 터미널 3 (또 다른 병렬 작업):
+   ```
+   cd "D:\NerdNavis\NerdNavisAi"
+   claude --worktree another-task
+   ```
+
+**특성**:
+- 각 워크트리는 **독립적인 파일 시스템 복사본** + **독립 브랜치**
+- 같은 파일을 수정해도 **절대 충돌하지 않음** (서로 다른 디렉토리)
+- 작업 완료 후 main에 merge하여 통합
+- 디스크 공간이 허용하는 만큼 무제한 생성 가능
+
+**워크트리 작업 후 merge 흐름**:
+```
+# 워크트리에서 작업 완료 후
+git add -A
+git commit -m "작업 완료 메시지"
+
+# 메인 디렉토리로 돌아가서
+cd "D:\NerdNavis\NerdNavisAi"
+git merge worktree-task-name
+git branch -d worktree-task-name
+git worktree remove .claude/worktrees/task-name
+```
+
+**적합한 경우**:
+- 동시에 **같은 파일을 수정**할 가능성이 있는 작업
+- 독립적인 기능 개발/문서 작업을 병렬로 진행
+- 작업 결과를 검토 후 선택적으로 merge하고 싶을 때
+
+### 2-3. 방법 C: `--print` 모드로 일회성 명령 (가장 빠른 질의용)
+
+**절차**:
+```
+claude -p "이 프로젝트의 디렉토리 구조를 설명해줘"
+```
+또는 파이프 사용:
+```
+cat "D:\NerdNavis\NerdNavisAi\CLAUDE.md" | claude -p "이 파일을 요약해줘"
+```
+
+**특성**:
+- 대화형이 아닌 **일회성 실행** (결과 출력 후 즉시 종료)
+- 인터랙티브 세션이 아니므로 후속 질문 불가
+- 대기 중인 윈도우 앱과 완전히 독립
+- 가장 빠르고 가벼운 방법
+
+**적합한 경우**:
+- 간단한 질문/분석 (코드 리뷰, 파일 요약 등)
+- 윈도우 앱이 긴 작업 중일 때 빠른 질의
+- 스크립트에서 자동화된 호출
+
+---
+
+## 3. 세션 관리 주요 CLI 플래그
+
+| 플래그 | 용도 | 예시 |
+|--------|------|------|
+| `claude` | 새 대화 시작 | `claude` |
+| `claude -c` | 가장 최근 대화 이어가기 | `claude -c` |
+| `claude -r` | 특정 세션 선택하여 이어가기 | `claude -r "session-name"` |
+| `claude -n "이름"` | 세션에 이름 부여 | `claude -n "기획검토"` |
+| `claude -w "이름"` | 워크트리 격리 세션 | `claude -w "feature-x"` |
+| `claude -p "질문"` | 일회성 질의 (비대화형) | `claude -p "요약해줘"` |
+| `claude --model opus` | 모델 지정 | `claude --model opus` |
+
+---
+
+## 4. 병렬 작업 시 git 충돌 관리 분석
+
+### 4-1. 시나리오별 위험도
+
+| 시나리오 | 방법 A (같은 디렉토리) | 방법 B (워크트리) |
+|----------|----------------------|-----------------|
+| 서로 다른 파일 수정 | 안전 (단, commit 순서 주의) | 완전 안전 |
+| 같은 파일 동시 수정 | **위험** (덮어쓰기) | 안전 (merge 시 충돌 해결) |
+| 동시 commit | 가능하나 혼란 | 각자 독립 commit |
+| 동시 push | 두 번째 push가 reject | 각자 브랜치에 push 가능 |
+
+### 4-2. 방법 A 사용 시 충돌 방지 규칙
+
+1. **작업 영역 분리 원칙**: 세션별로 수정 대상 디렉토리/파일을 명확히 구분
+   - 세션 1: `공유/소통/` 하위만
+   - 세션 2: `프로젝트/코어프레임워크/` 하위만
+2. **커밋 순서 보장**: 한 세션이 커밋 완료 후 다른 세션이 커밋
+3. **지시 시 명시**: "이 세션에서는 XX 파일만 수정하라" 식으로 범위 한정
+
+### 4-3. 방법 B 사용 시 merge 전략
+
+1. 워크트리에서 작업 완료 + commit
+2. main 브랜치로 이동
+3. `git merge worktree-branch-name`
+4. 충돌 발생 시 수동 해결 (충돌 가능성 낮음 - 작업 영역이 대개 다르므로)
+5. 워크트리 정리: `git worktree remove .claude/worktrees/name`
+
+---
+
+## 5. 대화 로그(P24) 병렬 기록 문제
+
+### 5-1. 문제
+
+같은 날짜의 로그 파일에 여러 CLI가 동시에 write하면:
+- **방법 A**: 두 세션이 같은 파일을 열고 각자 append하면 마지막 저장이 이전 것을 덮어씀
+- **방법 B**: 워크트리별로 별도 복사본이므로 merge 시 충돌
+
+### 5-2. 해결 방안
+
+1. **세션별 로그 파일 분리** (권장):
+   - `2026-04-16_조직운영_세션1.md`
+   - `2026-04-16_조직운영_세션2.md`
+   - 또는 각 세션 지시 시 "로그는 `2026-04-16_코어개발.md`에 기록하라" 식으로 파일 분리
+
+2. **append 전용 규칙**: 한 세션만 특정 로그 파일에 기록하도록 지정
+
+3. **워크트리 방식 사용 시**: 각 워크트리의 로그를 merge 시점에 수동 통합
+
+---
+
+## 6. PD님을 위한 실행 가이드
+
+### 6-1. 가장 간단한 시작 방법 (방법 A)
+
+**사전 조건**: Claude Code가 설치되어 있고 `claude` 명령이 PATH에 있어야 합니다 (현재 v2.1.110 설치 확인됨).
+
+**단계**:
+
+1. **윈도우 앱에서 작업 지시** (평소대로)
+   - 에이전트가 긴 작업 수행 중...
+
+2. **새 터미널 열기**
+   - 방법 1: `Win + R` → `powershell` → Enter
+   - 방법 2: Windows Terminal 앱 실행 → 새 탭 (Ctrl+Shift+T)
+   - 방법 3: 작업 표시줄의 Windows Terminal 아이콘 우클릭 → "새 탭"
+
+3. **레포 디렉토리로 이동**:
+   ```
+   cd "D:\NerdNavis\NerdNavisAi"
+   ```
+
+4. **claude 실행**:
+   ```
+   claude
+   ```
+
+5. **작업 지시**: 원하는 업무를 한국어로 지시
+
+6. **추가 터미널이 필요하면** 2~5번 반복
+
+### 6-2. 빠른 질의만 하고 싶을 때
+
+터미널에서:
+```
+cd "D:\NerdNavis\NerdNavisAi"
+claude -p "현재 프로젝트의 코어 규칙 C14 내용을 요약해줘"
+```
+결과가 출력되면 바로 종료됩니다. 윈도우 앱 세션에 영향 없음.
+
+### 6-3. 워크트리로 안전한 병렬 작업
+
+```
+cd "D:\NerdNavis\NerdNavisAi"
+claude -w "기획검토" -n "기획검토 세션"
+```
+이렇게 하면:
+- `.claude/worktrees/기획검토/` 에 프로젝트 복사본 생성
+- `worktree-기획검토` 브랜치에서 독립 작업
+- 메인 디렉토리와 완전 격리
+
+---
+
+## 7. 윈도우 앱과 CLI의 관계
+
+| 항목 | 윈도우 앱 (MSIX) | CLI 터미널 |
+|------|------------------|-----------|
+| 세션 격리 | 독립 세션 | 독립 세션 |
+| 대화 이력 | 앱 내부 관리 | `~/.claude/` 하위 저장 |
+| 세션 공유 | 불가 (앱과 CLI는 별개) | CLI끼리 `--resume`으로 이어가기 가능 |
+| 설정 공유 | `.claude/settings.json` 공유 | 동일 |
+| MCP 서버 | 각자 독립 연결 | 각자 독립 연결 |
+| git 작업 | 같은 working tree | 같거나 워크트리로 분리 가능 |
+| 동시 실행 | 가능 (서로 독립) | 가능 (서로 독립) |
+
+**핵심**: 윈도우 앱의 세션과 CLI 세션은 완전히 독립입니다. 앱에서 에이전트가 작업 중이더라도 CLI에서 별도 세션을 시작할 수 있고, 서로 간섭하지 않습니다. 다만 **같은 파일을 동시에 수정하면 충돌 위험**이 있으므로 작업 영역을 구분하거나 `--worktree`를 사용하는 것이 안전합니다.
+
+---
+
+## 8. 최근 업데이트 정보 (2026-04-14~15)
+
+Claude Code Desktop 앱이 2026-04-14에 대규모 리디자인되어 **앱 내에서도 병렬 세션을 네이티브 지원**합니다:
+- 사이드바에서 `+ New session` (Ctrl+N)으로 새 세션 생성
+- 각 세션에 자동 git 워크트리 격리 적용
+- 세션 간 드래그앤드롭 레이아웃
+- PR merge 시 세션 자동 아카이브
+
+현재 너드나비스에서 사용 중인 Windows Store(MSIX) 버전에도 이 업데이트가 적용되었을 가능성이 높습니다. 앱 내 사이드바에 `+ New session` 버튼이 보이면 CLI 없이도 앱 내에서 병렬 작업이 가능합니다.
+
+---
+
+## 9. 너드나비스 운용 관점 권고
+
+### 9-1. 현행 규칙과의 정합성
+
+| 규칙 | 병렬 CLI 영향 | 대응 |
+|------|-------------|------|
+| C13 (공유 의무) | 각 CLI 세션의 작업을 트래킹해야 함 | 세션별 이름 부여 (`-n`), 로그 파일 분리 |
+| C18 (공유 완료 판정) | 워크트리 사용 시 main merge 필요 | merge 후 완료 판정 |
+| C20 (커밋 재량) | 병렬 세션 각각의 커밋 순서 관리 | 작업 영역 분리 원칙 |
+| C24 (영속 대화) | CLI는 C24 대상 아님 (임시 병렬용) | 주 작업은 윈도우 앱, CLI는 보조용 |
+| P24 (대화 로그) | 병렬 로그 기록 시 파일 충돌 | 세션별 로그 파일 분리 |
+
+### 9-2. 권장 운용 패턴
+
+1. **윈도우 앱 = 주 세션** (영속 대화, 조직 규칙 준수 주체)
+2. **CLI = 보조 세션** (빠른 질의, 독립 분석, 병렬 작업)
+3. CLI에서 파일 수정 작업 시 `--worktree` 사용 권장
+4. CLI 작업도 대화 로그에 기록 (별도 파일)
+5. 워크트리 작업 완료 후 main merge는 주 세션에서 수행
+
+---
+
+## 10. 참고 자료
+
+- Claude Code 공식 CLI 레퍼런스: https://code.claude.com/docs/en/cli-reference
+- Claude Code 병렬 워크플로 문서: https://code.claude.com/docs/en/common-workflows
+- Claude Code Desktop 리디자인 (2026-04-14): https://code.claude.com/docs/en/desktop