maxritter/pilot-shell

How real engineers run Claude Code and Codex: spec-driven planning, enforced TDD, persistent memory, and quality enforcement on all levels. Make your agents production-ready.

Pilot Shell – Claude Code 및 Codex용 AI 보강 명령줄

무엇인가요 – Anthropic의 Claude Code (주요) 또는 OpenAI의 Codex 위에 얇은 쉘/CLI를 설치하여 구조적이고 테스트 중심의 개발 워크플로우를 추가합니다. 원시적인 코드 생성 프롬프트를 반복 가능하고 품질 검사를 거친 파이프라인으로 전환하여 요구사항 수집, 사양 수립, 구현, 버그 수정, 자율적 빌드를 모두 커버합니다.

왜 존재하는가 – Claude Code와 Codex는 코드를 빠르게 작성할 수 있지만, 프레임워크 없이는:

테스트 및 린팅을 생략함
세션 간 컨텍스트를 잃음
결과가 일관성 없음 Pilot Shell은 사양 중심 및 목표 중심 프로세스, 품질 게이트, 지속적인 "메모리"를 주입하여 AI가 더 체계적인 엔지니어링 팀원처럼 행동하게 합니다.

핵심 개념 및 명령어

명령어	사용 시기	기능
`/prd`	모호한 아이디어나 문제 설명이 있을 때.	브레인스토밍, 선택적 웹 조사 후 `docs/prd/`에 저장된 제품 요구사항서(PRD) 생성.
`/spec`	명확한 기능이나 버그를 처리할 때.	AI에게 계획 → 승인 → 구현(TDD) → 검증 → 완료 흐름을 안내하며 자동 린팅/포맷/타입 체크 및 선택적 공동 사양 검토를 수행.
`/build`	완전한 사양 없이 구체적인 목표에 도달하고 싶을 때.	짧은 작업 목록과 수용 기준을 생성한 후 반복적으로 빌드, 평가, 개선하여 기준을 충족할 때까지 진행.
`/fix`	테스트 중심 흐름에 맞는 버그 수정이 필요할 때.	집중적인 TDD 루프 실행; 수정이 너무 복잡해지면 중단.
`pilot` (관리자 별칭)	설치, 업데이트, 설정 관리.	런타임 설치/제거, 라이선스 활성화, 모델 전환 등 수행.

주요 기능

품질 훅 – 모든 수정에 대해 자동으로 린팅, 포맷팅, 타입 체크, 테스트 실행 강제.
컨텍스트 엔지니어링 및 메모리 공유 – 결정, 규칙, "메모리"는 ~/.pilot/에 지속 저장되며 프로젝트 리포지토리로 공유 가능.
세マン틱 검색(Semble) + 코드 지식 그래프(CodeGraph) – 토큰 사용량을 줄이는 빠르고 정확한 코드베이스 검색.
토큰 최적화 – RTK 압축과 Semble 검색을 통해 비용 60–90% 절감.
Pilot Bot – 지속적인 백그라운드 에이전트로 스케줄된 작업이나 장시간 실행 작업 실행 가능.
확장 기능 – 팀이 공유할 수 있는 재사용 가능한 규칙, 기술, MCP(메시지-컨트롤-프로토콜) 서버.
콘솔 – 실시간 알림, 세션 로그, 현재 요구사항/사양을 보여주는 로컬 웹 대시보드.

설치 (빠른 시작)

# macOS, Linux, Windows(WSL2)에서 작동하는 원라인
curl -fsSL https://raw.githubusercontent.com/maxritter/pilot-shell/main/install.sh | bash

설치 프로그램은 다음 작업을 수행합니다:

Homebrew, Node, Python 3.12+, git, jq 존재 여부 확인.
지원되는 AI 에이전트(Claude Code 또는 Codex) 감지 – 미리 설치 필요.
~/.pilot/ 아래에 Pilot 자산과 에이전트별 어댑터 배포.
지원 도구(Semble, RTK, CodeGraph, Playwright, Chrome-DevTools MCP, 언어 서버 등) 설치.
bash, fish, zsh용 쉘 별칭(pilot, claude/codex 래퍼) 추가.

제거 (데이터 유지):

curl -fsSL https://raw.githubusercontent.com/maxritter/pilot-shell/main/uninstall.sh | bash

--purge-data를 추가하면 ~/.pilot/ 삭제.

사전 요구 사항

Claude Code – 네이티브 설치 프로그램 (Anthropic 구독 필요) 또는
Codex CLI / ChatGPT 데스크톱 (OpenAI 구독 필요).
최신 터미널 (Zentty 권장, iTerm2, Ghostty 등도 작동 가능).

일반적인 워크플로우 예시

# Claude Code (또는 Codex) 시작
claude                     # 또는: codex

# 1️⃣ PRD 생성
> /prd "팀 업데이트에 대한 실시간 알림 추가"

# 2️⃣ 사양으로 전환하고 구현
> /spec "팀 업데이트에 대한 실시간 알림 추가"
# – Pilot이 계획, E2E 테스트 작성, TDD로 구현, 검증, 병합까지 안내.

# 3️⃣ 나중에 빠른 수정 필요 시
> /fix "페이지 새로 고침 후 알림이 중단됨"

모든 단계는 로그에 기록되며 생성된 사양, 규칙, 메모리는 리포지토리에 저장되어 향후 재사용 가능.

누가 이득을 볼 수 있나요?

Claude Code 또는 Codex를 이미 사용하면서 체계적이고 반복 가능한 워크플로우를 원하는 소프트웨어 엔지니어.
공유 사양, 품질 게이트, AI 생성 지식을 팀원 간 지속적으로 공유하고 싶은 팀.
토큰 비용을 줄이면서도 AI 보조를 안전하고 테스트 중심으로 유지하고 싶은 솔로 개발자.

링크

문서: https://pilot-shell.com/docs
블로그: https://pilot-shell.com/blog
릴리스: https://github.com/maxritter/pilot-shell/releases
라이선스 및 활성화: pilot activate <key> (Pilot 멤버 영역에서 키 획득)