# Sibling Tool Call Error 방지 시스템

## 배경
Claude Code의 병렬 tool 호출 시, **하나가 실패하면 나머지 sibling 호출이 전부 에러 처리**된다.
```
❌ <tool_use_error>Sibling tool call errored</tool_use_error>
```
특히 외부 네트워크 의존 호출(`gh api`, `curl`, `cokacdir` 등)에서 자주 발생.

## 작업 1: DIRECT-WORKFLOW.md에 병렬 호출 안전 규칙 추가

### 위치
`/home/jay/workspace/prompts/DIRECT-WORKFLOW.md`

### 추가할 섹션 (Step 3 이전, "## 워크플로우" 섹션 앞이나 뒤에)

```markdown
## 병렬 Tool 호출 안전 규칙

Claude Code에서 여러 tool을 병렬 호출할 때, **하나가 실패하면 나머지 sibling 호출이 전부 에러**된다.
이를 방지하기 위해:

1. **외부 호출은 순차 실행**: `gh api`, `curl`, `cokacdir`, `npm`, `pip` 등 네트워크 의존 호출은 절대 병렬로 묶지 않는다.
2. **파일 읽기도 안전하게**: 존재 여부가 불확실한 파일 Read는 병렬에 넣지 않는다. `ls`로 존재 확인 후 읽기.
3. **Bash exit code 주의**: 병렬 Bash 호출 중 하나가 exit code != 0 이면 sibling 전체 실패. `|| true`나 `2>/dev/null || echo "not found"` 패턴 사용.
4. **안전한 병렬 대상**: 로컬 파일 Read (존재 확인 완료), Glob, Grep — 이들은 병렬 안전.
5. **대형 파일 분할 읽기**: `gh api`로 큰 파일을 파트별로 읽을 때, part 1 → part 2 순차로 읽기. 병렬 분할 읽기 금지.
```

## 작업 2: teamlead-guide.md에도 동일 규칙 추가

### 위치
`/home/jay/workspace/prompts/teamlead-guide.md`

기존 가이드에 "병렬 호출 안전 규칙" 섹션 추가 (DIRECT-WORKFLOW.md와 동일 내용).

## 작업 3: Bash 래퍼 유틸리티 (선택)

팀장들이 `gh api` 호출 시 안전하게 사용할 수 있는 래퍼:

**`/home/jay/workspace/scripts/safe-gh-read.sh`**:
```bash
#!/bin/bash
# GitHub 파일 안전 읽기 (분할 + 순차)
# Usage: safe-gh-read.sh <owner/repo> <file_path>
REPO="$1"
FILE="$2"
CHUNK=5000

content=$(gh api "repos/$REPO/contents/$FILE" 2>/dev/null)
if [ $? -ne 0 ]; then
    echo "ERROR: Failed to fetch $REPO/$FILE" >&2
    exit 1
fi

echo "$content" | python3 -c "
import json, sys, base64
data = json.load(sys.stdin)
content = base64.b64decode(data['content']).decode('utf-8')
print(content)
"
```

이 스크립트는 `gh api` 호출을 한 번만 하고, Python으로 디코딩하여 전체 내용을 출력.
팀장이 파트 분할 없이 한 번에 읽을 수 있음.

## 테스트
1. DIRECT-WORKFLOW.md 수정 후 기존 test_team_prompts.py 통과 확인
2. safe-gh-read.sh 실행 테스트: `bash scripts/safe-gh-read.sh octocat/hello-world README.md`
3. pyright 체크 (해당 없음 — .md + .sh 파일만)

## QC 기준
- 문서 변경만이므로 Lv.1 수준
- 기존 테스트 깨지지 않음