lguidolin/ship-it

Ship It (배송하기)

완전한 배송 라이프사이클 처리: 스테이징, 커밋, 푸시, PR 열기, 병합 후 결정 기록 아카이브, 정리.

개요

모든 변경 사항은 브랜치와 PR을 거쳐야 합니다. 절대 main에 직접 푸시하지 마세요. 이 스킬은 병합 후 문서 아카이빙을 포함한 전체 마무리 주기를 처리합니다.

커밋 메시지는 문서입니다. PR 제목은 main에 스쿼시 병합 커밋으로 남으며 체인지로그에 나타납니다. PR 생성 시점에 제대로 작성하세요.

병합 후에만 아카이브하고, 절대 그 전에 하지 마세요. 사양과 계획은 PR이 병합될 때까지 접근 가능하게 유지됩니다. 병합 후에만 간결한 결정 기록으로 변환합니다.

사용 시기

• 사용자가 "push", "ship it", "let's ship", "open a PR", "create a PR"이라고 말할 때
• PR이 열린 후 사용자가 "merged", "it's merged", "pull and cleanup"이라고 말할 때
• 사용자가 구현을 완료하고 마무리하려 할 때
• 계획을 완료한 후 다음 단계가 작업을 제출하는 것일 때

사용하지 말아야 할 시기

• 사용자가 명시적으로 main에 직접 푸시하려 할 때 (먼저 의도를 확인하세요)
• 저장소에 원격 리포지토리가 설정되지 않은 경우
• 사용자가 아직 푸시할 준비가 안 된 작업 중인 변경 사항인 경우
• 사용자가 배송 없이 커밋만 하려는 경우 (conventional-commits-and-releases 사용)

프로세스

Phase 0: 확인 및 감지

빨간 테스트 스위트는 절대 PR이 되지 않습니다. 프로젝트의 전체 테스트 스위트를 먼저 실행하세요. 실패가 있으면 실패를 보고하고 중단하세요 — 커밋, 푸시, PR 열기를 하지 마세요. 이 게이트는 하우스 정책이며 위임되지 않습니다.

환경 감지(일반 저장소 vs. 명명된 브랜치 워크트리 vs. 분리된 HEAD)와 베이스 브랜치 결정은 superpowers:finishing-a-development-branch에 위임되며, 이 스킬은 이미 세 가지 경우를 모두 처리합니다.

올바른 방법으로 가용성을 확인하세요: 사용 가능한 스킬 목록에서 finishing-a-development-branch를 찾으세요. 목록에 있으면 호출 가능합니다. 목록에 없으면 호출 불가능하므로 대체 절차를 진행하세요.

파일시스템을 조사하지 마세요. ~/.claude/plugins/cache/에는 가져온 모든 버전이 저장되어 있으며, 설치되었지만 비활성화된 플러그인도 포함됩니다. 스킬은 플러그인 캐시 외의 메커니즘으로 제공될 수 있습니다. 캐시 아래에 경로가 존재한다고 해서 스킬을 호출할 수 있다는 증거는 되지 않습니다.

사용 가능한 경우 — 테스트 검증, 환경 감지, 베이스 브랜치 결정을 위해 호출한 후, 옵션 메뉴 전에 중단하세요.

통합 결정은 이미 하우스 규칙에 의해 이루어졌으며 사용자가 다시 결정할 사항이 아닙니다: 이 프로젝트는 PR을 통해서만 병합합니다. PR이 미리보기 배포와 CI 게이트를 생성하기 때문입니다. 로컬에서 <base>로 병합하는 옵션은 사용할 수 없습니다. "브랜치를 그대로 유지" 옵션은 유효합니다 — 이는 게이트를 우회하지 않고 결정을 연기하는 것입니다.

없는 경우 — 대체 절차를 진행하며, 정확성을 보장하는 데 필요한 것을 잃지 않습니다:

• 테스트 스위트를 직접 실행합니다.
• 브랜치의 업스트림 또는 main을 베이스로 간주하고, 계속 진행하기 전에 사용자에게 확인합니다.
• Phase 6의 워크트리 정리를 건너뛰고, 브랜치를 일반적으로 삭제합니다.

