ship 설치 가이드 — Claude Agent 워크플로

🌿 브랜치 생성 feat/{slug}-{YYYYMMDD-HHmmss} ← 보호 브랜치면 자동 생성, 아니면 현재 브랜치 사용 ↓ Phase 1 Architect → plan.md + agents.txt 자동 생성 ↓ Debate 1 🔴 Red 공격 → 🔵 Blue 수정 → ⚖️ Judge 판정 (최대 2라운드) ↓ Phase 3 Wave A (backend·frontend·debugger) 병렬 실행 ↓ 💾 커밋/푸시 Wave A 완료 후 자동 커밋 ↓ Phase 3 Wave B (reviewer·test·security) ← A 패널 유지된 채 시작 ↓ 💾 커밋/푸시 Wave B 완료 후 자동 커밋 → A+B 패널 정리 ↓ Debate 2 구현 결과 토론 REWORK 시 Wave 재실행 (횟수 무제한) ↓ Phase 4 tsc → eslint → test → build (CI 하네스 게이트) ↓ Phase 5 게이트 실패 시 자동 수정 (최대 3라운드, 라운드마다 커밋) ↓ 📬 PR 생성 항상 실행 게이트 통과 → 일반 PR / 실패 → Draft PR

1

사전 요구사항 설치

Homebrew (미설치 시)

terminal
/bin/bash -c "$(curl -fsSL
                            https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

필수 도구

terminal
# Node.js (nvm 권장)
                        curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
                        nvm install --lts && nvm use --lts

                        # tmux — wave 패널 분할에 필수
                        brew install tmux

                        # gh — PR 자동 생성에 필수
                        brew install gh && gh auth login
                    

2

Claude Code 설치 및 인증

terminal
npm install -g @anthropic-ai/claude-code
                        claude # 인증 (Anthropic 계정 필요)
                        claude --version
                    

3

전역 설정 파일 구성

~/.claude/settings.json
mkdir -p ~/.claude/agents ~/.claude/commands

                        cat > ~/.claude/settings.json << 'EOF'
                        {
                        "env": {
                        "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
                        },
                        "permissions": {
                        "allow": [
                        "Read(**)", "Write(**)", "Edit(**)",
                        "Bash(git *)", "Bash(gh *)", "Bash(npm *)", "Bash(npx *)",
                        "Bash(node *)", "Bash(ls *)", "Bash(cat *)", "Bash(echo *)",
                        "Bash(mkdir *)", "Bash(cp *)", "Bash(mv *)", "Bash(rm *)",
                        "Bash(touch *)", "Bash(find *)", "Bash(grep *)",
                        "Bash(sed *)", "Bash(awk *)", "Bash(tmux *)"
                        ],
                        "deny": []
                        }
                        }
                        EOF
                    

4

글로벌 CLAUDE.md 작성

모든 프로젝트에서 자동 로드되는 전역 규칙. 스택·레이어 규칙·커밋 규칙 등을 작성합니다.

~/.claude/CLAUDE.md
cat > ~/.claude/CLAUDE.md << 'EOF'
                        # 글로벌 하네스 규칙

                        ## 스택
                        - React Native (Expo) + TypeScript
                        - Next.js 14+ App Router + TypeScript

                        ## TypeScript 규칙
                        - strict: true 필수 — any 사용 금지
                        - export 함수는 반환 타입 명시
                        - Zod 로 런타임 검증

                        ## 레이어 규칙 (단방향 import)
                        app/ → components/ → hooks/ → lib/ → services/ → types/

                        ## 절대 금지
                        - .env* 커밋 / main 직접 push
                        - 프로덕션 console.log / git push --force
                        EOF
                    

5

Agent 파일 설치

ship이 선택해서 실행하는 에이전트 정의 파일입니다. Wave A / B로 분류됩니다.

에이전트	Wave	역할
🔧 backend	Wave A	API Route Handler, 서비스 레이어, Zod 검증
🎨 frontend	Wave A	React 컴포넌트, TanStack Query, Tailwind CSS
🐛 debugger	Wave A	경쟁 가설 방식 버그 원인 분석 및 수정
👀 reviewer	Wave B	가독성, 타입 안전성, 레이어 규칙 리뷰
🧪 test	Wave B	Vitest + Testing Library, 커버리지 80%+
🔒 security	Wave B	OWASP Top 10, 인증/인가, 시크릿 검토

~/.claude/agents/ — 예시 (backend)
cat > ~/.claude/agents/backend.md << 'EOF'
                        ---
                        name: backend
                        description: API·서비스·도메인 로직 담당. Next.js Route Handlers/Server Actions.
                        ---
                        당신은 백엔드 전문 에이전트입니다.
                        - Next.js Route Handler / Server Action 구현
                        - 서비스 레이어 비즈니스 로직 / Zod 스키마로 요청/응답 검증
                        - services/ → types/ 단방향 import만 허용
                        EOF

                        # 나머지 에이전트도 동일한 방식으로 생성
                        # frontend.md / debugger.md / reviewer.md / test.md / security.md
                    

