메뉴
열린 PR의 GitHub Actions/CI 실패를 분석해 원인을 분류하고, 코드·generated artifact·테스트·환경 문제를 근본 대응한 뒤 검증, 커밋, push까지 수행해야 할 때 사용한다. "CI 실패 대응", "체크 실패 봐줘", "Actions 실패 고쳐줘", "pr-checks 실패", "ci-ship" 요청에 사용한다.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | ci-ship |
| description | 열린 PR의 GitHub Actions/CI 실패를 분석해 원인을 분류하고, 코드·generated artifact·테스트·환경 문제를 근본 대응한 뒤 검증, 커밋, push까지 수행해야 할 때 사용한다. "CI 실패 대응", "체크 실패 봐줘", "Actions 실패 고쳐줘", "pr-checks 실패", "ci-ship" 요청에 사용한다. |
| argument-hint | [PR URL | PR number | check/job URL] |
| disable-model-invocation | false |
열린 PR의 CI 실패를 실제로 해소한다. 목표는 “실패 로그를 봤다”가 아니라 CI가 실패한 원인이 PR 변경과 어떻게 연결되는지 밝히고, 필요한 수정/검증/커밋/push로 다시 통과 가능한 상태를 만드는 것이다.
AI가 기본으로 할 수 있는 것:
AI가 사용자 명시 승인 없이 하면 안 되는 것:
CI rerun은 write side effect다. 새 commit push나 안전한 base-merge update push로 자동 재실행되는 CI는 괜찮지만, gh run rerun은 사용자가 명시 요청한 경우에만 수행한다.
Base branch update도 write side effect지만, 아래 Branch Freshness / Update Branch Decision 조건을 만족하면 ci-ship의 CI 복구 행위로 간주하고 별도 확인 없이 수행할 수 있다. 단 rebase/force-push는 금지하며, merge conflict가 나면 즉시 abort하고 사용자에게 차단 사유를 보고한다.
/ci-ship — 현재 branch의 PR CI 실패 수집 후 대응/ci-ship <PR URL> — 특정 PR의 실패 check 대응/ci-ship <PR number> — 현재 repo의 특정 PR 대응/ci-ship <Actions job URL> — 특정 failed job 우선 대응먼저 read-only로 실패 표면을 수집한다.
gh pr view <PR> --json number,title,url,headRefName,headRefOid,baseRefName,mergeStateStatus,reviewDecision,statusCheckRollup
실패/취소/timed out check만 우선 보되, 자동 대응 대상(actionable) 과 기본 제외 대상(excluded by default) 을 분리한다. 각 check에 대해:
기본 제외 대상:
fixme-alertFIXME 코멘트 체크, FIXME, TODO comment, comment policy처럼 의도적 주석/정책 gate만 나타나는 check이들은 CI rollup에는 남기지만, 사용자가 “FIXME도 지워서 통과시켜”, “모든 required check를 만족하게 해줘”처럼 명시하지 않는 한 자동 수정·검증·커밋 대상에서 제외한다. 특히 FIXME:는 임시 i18n/후속 작업 표식으로 의도적으로 남길 수 있으므로, ci-ship이 임의로 주석을 바꾸거나 삭제하지 않는다.
GitHub Actions job이면:
gh run view <run-id> --job <job-id> --log-failed
--log-failed가 빈약하면 전체 log를 더 좁혀 읽는다. tail만 보고 단정하지 않는다.
각 실패를 아래 중 하나로 분류한다.
| 분류 | 판단 기준 | 대응 |
|---|---|---|
| PR 변경으로 인한 코드 실패 | 타입/테스트/빌드가 변경 파일·새 API·새 behavior와 직접 연결 | 코드 수정 + 로컬 검증 + 커밋 |
| generated artifact stale | schema/codegen/i18n/snapshot/lockfile diff 요구 | 정식 generator 실행 + generated diff 확인 + 커밋 |
| stale base / branch behind | base가 앞서 있고 실패 로그·mergeState·로컬 재현이 base 최신화 필요성을 가리킴 | 안전 조건 확인 후 base merge update + 검증 + push |
| 테스트 기대값 stale | product behavior는 맞고 테스트가 이전 계약을 가정 | 테스트를 새 계약에 맞게 수정, 근거 기록 |
| flaky/timeout | 동일 commit 재시도/known flaky 근거가 있고 코드 원인 없음 | 근거 보고 또는 사용자 승인 후 rerun 제안 |
| infra/external | registry, network, secret, runner, third-party 장애 | 근거 수집 후 사용자/담당자 action 제시 |
| unrelated baseline | base branch에서도 실패하거나 PR 변경과 무관 | 근거를 남기고 현재 PR 영향 범위 분리 |
| intentional policy/comment gate | fixme-alert/FIXME 코멘트 체크처럼 의도적 주석·정책 표식을 금지하는 별도 gate이고, 사용자가 해당 표식을 유지하기로 한 맥락이 있음 | 자동 수정 대상에서 제외하고 최종 보고의 “제외/사용자 판단”으로 분리. 명시 요청이 있을 때만 수정 |
| unknown | 로그가 부족하거나 재현 불가 | 추가 로그/로컬 재현부터 수행 |
표면 대응 금지:
exit code 1만 보고 실패 원인을 단정하지 않는다.항상 실패한 step → 명령 → 실제 에러 → 관련 diff/파일 → 재현 명령 순서로 연결한다.
실패 로그를 보기 전후로 branch freshness를 함께 판단한다. CI 실패가 PR 코드 문제가 아니라 base 최신화 문제일 수 있기 때문이다.
Read-only 확인:
git fetch origin <baseRefName> <headRefName>
git status --short
git rev-parse HEAD
git rev-list --left-right --count origin/<baseRefName>...HEAD
판단 기준:
| 신호 | 의미 | 처리 |
|---|---|---|
mergeStateStatus가 BEHIND/out-of-date 계열 | GitHub가 branch update를 요구 | update 후보 |
| base-only commit 수가 1 이상이고 CI 로그가 base 변경 영향(스키마/락파일/테스트/merge ref)을 가리킴 | stale base 가능성 높음 | update 후보 |
| local HEAD에서는 통과하지만 PR merge ref/base 최신 상태에서만 실패 | stale base 가능성 높음 | update 후보 |
| merge conflict 또는 dirty worktree | 자동 update 불가 | abort/report |
| 실패가 변경 파일의 타입/테스트 오류로 명확함 | base update로 덮지 않음 | 코드 수정 우선 |
check가 아직 IN_PROGRESS이고 실패 로그가 없음 | 실패 아님 | 기다림/보고, update하지 않음 |
자동 update 안전 조건을 모두 만족해야 한다.
headRefName이거나, push 대상이 명확하다.git rev-parse HEAD가 PR headRefOid와 일치한다. 다르면 먼저 fetch/상태를 다시 보고 remote divergence를 설명한다.수행 방식:
git merge --no-edit origin/<baseRefName>
# conflict 발생 시:
# git merge --abort
# 최종 보고에 blocked로 기록
# conflict 없으면 CI 실패와 가장 가까운 로컬 검증 실행
git push origin HEAD:<headRefName>
GitHub의 Update branch 버튼과 같은 효과가 필요하면 기본은 /update-branch를 사용한다. 이 명령은 현재 PR을 식별해 gh pr update-branch를 원격에서 트리거하고, remote head 갱신 후 local worktree를 git pull --ff-only로 동기화한다. dirty worktree는 명령의 autostash 안전장치에 맡기되, local HEAD와 PR head가 다르거나 conflict로 GitHub update가 실패하면 로컬 merge로 억지 진행하지 말고 blocked로 보고한다. --rebase는 사용하지 않는다.
수정이 필요한 경우:
수정하지 않는 경우:
fixme-alert/FIXME 코멘트 체크 같은 intentional policy/comment gate이며 사용자가 의도적으로 유지한 표식일 가능성이 높음수정하지 않는 경우에도 “왜 코드 변경이 아닌지”를 최종 보고에 근거와 함께 남긴다. PR 코멘트는 사용자가 명시적으로 요청한 경우에만 남긴다.
CI의 실패 명령과 가장 가까운 로컬 명령을 실행한다.
예:
CI와 로컬 환경 차이가 있으면 차이를 명시한다.
fixme-alert처럼 기본 제외한 policy/comment gate는 로컬 재현을 필수로 돌리지 않는다. 단, 사용자가 해당 gate까지 해결하라고 명시한 경우에만 원 CI 스크립트와 같은 grep/check를 재현한다.
git status --short
git diff --check
git add <related files>
git commit -m "fix: address CI failure <summary>"
git push
커밋 메시지는 실패 원인 중심으로 쓴다.
ci-ship의 기본 완료 조건은 commit + push + 최종 보고다. PR comment는 기본 동작이 아니다.
다음처럼 사용자가 명시한 경우에만 코멘트를 남긴다.
명시 요청이 있을 때의 코멘트 형식:
CI 실패 대응 완료 (`<SHORT_SHA>`):
- 실패 check: <workflow/job/step>
- 원인: <root cause>
- 대응: <수정/생성/테스트 변경>
- 검증: `<local command>` ✅
- 비고: <rerun은 새 push로 자동 진행 / 수동 rerun은 하지 않음>
명시 요청이 있고 수정하지 않는 경우:
CI 실패 확인 결과 코드 변경은 하지 않았습니다.
- 실패 check: <workflow/job/step>
- 판단: <infra/flaky/baseline/외부 요인>
- 근거: <log/run URL/local command>
- 제안: <rerun 요청/담당자 확인/후속 action>
완료했습니다.
- PR: <url>
- 실패 분류: <code/generated/flaky/infra/baseline>
- 대응: <수정/생성/보류>
- 커밋: `<sha>` <message>
- Push: <branch>
- Base update: <수행/불필요/차단> (<근거>)
- 검증: `<command>` ✅ / ⚠️ <reason>
- 하지 않은 것: rerun/re-request/PR merge는 수행하지 않음
현재 worktree를 최신 production 기반 새 branch로 in-place 전환해야 할 때 사용한다. "/to-production", "production으로 옮겨", "production 바라보게", "hotfix로 다시 쌓아" 요청에 사용한다. 기존 작업 commit은 backup 후 cherry-pick하고, 새 worktree가 필요하면 /wt fork --hotfix가 담당한다.
열린 PR의 리뷰 코멘트나 changes requested에 대해 부모/현재 대화와 작업 내역을 확인한 뒤, 표면적 답변이 아니라 근본 원인을 판단해 코드 수정·커밋·푸시·스레드 답글·review re-request까지 수행해야 할 때 사용한다. `--push-only` 모드에서는 코멘트/re-request 없이 커밋·푸시 후 수동 게시용 답글 초안을 세션에서 다듬는다. "PR 코멘트 대응", "리뷰 대응", "이거 대응작업-커밋-푸시-코멘트까지", "근본적으로 대응", "대응할 게 없으면 근거 코멘트" 요청에 사용한다.
Local guide for using interactive_shell in this repo. Prefer it for dev servers, TUI apps, REPLs, database shells, log viewers, and commands that need a visible terminal overlay. Do not use it for subagent-style delegation; use the subagent tool for that.
PR을 만들기 전 또는 remote에 올리기 전, 변경사항을 의도 단위로 커밋하고 lint/typecheck/test/build 같은 사전 검증을 통과시킨 뒤 push해야 할 때 사용한다. "ship 해줘", "커밋해서 푸시", "올리기 전에 검증", "push 준비" 요청에 사용한다.
PR/구현 검증을 PM·비개발자도 이해할 수 있는 캡처 중심 HTML 리포트로 만든다. Jira/Notion/Slack/와이어프레임/PR test plan 같은 기획 근거를 사용자-facing 동작과 매핑하고, 핵심 UI 흐름은 스크린샷/GIF를 primary evidence로 증명한다. 로직/API/DB/code diff 검증은 하단 기술 보조 검증으로 정리한다. 기본은 로컬 확인용이며 업로드/PR 업데이트는 명시 요청 시에만 한다.
작업 시작 전에 구체 질문으로 목표·성공 기준·범위·검증 초점을 함께 좁히고, 이후 /decide·/verify가 mechanically 읽을 수 있는 frame.json을 워크트리에 박제한다.