From 762dbea90cbf1fba2485d682ee5e4b25bbce1ea6 Mon Sep 17 00:00:00 2001 From: swrring Date: Thu, 16 Apr 2026 16:53:23 +0900 Subject: [PATCH] =?UTF-8?q?docs(=EA=B0=9C=EB=B0=9C=ED=8C=80):=20Claude=20C?= =?UTF-8?q?ode=20=EC=BD=98=EC=86=94(CLI)=20=EB=B3=91=EB=A0=AC=20=EC=8B=A4?= =?UTF-8?q?=ED=96=89=20=EA=B8=B0=EC=88=A0=20=EA=B2=80=ED=86=A0=20=EB=B3=B4?= =?UTF-8?q?=EA=B3=A0=EC=84=9C=20(PD=EB=8B=98=20=EC=A7=80=EC=8B=9C)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CLI 병렬 세션 3가지 방법(동일 디렉토리/워크트리/일회성 질의), git 충돌 관리, 대화 로그 무결성 방안, PD님 실행 가이드 포함. Co-Authored-By: Claude Opus 4.6 (1M context) --- 공유/대화로그/조직운영/2026-04-16.md | 7 + .../2026-04-16_콘솔병렬실행_기술검토_개발팀.md | 287 ++++++++++++++++++ 2 files changed, 294 insertions(+) create mode 100644 공유/소통/개발팀→PM/2026-04-16_콘솔병렬실행_기술검토_개발팀.md diff --git a/공유/대화로그/조직운영/2026-04-16.md b/공유/대화로그/조직운영/2026-04-16.md index 3f8ab16..fd302a9 100644 --- a/공유/대화로그/조직운영/2026-04-16.md +++ b/공유/대화로그/조직운영/2026-04-16.md @@ -80,3 +80,10 @@ - **이유**: 대화 컨텍스트가 git에 저장되지 않는 문제 해결 + 조직 노하우 축적 - **산출물**: SKILL.md P24, 본 파일이 첫 대화로그 - **상태**: 완료 + + +## [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` +- **상태**: 완료 diff --git a/공유/소통/개발팀→PM/2026-04-16_콘솔병렬실행_기술검토_개발팀.md b/공유/소통/개발팀→PM/2026-04-16_콘솔병렬실행_기술검토_개발팀.md new file mode 100644 index 0000000..6ec30ab --- /dev/null +++ b/공유/소통/개발팀→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