Phase 1: 스테이징 및 커밋

git status --short
git branch --show-current
git log --oneline @{upstream}..HEAD 2>/dev/null || echo "No upstream set"

결정 트리:

• main에 있고 커밋되지 않은 변경 사항이 있는 경우 → 브랜치 생성, 커밋, 푸시, PR
• 기능 브랜치에 있고 커밋되지 않은 변경 사항이 있는 경우 → 커밋, 푸시, PR (또는 기존 PR 업데이트)
• 기능 브랜치에 있고 푸시되지 않은 커밋이 있는 경우 → 푸시, PR (또는 기존 PR 업데이트)
• 기능 브랜치에 기존 PR이 있는 경우 → 푸시 (PR이 이미 존재)

스테이징되지 않은 변경 사항이 있는 경우:

• 사용자에게 모든 변경 사항을 포함할지 특정 파일만 포함할지 물어보세요.
• 변경 사항이 여러 관심사에 걸쳐 있는 경우 분할을 제안하세요.

커밋 메시지 작성:

유형	사용 시기
feat	새로운 기능
fix	버그 수정
docs	문서만 변경
chore	설정, 의존성, 도구
refactor	코드 구조 변경, 동작 변경 없음
test	테스트 추가 또는 수정
ci	CI/CD 워크플로 변경

형식: <유형>[선택적 범위]: <명령형 설명>

규칙:

• 명령형 어조 사용 ("added"나 "adds"가 아닌 "add")
• 콜론 뒤 첫 단어는 소문자
• 끝에 마침표 없음
• 짧게 (제목은 50자 이하)
• 무엇을 하는지 설명하고, 어떻게 하는지는 설명하지 않음

커밋 전에 제안된 커밋 메시지를 사용자에게 제시하고 확인을 받으세요.

Phase 2: 브랜치 및 푸시

main에 있는 경우 브랜치를 생성하세요:

<유형>/<짧은-설명>

예시:

• feat/oauth-login
• fix/null-response-handling
• docs/release-workflow-permissions

푸시:

git push -u origin $(git branch --show-current)

Phase 3: PR 열기

PR 제목 = 컨벤셔널 커밋 메시지 (main에 스쿼시 병합 시 사용됨).

PR 본문 구조:

## 변경 사항

[추가/수정/제거 사항에 대한 구체적 설명]

## 이유

[동기 — 이 변경이 해결하는 문제]

gh CLI를 사용하여 생성:

gh pr create --title "<컨벤셔널 커밋 메시지>" --body "<PR 본문>"

gh를 사용할 수 없는 경우, git push 출력에서 PR URL을 제공하거나 직접 구성하세요.

미리보기 환경이 정상적으로 올라왔는지 확인하세요. 프로젝트가 PR별 미리보기를 배포하는 경우, 해당 워크플로가 완료될 때까지 기다리고 환경에 접근 가능한지 확인한 후 PR을 넘기세요:

gh pr checks --watch

미리보기 배포에 실패하면 보고하고 중단하세요. 검토할 수 없는 PR은 배송된 것이 아닙니다.

이 스킬이 멈추는 지점입니다. ship-it의 배포 인식은 미리보기에서 끝납니다. 스테이징 및 프로덕션 프로모션은 이 스킬의 역할이 아닙니다 — 이는 프로젝트의 배송 스킬(cloud-delivery-aks 또는 이와 동등한 것)에 속합니다. 아래 Phase 4-6은 Git 및 문서 위생이며, 배포가 아닙니다.

Phase 4: 병합 대기

PR 생성 후 질문: "병합되면 알려주세요. 제가 정리와 아카이브를 처리하겠습니다."

사용자의 확인을 기다립니다 (예: "merged", "done", "it's merged").

Phase 5: 병합 후 — 결정 기록 아카이브

사양과 계획은 설계상 상세합니다 — 사람이 이력을 읽는 데는 좋지만, Claude가 로드할 때마다 비용이 많이 듭니다. 이를 간결한 결정 기록으로 변환하면 필수 결정을 저렴하게 읽을 수 있고, 전체 내용은 디스크에 아카이브되어 누군가 의도적으로 열기 전까지 비용이 들지 않습니다.