6

Command 파일 설치

~/.claude/commands/ship.md
cat > ~/.claude/commands/ship.md << 'EOF'
                        ---
                        description: 기획부터 배포까지 전체 자동 실행 (동적 에이전트 선택)
                        ---
                        터미널에서 `ship "기능 설명"` 명령어를 사용하세요.
                        EOF

7

ship 스크립트 설치

terminal
# 1. 레포 클론 (처음 한 번)
                        git clone https://github.com/project-hh-com/tmux.git ~/development/tmux

                        # 2. 심볼릭 링크 생성 — 소스 파일 하나만 관리
                        mkdir -p ~/.local/bin
                        ln -sf ~/development/tmux/ship/ship ~/.local/bin/ship

                        # 3. 실행 권한
                        chmod +x ~/.local/bin/ship

                        # 4. PATH 설정
                        echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
                        source ~/.zshrc
                        which ship # → /Users/[이름]/.local/bin/ship
                    

💡

심볼릭 링크의 장점

~/.local/bin/ship은 ~/development/tmux/ship/ship을 직접 가리켜요. 소스 파일 하나만 관리하면 되고, git pull만 해도 바로 최신 버전으로 실행됩니다. 별도 복사 불필요.

🔄

업데이트 방법

cd ~/development/tmux && git pull — 끝. 심볼릭 링크가 최신 소스를 자동으로 참조합니다.

Git 워크플로 동작 방식

ship은 실행 시작부터 끝까지 git 작업을 자동으로 처리합니다.

1

브랜치 자동 생성 — main·master·prd·develop에서 실행하면 feat/{slug}-{YYYYMMDD-HHmmss} 브랜치를 자동 생성. 이미 feature 브랜치에 있으면 현재 브랜치 사용.
2

중간 커밋/푸시 — Wave A 완료 후, Wave B 완료 후, 자동 수정 라운드마다 자동 커밋. 변경사항 없으면 스킵.
3

PR 생성 (항상 실행) — CI 게이트 통과 여부와 무관하게 Phase 6에서 항상 PR을 생성. 게이트 실패 시 Draft PR, 통과 시 일반 PR. 라벨 Claude Agent 자동 부착.

🚫

PR 베이스 브랜치 보호

릴리스 매니저는 prd·master를 베이스로 한 PR을 절대 생성하지 않습니다. 해당 상황이 감지되면 즉시 중단하고 사유를 보고합니다.

8

tmux 설정

~/.tmux.conf
cat > ~/.tmux.conf << 'EOF'
                        set -g mouse on
                        set -g pane-border-status top
                        set -g pane-border-format " #{pane_title} "
                        set -g default-terminal "screen-256color"
                        bind | split-window -h -c "#{pane_current_path}"
                        bind - split-window -v -c "#{pane_current_path}"
                        EOF

                        tmux source-file ~/.tmux.conf 2>/dev/null || true
                    

Wave 레이아웃

┌──────────────┬─────────────┬─────────────┐ │ 🚢 ship │ 🔧 backend │ 👀 reviewer │ │ (메인) │─────────────│─────────────│ │ │ 🎨 frontend │ 🧪 test │ │ │─────────────│─────────────│ │ │ 🐛 debugger │ 🔒 security │ └──────────────┴─────────────┴─────────────┘ Wave A 완료 후 Wave B 열림 (A 유지) Wave B 완료 후 A+B 모두 닫힘 → 메인 복귀

9

프로젝트별 설정

.claude/settings.local.json
mkdir -p .claude

                        cat > .claude/settings.local.json << 'EOF'
                        {
                        "permissions": {
                        "allow": [
                        "Read(**)", "Write(**)", "Edit(**)",
                        "Bash(git *)", "Bash(gh *)", "Bash(npm *)", "Bash(npx *)",
                        "Bash(node *)", "Bash(tmux *)", "Bash(ls *)"
                        ],
                        "deny": []
                        },
                        "additionalDirectories": ["/Users/YOUR_USERNAME/.claude"]
                        }
                        EOF
                    

⚠️

YOUR_USERNAME을 실제 macOS 사용자명으로 변경하세요. 확인: echo $HOME

10

사용법

기본 실행

terminal
# 1. 프로젝트로 이동
                        cd ~/development/my-project

                        # 2. tmux 세션 시작 (패널 분할을 위해 필수)
                        tmux new-session -s work

                        # 3. ship 실행
                        ship "구현하거나 수정할 내용을 자연어로 설명"
                    

