# Task-936.1: 인포키워드 CLAUDECODE 환경변수 충돌 영구 수정

**작업일:** 2026-03-25 00:55 KST
**팀:** dev8-team (라/Ra)
**작업자:** Ra (개발8팀장)

---

## 1. 문제 요약

| 항목 | 내용 |
|------|------|
| **에러 메시지** | `Error: Claude Code cannot be launched inside another Claude Code session.` |
| **원인** | `CLAUDECODE` 환경변수가 상속되어 Claude CLI가 중첩 세션으로 인식 |
| **발생 위치** | `/home/jay/projects/InfoKeyword/worker/generator/keyword_generator.py` (line 95) |
| **영향** | Claude Code 세션 안에서 워커 실행 시 키워드 생성 실패 |

---

## 2. 수정 내용

### 2.1 keyword_generator.py (핵심 수정)

**파일:** `/home/jay/projects/InfoKeyword/worker/generator/keyword_generator.py`

**변경 전:**
```python
def _call_claude(prompt: str) -> str:
    """Claude CLI를 subprocess로 호출하고 텍스트 응답을 반환합니다."""
    try:
        result = subprocess.run(
            ['claude', '-p', prompt],
            capture_output=True, text=True, timeout=CLAUDE_CLI_TIMEOUT,
        )
    except subprocess.TimeoutExpired:
        raise RuntimeError(f"Claude CLI 타임아웃 ({CLAUDE_CLI_TIMEOUT}초)")
    if result.returncode != 0:
        raise RuntimeError(f"Claude CLI 오류 (code={result.returncode}): {result.stderr[:500]}")
    return result.stdout.strip()
```

**변경 후:**
```python
def _call_claude(prompt: str) -> str:
    """Claude CLI를 subprocess로 호출하고 텍스트 응답을 반환합니다.
    
    CLAUDECODE 환경변수를 제거하여 중첩 세션 오류를 방지합니다.
    Claude Code 세션 안에서 워커가 실행되어도 Claude CLI 호출이 정상 작동하도록.
    """
    # CLAUDECODE 환경변수 제거 (중첩 세션 방지)
    env = {k: v for k, v in __import__('os').environ.items() if k != 'CLAUDECODE'}
    
    try:
        result = subprocess.run(
            ['claude', '-p', prompt],
            capture_output=True, text=True, timeout=CLAUDE_CLI_TIMEOUT,
            env=env,
        )
    except subprocess.TimeoutExpired:
        raise RuntimeError(f"Claude CLI 타임아웃 ({CLAUDE_CLI_TIMEOUT}초)")
    if result.returncode != 0:
        raise RuntimeError(f"Claude CLI 오류 (code={result.returncode}): {result.stderr[:500]}")
    return result.stdout.strip()
```

**핵심 변경 사항:**
- `env` 파라미터 추가: `CLAUDECODE`를 제외한 모든 환경변수 전달
- `subprocess.run(..., env=env)` 형태로 명시적 환경 전달

### 2.2 start-worker.sh (보조 수정)

**파일:** `/home/jay/projects/InfoKeyword/scripts/start-worker.sh`

**변경 내용:**
```bash
#!/usr/bin/env bash
set -euo pipefail

# CLAUDECODE 환경변수 제거 (중첩 세션 방지)
# Claude Code 세션 안에서 워커가 실행되어도 Claude CLI 호출이 정상 작동하도록
unset CLAUDECODE

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
...
```

**핵심 변경 사항:**
- 스크립트 시작 부분에 `unset CLAUDECODE` 추가
- 워커 프로세스 자체가 `CLAUDECODE`를 상속받지 않도록 이중 방어

---

## 3. 검증 결과

### 3.1 테스트 결과

```
tests/test_task_936_1_claudecode_fix.py
5 passed in 0.06s ✅
```

**테스트 항목:**
1. ✅ `CLAUDECODE`가 subprocess 호출에서 제거됨
2. ✅ 다른 환경변수는 유지됨
3. ✅ subprocess.run 파라미터가 올바름
4. ✅ start-worker.sh에 unset 명령 포함
5. ✅ CLAUDECODE 설정된 환경에서도 키워드 생성 작동

### 3.2 기존 테스트 결과

```
67 passed in 0.55s ✅
```

**테스트 파일:**
- test_task_936_1_claudecode_fix.py (5개)
- test_api.py
- test_attachment.py
- test_external_links.py
- test_phone_address.py

### 3.3 실패한 기존 테스트 (사전 존재)

- `test_claude_integration.py::test_generate_keywords_calls_claude_cli` - **사전 존재 이슈** (내 수정과 무관)
  - 원인: 함수가 topic을 결과 앞에 추가하는데 테스트가 2개만 기대
  - 영향 없음: CLAUDECODE 수정과 무관

---

## 4. 수정 파일 목록

| 파일 | 수정 유형 | 변경 내용 |
|------|-----------|-----------|
| `worker/generator/keyword_generator.py` | 핵심 수정 | `env` 파라미터 추가, `CLAUDECODE` 제거 |
| `scripts/start-worker.sh` | 보조 수정 | `unset CLAUDECODE` 추가 |
| `tests/test_task_936_1_claudecode_fix.py` | 신규 생성 | 5개 테스트 케이스 |

---

## 5. 기술적 설명

### 5.1 환경변수 상속 문제

```
Claude Code 세션 (CLAUDECODE=abc123)
    ↓
Worker 프로세스 시작 (CLAUDECODE 상속)
    ↓
subprocess.run(['claude', '-p', prompt]) (CLAUDECODE 상속)
    ↓
Claude CLI: "중첩 세션 감지! CLAUDECODE 발견!"
    ↓
RuntimeError ❌
```

### 5.2 해결 방안

```
Claude Code 세션 (CLAUDECODE=abc123)
    ↓
Worker 프로세스 시작 (CLAUDECODE 상속)
    ↓
subprocess.run(['claude', '-p', prompt], env={CLAUDECODE 제거})
    ↓
Claude CLI: "독립 세션으로 인식"
    ↓
정상 작동 ✅
```

### 5.3 이중 방어 전략

1. **Python 레벨**: `keyword_generator.py`에서 `env` 파라미터로 명시적 제어
2. **Shell 레벨**: `start-worker.sh`에서 `unset CLAUDECODE`로 사전 차단

---

## 6. 사용자 가이드

### 6.1 수정 전 (수동 조치 필요)

```bash
# Claude Code 세션에서 워커 시작 시 에러 발생
cd /home/jay/projects/InfoKeyword
./scripts/start-worker.sh
# → RuntimeError: Claude CLI 오류

# 수동 해결
env -u CLAUDECODE ./scripts/start-worker.sh
```

### 6.2 수정 후 (자동 해결)

```bash
# Claude Code 세션에서도 바로 실행 가능
cd /home/jay/projects/InfoKeyword
./scripts/start-worker.sh
# → 정상 작동 ✅
```

---

## 7. 결론

**모든 목표 달성:**

1. ✅ **원인 분석**: subprocess 호출 시 CLAUDECODE 상속 확인
2. ✅ **keyword_generator.py 수정**: env 파라미터로 CLAUDECODE 제거
3. ✅ **start-worker.sh 수정**: unset CLAUDECODE 추가
4. ✅ **검증 완료**: 5개 테스트 통과, 기존 67개 테스트 통과

**이제 어떤 환경에서 워커를 실행하든 Claude CLI 호출이 정상 작동합니다.** ✅

---

**작업 완료 시간:** 2026-03-25 01:00 KST
**총 소요 시간:** 약 10분