PR이 병합된 후에만, 변환되지 않은 사양/계획을 확인하세요:

ls docs/superpowers/specs/ 2>/dev/null
ls docs/superpowers/decisions/ 2>/dev/null

recording-decisions 스킬에는 이를 위한 두 개의 도우미가 포함되어 있습니다. 이를 찾으세요 — 스킬이 프로젝트에 설치되어 있거나 전역에 설치되어 있을 수 있습니다:

for base in .claude/skills ~/.claude/skills; do
  d="$base/recording-decisions/scripts"
  [ -d "$d" ] && echo "$d" && break
done

찾은 경우, $d/doc-archive.sh는 변환되지 않은 사양을 나열하고 변환 프롬프트를 출력하며, $d/index-rebuild.sh는 인덱스를 재생성합니다. 찾지 못한 경우, 아래 단계를 사용하여 동일한 작업을 수동으로 수행하세요 — 이 단계들은 자체 완결적입니다.

변환되지 않은 사양/계획이 존재하는 경우:

1. 사용자에게 질문: "이 작업에 해당하는 사양/계획을 찾았습니다. 간결한 결정 기록으로 변환하고 원본을 아카이브할까요?"

2. 예인 경우, 각 사양에 대해:

   • 사양 내용 읽기
   • YAML 프론트매터가 포함된 결정 기록 생성:

     ---
     title: <사양에서 추출>
     date: <사양 파일명에서>
     component: <내용에서 유추>
     status: implemented
     supersedes: null
     dependencies: [<유추>]
     ---
     

   • 약 30-50줄 작성: 주요 결정, 인터페이스, 제약 조건 포함
   • docs/superpowers/decisions/<날짜>-<주제>.md에 저장
   • 원본 사양을 docs/superpowers/archive/specs/로 이동
   • 일치하는 계획을 docs/superpowers/archive/plans/로 이동

3. 마스터 인덱스 재구축 — 모든 결정 기록의 프론트매터에서 docs/superpowers/index.md를 재생성하고, 활성 결정 테이블(구성 요소, 제목, 날짜, 의존성)과 대체됨 테이블(구성 요소, 제목, 대체한 항목)로 그룹화합니다. 위에서 찾은 $d/index-rebuild.sh를 실행하거나, 직접 파일을 작성하세요.

4. 아카이브 커밋:

   git add docs/superpowers/
   git commit -m "docs: archive specs and update decision index"
   git push
   

Phase 6: 정리

git checkout main
git pull
git branch -d <브랜치-이름>
git push origin --delete <브랜치-이름> 2>/dev/null || true
git fetch --prune

깨끗한 상태 확인:

git branch --show-current
git log --oneline -3

작업이 Git 워크트리에서 이루어진 경우, 정리를 superpowers:finishing-a-development-branch에 위임하세요 (이 스킬은 소유권 기반 정리를 수행하며, 자신이 소유한 워크트리는 알고 외부에서 관리되는 것은 그대로 둡니다). 해당 스킬을 사용할 수 없는 경우, git worktree remove <경로>로 수동으로 워크트리를 제거하고 먼저 사용자에게 확인하세요.

핵심 원칙

• 빨간 테스트 스위트는 절대 PR이 되지 않음 — 다른 것보다 먼저 확인 (Phase 0)
• main에 직접 푸시 금지 — 항상 브랜치 + PR. PR이 미리보기 배포이자 CI 게이트이며, 로컬 병합은 둘 다 건너뜁니다. 이는 로컬 병합을 선택지로 제공하는 모든 워크플로를 무효화합니다.
• 배송은 미리보기에서 끝남 — 병합, 아카이브, 정리는 위생이며, 스테이징 및 프로덕션 프로모션은 별도 스킬의 역할
• 컨벤셔널 커밋 — PR 제목이 체인지로그 항목
• 병합 후에만 아카이브 — 사양은 검토 중에도 접근 가능하게 유지
• 결정 기록은 간결함 — 약 30-50줄, YAML 인덱싱, LLM 최적화
• 완전히 정리 — 오래된 브랜치나 추적 참조 없음