요청 유형별 자동 에이전트 선택

요청 예시	선택 에이전트	Wave 구성
`"로그인 버그 수정"`	🐛 debugger + 🔧 backend + 🧪 test	A: 2개 · B: 1개
`"마이페이지 UI 구현"`	🎨 frontend + 🧪 test	A: 1개 · B: 1개
`"결제 기능 추가"`	🔧 backend + 🎨 frontend + 🧪 test + 👀 reviewer	A: 2개 · B: 2개
`"보안 점검"`	🔒 security + 👀 reviewer	A: — · B: 2개

Debate 2 초점 자동 결정

에이전트 포함 여부	Debate 2 주제	REWORK 허용
`test` 포함	테스트 커버리지 및 품질 검토	✅
`reviewer` 포함	코드 리뷰 결과 검토	✅
둘 다 없음	plan.md 기반 일반 검토	✅

실행 중 터미널 출력 예시

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🚢 ship: "결제 API 연동 및 완료 화면 구현" 🌿 브랜치: feat/api-20260424-153012 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📋 Phase 1: 설계 검토 및 에이전트 선택... 🗣️ 토론: 설계 계획 검토 🔴 Round 1/2 — Red 공격 중... 🔵 Round 1/2 — Blue 방어 중... ⚖️ 판정: CONSENSUS 🔨 Phase 3: 에이전트 2-웨이브 실행 ▶ Wave A (구현) (2개) 시작... ⏳ Wave A 완료: 2/2 (45s) ✅ Wave A 완료 ✅ 커밋/푸시 완료 ← 중간 자동 커밋 ▶ Wave B (검증) (2개) 시작... ✅ 커밋/푸시 완료 ← 중간 자동 커밋 🔍 Phase 4: 하네스 게이트 ✅ tsc · eslint · test · build 통과 📦 Phase 6: 릴리스 매니저 실행 중... ✅ PR 생성: https://github.com/.../pull/42

tmux 단축키

단축키	기능
`Ctrl+B 방향키`	패널 이동
`Ctrl+B z`	현재 패널 전체화면 토글
`Ctrl+B x`	패널 닫기
`Ctrl+B d`	세션 나가기 (백그라운드 유지)
`tmux attach -t work`	세션 다시 접속

✓

전체 설치 순서 요약

brew install tmux

brew install gh && gh auth login

npm install -g @anthropic-ai/claude-code && claude

mkdir -p ~/.claude/agents ~/.claude/commands

~/.claude/settings.json 생성

~/.claude/CLAUDE.md 생성

agents/*.md 6개 생성 (backend·frontend·debugger·reviewer·test·security)

commands/ship.md 생성

git clone https://github.com/project-hh-com/tmux.git
                        ~/development/tmux

mkdir -p ~/.local/bin && ln -sf
                        ~/development/tmux/ship/ship ~/.local/bin/ship

chmod +x ~/.local/bin/ship

PATH에 ~/.local/bin 추가 (.zshrc)

~/.tmux.conf 설정

프로젝트별 .claude/settings.local.json 생성

?

문제 해결

ship: command not found

export PATH="$HOME/.local/bin:$PATH"
                        which ship

permission denied: ship

chmod +x ~/.local/bin/ship

tmux 패널이 분할 안 됨

echo $TMUX # 비어있으면 tmux 밖에서 실행 중
                        tmux new-session -s work

PR이 생성되지 않음

# gh 인증 확인
                        gh auth status

                        # 릴리스 매니저 로그 확인
                        cat .agent/ship-[타임스탬프]/release_manager.log
                    

ℹ️

Phase 6은 게이트 실패 시에도 항상 실행됩니다. PR이 생성되지 않았다면 release_manager.log에서 원인을 확인하세요.

에이전트가 항상 기본값으로 나옴

# agents.txt 확인
                        cat .agent/ship-[타임스탬프]/agents.txt

                        # architect 로그 확인
                        cat .agent/ship-[타임스탬프]/architect.log
                    

토론이 너무 오래 걸림

Debate는 에이전트 3개(Red/Blue/Judge)가 순차 실행되므로 라운드당 시간이 걸려요. ship 파일에서 run_debate 함수의 MAX_ROUNDS=2를 1로 줄이면 빨라져요.

토론 결과 확인

# 가장 최근 실행 로그 목록
                        ls -t .agent/ | head -1 | xargs -I{} ls .agent/{}

                        # 판정 결과만 보기
                        cat .agent/ship-[타임스탬프]/judge_plan_1.md
                        cat .agent/ship-[타임스탬프]/judge_review_1.md
                    

ship 스크립트 업데이트

cd ~/development/tmux && git pull