pilot-shell (Claude Skill) — インストール & ライブデモ

なぜ使うのか

主な機能

計画 → 仕様 → 実装 → 検証のパイプラインをデフォルトのループとして提供
品質ゲート：lint・型・テスト・ドキュメントの存在を全て強制
プロジェクト知識ファイルを自動的に維持
受け入れ基準ファースト。コードより前にテストを書く
新しいツールを強制することなく 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 を出さないようにする

👤 lint・型エラーで PR が頻繁にはじかれる開発者 ⏱ ~30 min intermediate

使うタイミング： 今週 3 件の PR を開いたが、全て基本的なことで CI に落とされたとき。

フロー

ゲートを設定する

Use pilot-shell. Configure quality gates to mirror our CI: eslint, tsc, vitest, prettier.✓ コピーしました

→ ゲートが記載された .pilot.config.json が作成される
赤では PR を開かない

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 トークン。知識ファイルは管理しやすい規模で約 3000 が上限
金額: 無料
ヒント: knowledge.md を約 3000 トークン以内に収める。古いエントリを定期的に統合する

セキュリティ

権限、シークレット、影響範囲

最小スコープ： 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 スキルではなくクロスツール対応の MCP サーバーとして使いたいとき	セットアップが多い。デプロイの柔軟性が高い
Plain CLAUDE.md + manual TDD	個人プロジェクトで自動化が不要な場合	規律に依存する。ガードレールが少ない

その他

リソース

📖 GitHub の公式 README を読む

🐙 オープンな issue を見る

🔍 400以上のMCPサーバーとSkillsを見る