# 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