pilot-shell (Claude Skill) — 설치 & 라이브 데모

왜 쓰나요

핵심 기능

계획 → 스펙 → 구현 → 검증 파이프라인이 기본 루프
품질 게이트: lint, type, test, doc 존재 여부 모두 적용
프로젝트 지식 파일 자동 유지
수락 기준 우선; 코드 전에 테스트 작성
새 도구 없이 Claude Code 워크플로우에 통합

라이브 데모

실제 사용 모습

준비됨

설치

작성자 저장소 · Claude Skills 공식 문서

사용 사례

실전 활용법: pilot-shell

스펙 우선 원칙으로 기능 구현

👤 반쪽짜리 AI 작성 기능에 지친 개발자 ⏱ ~90 min intermediate

언제 쓸까: PM으로부터 모호한 기능 요청; 빠른 것이 아닌 제대로 구현하고 싶을 때.

흐름

계획

Use pilot-shell. Plan the feature 'export usage CSV per workspace per month'. List unknowns + risks.✓ 복사됨

→ 명시적 미지사항이 있는 계획; 다음 단계 전에 공백을 채움
스펙

From the plan, write a spec with acceptance criteria + non-goals + edge cases.✓ 복사됨

→ /specs/<feature>.md에 스펙 저장됨
구현

Implement against the spec. Tests first, then code. Stop at any unmet criterion.✓ 복사됨

→ 테스트 + 구현; 구현이 통과될 때까지 실패하는 테스트 표시
게이트 검증

Run all gates: lint, type, tests, docs. Block PR if any red.✓ 복사됨

→ 게이트 보고서; 모두 녹색만 병합 후보

결과: 테스트와 문서가 있는 스펙 완성 기능 구현.

함정

스펙이 계획 마라톤으로 늘어짐 — 스펙 단계를 30분으로 시간 제한; 완벽한 스펙 대신 수락 기준을 잠그는 최소 스펙 구현

함께 쓰기: filesystem

첫 실행에서 CI가 실패하는 PR 열기 멈추기

👤 PR이 lint/type 오류로 자주 반려되는 개발자 ⏱ ~30 min intermediate

언제 쓸까: 이번 주 PR을 3개 열었는데 모두 기본적인 CI에서 실패했을 때.

흐름

게이트 설정

Use pilot-shell. Configure quality gates to mirror our CI: eslint, tsc, vitest, prettier.✓ 복사됨

→ 게이트가 나열된 .pilot.config.json
빨간 불 차단

Set policy: don't open PR until all gates green locally.✓ 복사됨

→ 정책 적용됨
측정

After 2 weeks, compare CI first-run pass rate before/after.✓ 복사됨

→ 통과율 향상

결과: CI를 첫 번에 통과하는 PR; 리뷰어를 위한 덜한 반복.

함정

로컬 게이트가 CI와 미묘하게 다름 (Node 버전) — .nvmrc로 로컬 Node 버전 고정; CI의 정확한 명령 미러링

함께 쓰기: github

팀이 성장하면서 프로젝트 지식 보존

👤 새로운 협력자를 온보딩하는 프로젝트 소유자 ⏱ ~30 min beginner

언제 쓸까: 프로젝트를 인계/공유하면서 결정과 불변 조건을 캡처하고 싶을 때.

흐름

지식 파일 초기화

Use pilot-shell. Initialize project knowledge with: architecture, key invariants, decisions log.✓ 복사됨

→ 섹션이 있는 /.pilot/knowledge.md 생성됨
진행하면서 캡처

Whenever a decision is made (chose Postgres over MySQL), record with date + reason.✓ 복사됨

→ 결정이 축적됨; 새 협력자가 히스토리를 읽을 수 있음
온보딩에 활용

When a new collaborator starts, point Claude Code to this file as primary context.✓ 복사됨

→ 더 빠른 적응; '왜 이렇게 됐어요?'가 줄어듦

결과: 팀 변경에서도 지식이 살아남음.

함정

지식 파일이 사소한 내용의 일지가 됨 — 간결하게 유지: 불변 조건, 결정, 주의 사항. 일일 로그 아님

조합

다른 MCP와 조합해 10배 효율

pilot-shell-skill + github

스펙에서 자동으로 채워진 PR 템플릿; CI가 게이트 검증

When opening a PR, populate the body from the spec markdown; CI checks gates match.✓ 복사됨

pilot-shell-skill + filesystem

저장소에 스펙과 지식 커밋

Persist /specs/ and /.pilot/knowledge.md in repo for review history.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출
plan	feature_description	모든 새 기능의 1단계
spec	plan_id	계획의 미지사항 해결 후
implement	spec_id	스펙 승인 후
run_gates	scope?	PR 전; CI 미러
knowledge_update	decision_or_invariant	프로젝트 수준의 결정 캡처

비용 및 제한

운영 비용

API 쿼터: 없음 — 로컬
호출당 토큰: 스펙 문서 약 500–2000 token; 지식 파일은 관리 가능하도록 약 3000 상한
금액: 무료
팁: knowledge.md를 약 3000 token으로 제한; 오래된 항목을 주기적으로 통합

보안

권한, 시크릿, 파급범위

최소 스코프: filesystem-write

자격 증명 저장: 없음

데이터 외부 송신: 없음

스펙에 민감한 제품 세부 정보가 담길 수 있음 — 비공개라면 /specs/를 gitignore

문제 해결

자주 발생하는 오류와 해결

게이트가 로컬에서는 통과하지만 CI에서 실패

Node 버전, OS별 의존성 고정; CI 명령을 정확하게 미러링

확인: Diff local vs CI command output

구현 단계가 테스트 우선을 건너뜀

.pilot.config에서 strict_tdd=true 설정; 테스트 전에 구현 작성을 거부함

스펙 단계가 늘어짐

--time-box 30m 사용; 완벽한 스펙 대신 미지사항에 대한 결정을 강제

지식 파일이 너무 길어짐

knowledge_consolidate 실행; 오래된 항목을 /.pilot/archive/로 보관

대안

pilot-shell 다른 것과 비교

대안	언제 쓰나	단점/장점
spec-workflow-mcp	Claude Code skill이 아닌 크로스 도구 범위의 MCP 서버로 원할 때	더 많은 설정; 더 유연한 배포
Plain CLAUDE.md + manual TDD	솔로 프로젝트, 자동화가 필요 없을 때	규율에 의존; 가드레일 적음

pilot-shell