SwiftShip
validate
iOS 및 macOS 앱을 위한 명세 기반 개발(Spec-driven development)으로, Claude Code를 통해 완전히 실행됩니다.
모든 변경 사항은 지속적 통합(CI)에서 확인됩니다. 210개 이상의 모든 스킬 참조는 [skills library]와 비교되며, 문서화된 카운트는 실제와 일치하고, 모든 명령어가 등록되며, 프론트매터(frontmatter)가 잘 구성되어 있습니다 (scripts/validate.sh).
SwiftShip은 [GSD의 워크플로우 방법론(workflow methodology)]과 깊이 있는 Apple 플랫폼 전문 지식을 결합하여, 사용자가 '앱 아이디어가 있습니다'라는 상태에서부터 세션 간 맥락을 잃지 않고 'App Store에 라이브하게 배포됩니다'까지 안내합니다.
SwiftShip이란 무엇인가요?
혼자 두면 매우 뛰어나지만 기억력이 부족한 AI 비서와 함께 앱을 구축하는 것을 상상해 보세요. 이 비서는 지난주의 결정을 기억하지 못하고, Apple의 모든 규칙을 자동으로 알지 못합니다.
SwiftShip은 Claude Code 위에 자리 잡는 프로젝트 매니저이자 Apple 전문가 팀입니다. 이는 사용자에게 다음을 제공합니다:
- 명확한 경로(A clear path) — 아이디어에서 디자인, 빌드, 테스트, 배포(ship)까지 안내하는 일련의 간단한 명령어(예:
/apple:something)입니다.
- 기억력(A memory) — 프로젝트 내부에 숨겨진
.planning/ 폴더가 사용자의 명세(spec), 로드맵, 결정 사항 및 진행 상황을 기록하여, 오늘 멈추고도 내일 정확히 중단했던 지점부터 재개할 수 있게 합니다.
- 대기 전문가(Specialists on call) — 까다로운 부분(SwiftUI 화면, 인앱 결제, iCloud 동기화, App Store 검토 등)에 대해서는 적절한 '에이전트(agent)'가 자동으로 투입됩니다.
⚠️ 중요: SwiftShip은 앱도 아니고 컴파일하는 프로그램도 아닙니다. 이는 Claude Code에게 프로젝트 매니저처럼 행동하도록 가르치는 신중하게 작성된 일련의 지침 파일(Markdown)입니다. 구축할 것이 아무것도 없으며, 단순히 설치하고 명령어를 입력하기만 하면 됩니다.
간단한 개념적 이해
앱을 만드는 것은 집을 짓는 것과 같습니다:
| House | SwiftShip |
|---|
| Blueprints & permits | .planning/ 파일 (spec, roadmap, plan) |
| ... | |
주요 특징 (Highlights)
- 전체 라이프사이클을 포괄하는 53개 명령어: 아이디어 검증(idea validation), 계획 수립(planning), 빌드(building), 테스트(testing), App Store 메타데이터, 스크린샷, TestFlight, 제출(submission), 그리고 출시 후 관리까지를 아우릅니다.
- 신규 앱과 기존 앱 모두에 적용 가능: 하나의 명령어로 기존 코드를 매핑할 수 있으며, 또 다른 명령어로 이를 단계별 기능 추가 및 버그 수정 릴리스 계획으로 전환합니다.
- 앱 실행 및 스크린샷 촬영: 단순하게 “작동하는지?”를 묻는 것을 넘어, 실제 앱(iOS Simulator 또는 실제 Mac 앱)을 구동하여 품질 검사 명령어를 수행하고 확인할 수 있습니다.
- 선택적 App Store Connect 자동화: 적절한 도구를 연결하면, 메타데이터, 릴리스 노트, TestFlight 설정 등을 App Store Connect로 푸시할 수 있습니다. 이 과정은 항상 미리보기를 보여주고 사용자에게 먼저 확인을 요청합니다. (최종 “검토용 제출(Submit for Review)” 결정권은 항상 사용자에게 있습니다.)
- 데이터 기반 계획 수립: 실제 다운로드 수, 판매량, 충돌(crashes), 리뷰 등의 데이터를 끌어와 다음 개발할 기능을 결정하는 데 활용할 수 있습니다.
- 이식성 (Portable): 단 하나의 스크립트로 모든 Mac에 설치되며, 수정해야 할 하드코딩된 경로가 없습니다.
- 기본적으로 우아함 (Graceful by default): 모든 “스마트” 기능은 선택 사항입니다. 만약 도구가 설치되어 있지 않다면, 해당 명령어는 조용히 일반적인 수동 지침으로 대체됩니다. 아무것도 고장 나지 않습니다.
작동 방식 (How it works)
┌─────────────────────────────────────────────────────────────────────────┐
│ 명령어 (COMMANDS) (사용자가 입력하는 내용) │
│ /apple:validate → /apple:new-app → /apple:roadmap → /apple:plan → ... │
...
선택적 도구 핸드오프(Optional tool handoffs): 지원되는 도구가 연결되면, 일부 명령어는 단순히 수동 단계를 출력하는 대신 실행할 수 있습니다 (메타데이터 푸시, 실행 중인 앱 스크린샷 촬영, 판매 내역 읽기 등). 이 기능들은 항상 **선택적 참여(opt-in), 미리 보기 우선(preview-first), 그리고 실행 전 확인(confirm-before-acting)**을 거치며, 아무것도 연결되어 있지 않아도 **점진적으로 저하(degrade gracefully)**됩니다. 즉, 모든 명령어는 단순히 수동 지침을 제공합니다. (자세한 내용은 Optional power-ups를 참조하세요.)
설치(Installation)
SwiftShip은 Mac에서 **Claude Code**와 **Xcode + Swift 툴체인(toolchain)**이 필요합니다. 이 라이브러리가 읽는 보조 "매뉴얼" 라이브러리([claude-code-apple-skills])는 아래의 설치 경로 중 하나를 사용합니다.
플러그인으로 설치 (권장)
Claude Code에서:
/plugin marketplace add rshankras/claude-code-apple-skills
/plugin install apple-skills@indie-apple-stack
/plugin install apple@indie-apple-stack
그런 다음 앱 프로젝트에서 **새 세션(fresh session)**을 시작하고 /apple:help를 실행합니다. 업데이트는 언제든지 /plugin marketplace update indie-apple-stack으로 수행할 수 있으며, 제거하려면 /plugin uninstall apple을 사용하세요.
- 두 플러그인 모두 설치합니다.
apple은 워크플로우이며, apple-skills는 이 명령어들이 읽는 지식 라이브러리입니다. 세션 시작 훅(session-start hook)이 두 플러그인 간의 파일 경로를 자동으로 연결해 줍니다.
- 왜 이름이
swiftship이 아니라 apple인가요? 플러그인의 이름은 명령어 네임스페이스(command namespace)입니다. 이름을 apple로 지정했기 때문에 명령어가 /apple:build, /apple:plan, …와 같이 표시됩니다. 플러그인 브라우저에서는 SwiftShip으로 나타납니다.
- 플러그인 설치 시 사용 기록 장부(usage ledger)가 기본적으로 활성화됩니다. 이 플러그인은 SwiftShip의 로컬 전용 사용 훅(
~/.claude/swiftship-usage.jsonl — 타임스탬프, 명령어 이름, 결과만 기록; 절대 기기를 벗어나지 않습니다)을 등록합니다. /plugin disable apple로 비활성화하거나 언제든지 파일을 삭제할 수 있습니다. 수동 설치는 여전히 엄격하게 선택적(opt-in)입니다 (아래 참조).
- 수동 설치에서 마이그레이션하는 경우? 중복된
/apple:* 명령어가 생기는 것을 방지하기 위해 먼저 체크아웃 위치에서 ./install.sh --uninstall을 실행하세요. 만약 사용 기록 훅(usage hook)에 동의했다면, ~/.claude/settings.json에서 해당 항목 두 개(swiftship-usage-log.sh를 참조하는 것들)도 제거해야 합니다. 이들이 가리키는 스크립트는 사라졌고 플러그인이 자체 복사본을 등록했기 때문에, 이를 남겨두면 모든 프롬프트마다 훅 오류가 발생하고 중복 기록이 됩니다.
수동 설치 (기여자 / 개발용)
처음부터 시작하려면 세 개의 명령어가 필요합니다:
git clone https://github.com/rshankras/claude-code-apple-skills.git
git clone https://github.com/rshankras/SwiftShip.git
cd SwiftShip && ./install.sh
그런 다음 앱 프로젝트에서 새로운 Claude Code 세션을 시작하고(명령어와 에이전트는 세션 시작 시 로드됨) /apple:help를 실행하세요.
설치 프로그램은 다음 순서로 스킬 라이브러리가 어디에 있는지 파악하므로, 수정 없이 어떤 기기에서도 작동합니다:
./install.sh
./install.sh /path/to/claude-code-apple-skills
SWIFTSHIP_SKILLS_DIR=/path/to/claude-code-apple-skills ./install.sh
이는 `~/.claude/` 내에 **홈 디렉토리 기준 심볼릭 링크(home‑relative symlinks)**를 생성하여, 어떤 프로젝트에서든, 어떤 사용자 계정에서든 명령어들이 작동하도록 합니다:
| 심볼릭 링크 | 가리키는 대상 |
|---|---|
| `~/.claude/commands/apple` | 이 저장소의 `commands/` (애플(apple)으로 연결되어 `/apple:*` 접두사가 유지됨) |
| ... |
모든 것이 `~/...` 경로를 통해 참조되기 때문에 (이는 사용자별로 확장되므로), **수정해야 할 기계 특정 절대 경로는 없습니다**. 스킬 라이브러리를 이동할 때마다 `./install.sh`를 다시 실행하십시오. (개별 파일 에이전트 연결 이전에 설치된 내용은 다음 실행 시 자동으로 마이그레이션됩니다.)
**Stable vs dev:** `main`은 개발 채널입니다. 안정적인 설치가 필요하면, 설치 프로그램을 실행하기 전에 최신 태그(`git checkout v1.0.0`)를 확인하십시오 — [CHANGELOG.md](CHANGELOG.md)와 [Releases](https://github.com/rshankras/SwiftShip/releases)를 참조하세요.
```bash
cd /path/to/claude-code-apple-skills && git pull
cd /path/to/SwiftShip && git pull && ./install.sh
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
심볼릭 링크는 체크아웃된 내용을 추적하므로, 대부분의 업데이트에는 git pull만 필요합니다. install.sh를 다시 실행하는 것은 아무 비용도 들지 않으며 파일을 추가하는 릴리스까지 처리해줍니다. 변경 사항을 로드하려면 Claude Code 세션을 재시작하십시오.
제거(Uninstall)
SwiftShip의 심볼릭 링크만 제거합니다. 사용자의 에이전트, settings.json, 사용 기록 장부(usage ledger), 그리고 모든 프로젝트의 .planning/ 파일은 손대지 않습니다.
선택 사항: 로컬 사용 로그(Optional: local usage log)
SwiftShip은 어떤 명령어를 실행했고 어떻게 진행되었는지에 대한 로컬 전용 기록(~/.claude/swiftship-usage.jsonl)을 유지할 수 있습니다. 이는 워크플로우가 어디서 멈추고 각 명령어가 실제로 비용이 얼마나 드는지를 파악하는 데 유용합니다. 워크플로우 명령어는 완료 시 한 줄의 결과값을 추가합니다. 완전한 기록을 위해서는 `
⚠️ [IMG:N] 형식 토큰은 이미지 placeholder 입니다. 번역하지 말고 원래 위치에 그대로 유지하세요.
"UserPromptSubmit": [{"hooks": [{"type": "command", "command": "~/.claude/hooks/swiftship-usage-log.sh"}]}],
"PostToolUse": [{"matcher": "Skill", "hooks": [{"type": "command", "command": "~/.claude/hooks/swiftship-usage-log.sh"}]]}
(UserPromptSubmit은 사용자가 직접 입력하는 명령어를 클라이언트 측에서 확장할 때 포착하며, PostToolUse는 Skill 도구를 통해 호출되는 명령어를 포착합니다 — Claude가 스스로 호출하거나, 사용자가 입력한 명령을 Skill을 통해 라우팅하는 하네스 버전을 통해서입니다. 각 호출은 정확히 하나의 항목과 일치하며, 로그에는 해당 호출이 via: "typed" | "skill" 중 어느 경로로 이루어졌는지 기록됩니다.)
어떤 데이터도 사용자의 기기를 벗어나지 않습니다 — 분석 서비스나 전화 홈(phone-home) 기능이 없습니다. 이 로그는 타임스탬프, 명령어 이름, 횟수, 세션 모델, 그리고 각 명령어가 어떻게 호출되었는지(직접 입력 vs Skill 라우팅)만을 기록합니다. 언제든지 파일을 삭제하거나 후크를 건너뛸 수 있습니다.
데이터가 쌓이면 **/apple:usage**를 실행하여 보고서를 확인할 수 있습니다. 어떤 명령어를 실행했는지, 그 결과가 어떠했는지, 어느 단계에서 작업이 멈췄는지, 그리고 각 명령어가 적절해야 할 모델 등급(model tier)에서 실행되었는지를 알 수 있습니다.
선택 사항: 권한 프롬프트 감소 (Optional: fewer permission prompts)
Claude Code가 모든 읽기 작업에 대해 권한을 요청하지 않도록 하려면, ~/.claude/settings.json 파일에 일반적이고 안전한 명령어들을 미리 허용할 수 있습니다:
{
"permissions": {
"allow": [
...
또는 /fewer-permission-prompts Skill을 사용하여 Claude Code가 이 설정을 자동으로 처리하도록 할 수도 있습니다.
빠른 시작 (Quick start)
/apple:validate "집중 및 수분 공급을 위한 메뉴 바 앱"
...
새로운 앱에 SwiftShip 사용하기 (Using SwiftShip on a new app)
이것이 주요한, 엔드-투-엔드(end-to-end) 흐름입니다. 각 단계는 .planning/ 폴더 안에 파일을 작성하여 아무것도 빠뜨리지 않도록 합니다.
-
아이디어 검증 — /apple:validate "당신의 아이디어"
Claude가 시장 규모, 경쟁사, 기능 격차(feature gaps), 수익 잠재력을 조사하고 GO / PIVOT / NO-GO 중 하나의 추천을 제공합니다. 아무도 원하지 않는 것을 만드는 실수를 막아줍니다. → .planning/VALIDATION.md
-
앱 정의 — /apple:new-app MyApp
안내 인터뷰를 통해 플랫폼(iOS/macOS/둘 다), 해결하려는 문제, 대상 사용자, 핵심 기능, 수익 모델, 필요한 Apple 프레임워크 등을 파악합니다. → .planning/APP.md (+ 프로젝트 CLAUDE.md)
-
로드맵 생성 — /apple:roadmap
명세(spec)를 다음 7단계로 전환합니다: Foundation (기초) → Core Features (핵심 기능) → Polish & Platform Features (다듬기 및 플랫폼 기능) → Monetization (수익화) → Quality & Testing (품질 및 테스트) → Pre‑Release (출시 전) → Submission (제출). → .planning/ROADMAP.md, STATE.md
-
(선택 사항) 환경 설정 — /apple:discuss [phase]
계획을 세우기 전에 Claude는 사용자가 선호하는 작업 방식(아키텍처 (MVVM 등), 네비게이션, 오류 처리, 테스트 깊이)에 대해 질문합니다. 이러한 선택은 기억되어 계획 및 빌드 과정에서 자동으로 적용됩니다. → .planning/PREFERENCES.md
-
(선택 사항) 까다로운 API 위험 제거 — /apple:spike "topic"
Apple은 매년 새로운 API를 출시하며, 대부분 OS 버전과 장치에 따라 제한됩니다. *스파이크(spike)*는 계획에 커밋하기 전에 "이것이 실제로 내 최소 OS/이 장치에서 작동하는가?"라는 질문에 답하는 빠르고 일회성 실험입니다. → .planning/spikes/...
-
단계 계획 — /apple:plan 1
특정 단계를 구체적인 작업들로 분해하며, 각 작업은 auto(Claude가 전문가와 함께 수행), generator(준비된 코드 레시피 사용), 또는 manual(사용자가 직접 수행, 예: Xcode 프로젝트 생성) 태그가 지정됩니다. → .planning/PLAN.md
-
단계 빌드 — /apple:build
작업 목록을 따라 진행합니다: 적절한 전문가 에이전트를 투입하고, 코드를 작성하며, 검사를 실행하고, 각 작업 후 커밋하며, 프로젝트의 메모리를 업데이트합니다. 마지막에는 자동으로 품질 게이트(quality gate)를 실행합니다.
-
작동 확인 — /apple:verify
기능이 실제로 작동하는지 확인합니다(빌드, 테스트를 수행하며, 지원되는 도구가 연결된 경우 실행 중인 앱을 실행하고 스크린샷을 찍어 검토할 수 있습니다). → .planning/VERIFICATION.md
