cli-builder

CLI ビルダー

あらゆるモジュールやアプリケーション向けに、あらゆる言語で本番品質の CLI ツールを構築します。

参照ファイル（エージェントのコンテキスト予算を抑えるため、先にまとめて読むのではなく、必要に応じて各ファイルを読みます）：

• references/cli-libraries.md — Step 2（設計）でライブラリを推奨する際と、Step 4（実行）でスターターのスキャフォールドを用意する際に読みます
• references/btop-style.md — Step 2（設計）で「ビジュアルスタイル」セクションを作成する際と、Step 4（実行）でスタイルモジュールとそのテストを構築する際に読みます
• references/testing-patterns.md — Step 4（実行）でテストを作成する際に読みます
• references/final-report.md — Step 5（要約）で最終レポートを作成する際に読みます

編集前のリポジトリ同期（必須）

Step 1 の前にこのセクションを一度実行し、分析時に最新のコードを読み込んでください。git rev-parse --git-dir が失敗した場合、このディレクトリは Git リポジトリではありません。その場合は、このセクション、ブランチ優先の安全ルール、Step 4 のコミットを省略し、最終レポートの Uncertainty: に no git repository: no branch or commits と記載してください。

Git リポジトリの場合は、現在のブランチをリモートと同期します。

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

作業ツリーがクリーンでない場合は、先に stash してから同期し、その後復元します。

git stash push -u -m "pre-sync"
branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin && git pull --rebase origin "$branch"
git stash pop

origin がない、pull を利用できない、または rebase／stash の競合が発生した場合は、そこで中断し、続行する前にユーザーに確認してください。

ブランチ優先の安全ルール

Step 4 の開始時、最初にファイルを書き込む前に、このルールを実行し、CLI_NAME には Step 2 で承認されたツール名を設定してください。新しいブランチを作成するのは main または master にいる場合だけです。それ以外の場合は、既存のブランチで続行してください（ユーザーがすでにブランチを用意しているか、作業を再開している可能性があります）。

current_branch="$(git rev-parse --abbrev-ref HEAD)"
if [ "$current_branch" = "main" ] || [ "$current_branch" = "master" ]; then
  slug="$(echo "${CLI_NAME:-cli}" | tr '[:upper:] ' '[:lower:]-' | tr -cd 'a-z0-9-')"
  ts="$(date +%Y%m%d-%H%M%S)"
  git checkout -b "feat/cli-${slug}-${ts}"
fi

必須の 5 ステップワークフロー（承認制）

明示的な承認とは、提示された内容をそのまま受け入れるユーザーの返信です。たとえば「承認します」や「問題ありません。進めてください」などです。質問、変更依頼、返信がないことは承認ではありません。Step 1〜3 ではファイルを書き込みません。

Step 1：分析

何かを提案する前に、プロジェクトを理解します。

マニフェストファイルを確認して言語を自動検出します：

• package.json／tsconfig.json -> JavaScript／TypeScript
• pyproject.toml／setup.py／setup.cfg／requirements.txt -> Python
• go.mod -> Go
• Cargo.toml -> Rust
• pom.xml／build.gradle／build.gradle.kts -> Java／Kotlin
• Gemfile／*.gemspec -> Ruby

既存の CLI／エントリーポイントを特定します：bin フィールド、__main__.py、main.go、fn main()、既存の引数解析コード、または package.json の scripts を確認します。

モジュール構成を記録します：CLI が公開する関数またはクラス、その入出力、コアデータ型、実行時の依存関係を一覧にします。

確認の質問をします（推測できないことだけを尋ねます）：

• 主な用途（自動化、開発者向けツール、データ処理、管理）
• 対象ユーザー（開発者、運用担当者、エンドユーザー）
• 単一コマンドか複数コマンドか（サブコマンドツリー）
• 必要な出力形式（テキスト、JSON、テーブル、CSV）
• 配布方法（pip／npm／go install、スタンドアロンバイナリ、ソース）

検出した言語、エントリーポイント、公開する関数の一覧、未解決の質問を提示します。Step 2 に進む前に、明示的な承認を待ちます。

---

ステップ 2：設計

構成を整理した CLI 設計ドキュメントを提示します。

• ツール名とバイナリ／エントリーポイント名
• コマンドツリー（複数コマンドのツールの場合は階層を図示）
• 各コマンドの引数とオプション（名前、型、必須／任意、デフォルト値、ヘルプテキスト）
• グローバルオプション（verbose、quiet、出力形式、設定ファイル、no-color）
• I/O 動作（標準入力のサポート、stdout／stderr の分離、パイプ処理）
• 設定の優先順位（CLI 引数 > 環境変数 > 設定ファイル > デフォルト値）
• 実行例（一般的なユースケースを示す、現実的な例を少なくとも 3 つ）
• ビジュアルスタイル（すべての設計で必須）— references/btop-style.md にある btop に着想を得たスタイル：コマンドごとのコンポーネント、テーマの役割、フォールバック、スタイリングライブラリまたは依存関係ゼロのモジュール、スタイルを適用したコマンド出力のモックアップ。ユーザーがこのスタイルを明示的に拒否した場合に限り、別のスタイルを使用します。

承認の手順：

1. 設計ドキュメントを提示します。
2. フィードバックを求めます。
3. 返答が明示的な承認でない場合は設計を修正し、1 に戻ります。

設計の承認前に実装してはいけません。 ユーザーが設計を承認せずに実行を終了した場合は停止し、最終ステータスを BLOCKED とします。

---

ステップ 3：計画

実装を、詳細なタスクを含む 3 つのフェーズに分けます。

フェーズ 1 — 基盤（動作する CLI の骨組みを作成）：

• エントリーポイントと引数解析の設定
• 主要なコマンドを 1 つ（最も重要なもの）
• ヘルプテキストとバージョンフラグ
• 基本テスト（ヘルプ出力、バージョン、コマンド 1 つ）

フェーズ 2 — 完成（全機能を実装）：

• 残りのすべてのコマンド
• 入力検証とエラー処理
• 承認済みのビジュアルスタイルに従う 1 つのスタイルモジュールを通じた出力形式（設計どおりのテキスト、JSON、テーブル）
• 包括的なテスト

フェーズ 3 — 仕上げ（任意。ユーザーが確認した場合のみ含めます）：

• 設定ファイルのサポート
• 環境変数によるオーバーライド
• シェル補完（bash、zsh、fish）
• 配布／パッケージ設定（setup.py、package.json bin、goreleaser など）

各タスクには以下を含めます。

• 目標：1 文
• ファイル：作成または変更するファイル
• 期待される動作：このタスクの完了後にユーザーができること
• テスト：検証方法
• 工数：S／M／L

計画にも、ステップ 2 と同じ承認の手順を使用します。

計画の承認前に実行してはいけません。 ユーザーが計画を承認せずに実行を終了した場合は停止し、最終ステータスを BLOCKED とします。

---

ステップ 4：実行

最初にファイルを書き込む前に、Branch-First Safety Rule を適用します。その後、承認済みの計画に含まれる各タスクについて、次の手順を実行します。

1. タスクを実装します。
2. マニフェストに記載されているプロジェクトのテストコマンドを実行します（例：pytest、npm test、go test ./...、cargo test）。
3. テストが失敗した場合はコードを修正し、テストコマンドを再実行します。同じタスクで修正を 3 回試みても失敗する場合は、ステップ 4 を停止し、失敗した出力を提示してユーザーに対処方法を尋ねます。テストが失敗している間は、次のタスクを開始しないでください。
4. テストコマンドを実行できない場合（必要なツールチェーンまたはテストランナーがない場合）は、その旨をユーザーに伝えます。明示的な承認を得た後にのみ続行し、そのタスクのテストは not run と記録します。

各フェーズの終了時：

5. デモ（--help と、承認済みの実行例を少なくとも 1 つ）を実行し、出力を提示します。フェーズ 2 以降では、ユーザーが btop スタイルを拒否していない限り（references/btop-style.md → Verify）、FORCE_COLOR=1 を指定した実行例も 1 つ実行します。デモがゼロ以外の終了コードで終了した場合は、テスト失敗として扱います（項目 3）。
6. git リポジトリの場合、このフェーズで作成または変更したファイルのみをステージし、内容が分かるコミットメッセージを付けてコミットします。

タスクのために承認済みの設計を変更する必要がある場合（コマンド、オプション、出力形式が異なる場合）は、ステップ 4 を停止します。変更案を提示し、続行する前に明示的な承認を待ちます。

ステップ 5：要約

最後のステップ完了レポートの後に、最終レポートをプレーンテキストでチャットに一度だけ出力してください。ユーザーから依頼がない限り、レポートファイルは作成しないでください。各項目の内容、ステータスのルール、2 つの例については references/final-report.md を読んでください。4 つの項目は次の順序で記載します。

1. Result: — 最初にステータス（COMPLETE、PARTIAL — <reason>、または BLOCKED — <reason>）を記載し、次にツール名を記載します。
2. Evidence: — 実行したチェックのみ記載します。ファイル、テスト数、デモの終了コードが対象です。
3. Uncertainty: — 未テストの動作と前提を、確認済みの事実とは分けて記載します。
4. Decision: — 必要な承認、または No approval needed. を記載し、その後に残っているユーザーの作業をそれぞれ記載します。

4 つの項目の後に、使用方法のクイックスタート（インストールコマンドと 3～5 個の実行例）および次のステップ（改善案、不足している機能、配布に関する TODO）を記載します。

ステータスのルール — 最初に該当するルールを適用します。

1. BLOCKED — たとえば、設計や計画が承認されなかった、ラップするモジュールがなくユーザーから回答もなかった、または Repo Sync で競合や origin の不足が発生し、ユーザーが回避策を承認しなかったなど、最初のファイル書き込み前に実行が停止した場合。
2. PARTIAL — 少なくとも 1 つのファイルを書き込んだ後、次のいずれかが発生した場合：テストまたはデモが失敗したまま、テストコマンドを実行できなかった、ユーザーがステップ 4 を途中で終了した、承認されたタスクが未完了、または設計変更の承認待ち。
3. COMPLETE — 承認された計画のすべてのタスクが完了し、すべてのテストコマンドとデモが実行され、成功した場合。ユーザーがフェーズ 3 を辞退しても、実行は部分完了にはなりません。

期待される出力

このスキルを mylib という Python モジュールで実行した場合、最終レポートは次のようになります（完全な例：references/final-report.md）。

Result: COMPLETE — mylib CLI (Python, click) with subcommands run and info
Evidence:
  Branch: feat/cli-mylib-20260419-143200
  Created: cli/main.py, cli/commands/run.py, cli/commands/info.py, tests/test_cli.py
  Modified: pyproject.toml ([project.scripts] entry point)
  pytest: 8 passed, 0 failed
  Visual style: btop, rich
  Demo: mylib --help, mylib --version, mylib info, env -u NO_COLOR FORCE_COLOR=1 mylib info (all exit 0)
Uncertainty:
  Tested on macOS only. Styled output not viewed in a real terminal; light-background terminal not tried.
  Shell completions not built (Phase 3 declined).
Decision: No approval needed.
  Remaining action: review the branch and push it.

Usage quick-start:
  pip install -e .
  mylib --help
  mylib run --input data.csv --output results.json
  mylib info --format json

ステップ完了レポート（ステップ 4～5）：

◆ Execute + Summarize (step 4-5 of 5 — mylib CLI)
··································································
  Implementation:         √ pass (2 subcommands, 4 files created)
  Test coverage:          √ pass (8/8 tests passing)
  Phase demos completed:  √ pass (help, version, run verified)
  Final report delivered: √ pass
  Criteria:               √ 4/4 met
  ____________________________
  Result:                 PASS

エッジケース

• ラップするモジュールが明確でない場合：分析に進む前に、CLI で公開する関数や機能をユーザーに尋ねてください。
• 複数の言語が検出された場合：選択肢を提示し、CLI 関連の既存コードが最も多い言語を推奨してください。
• 既存の CLI が見つかった場合：作り直すのではなく、拡張またはリファクタリングを提案してください。まず既存の実装を監査します。
• 既存の CLI に独自のビジュアルスタイルがある場合：設計には btop スタイルも提示し、現在の出力との違いを列挙したうえで、設計承認時にユーザーが選べるようにしてください。
• ライブ更新される btop のような表示を求められた場合：ステップ 1 で、全画面のライブ表示は TUI であり、このスキルでは構築しないことを伝え、追記専用の出力（references/btop-style.md）を提案してください。
• 多数のパッケージを含むモノレポの場合：どのパッケージまたはサービスに CLI を追加するかを尋ね、分析の範囲をそのサブツリーに限定してください。
• テストフレームワークがない場合：フェーズ 1 の基盤タスクの一環として、最小限のテスト環境（pytest、jest、go test）を追加してください。
• バイナリー出力（スタンドアロンの .exe／コンパイル済み）が必要な場合：設計フェーズで配布方法に触れ、フェーズ 3 の仕上げにビルド手順（PyInstaller、pkg、goreleaser）を追加してください。
• ユーザーが設計を承認し、実装を拒否した場合：設計フェーズに戻ってください。却下された方法で黙って作業を進めないでください。

受け入れ基準

• 確認質問をする前に、マニフェストファイルから言語が自動検出される
• 実装を開始する前に、CLI の設計ドキュメントが提示され、明示的な承認を得る
• 実行を開始する前に、実装計画が提示され、明示的な承認を得る
• すべてのコマンド階層で --help が機能し、--version が実装されている
• 終了コードが references/testing-patterns.md の標準表に従っている
• エラーメッセージは stderr に出力され、クリーンな出力は stdout に出力される（パイプで利用可能）
• NO_COLOR 環境変数または --no-color フラグが尊重される
• ターミナル出力が承認済みのビジュアルスタイルに従い、--format json、パイプ出力、および NO_COLOR の出力に ESC（0x1b）バイトが含まれない
• 次のフェーズに進む前にテストが作成され、合格している
• 最終レポートにインストールコマンドと3つ以上の使用例が含まれている
• 最終レポートは Result: と Step 5 のステータスルールに基づいて選ばれたステータスで始まり、その後に Evidence:、Uncertainty:、Decision: が続く
• 読者が結果を確認し、検証済みのチェック項目と仮定を区別し、各主張をファイルまたはコマンドまでたどり、次の判断事項を確認できる（読者向けチェック項目は references/final-report.md を参照）。ユーザーがそれらのチェック項目に回答するまでは、人間による理解は未確認のままとする

ステップ完了レポート

各主要ステップの完了後、次の形式でステータスレポートを出力してください。

◆ [Step Name] ([step N of M] — [context])
··································································
  [Check 1]:          √ pass
  [Check 2]:          √ pass (note if relevant)
  [Check 3]:          × fail — [reason]
  [Check 4]:          √ pass
  [Criteria]:         √ N/M met
  ____________________________
  Result:             PASS | FAIL | PARTIAL

チェック項目名は、そのステップで実際に検証する内容に合わせてください。合格には √、不合格には × を使用し、簡単な補足には — を使用してください。「Criteria」行には、達成した受け入れ基準の数を要約します。「Result」行には、総合判定を記載します。

フェーズごとのスキル固有のチェック項目

フェーズ：分析（Step 1） — チェック項目：Project analysis、Language detected、Entry points identified、Clarifying questions asked

フェーズ：設計（Step 2） — チェック項目：Design approval、Command tree defined、I/O behavior specified、Example invocations provided、Visual style defined

フェーズ：計画（Step 3） — チェック項目：Plan approval、Phases broken down、Tasks have goals and tests、Effort estimated

フェーズ：実行＋要約（Steps 4–5） — チェック項目：Implementation、Test coverage、Phase demos completed、Final report delivered

エラー処理

状況	対応
ラップする明確なモジュールがない	CLI でどの機能を公開するべきかユーザーに尋ねる
複数の言語が検出された	使用する言語をユーザーに尋ね、CLI コードがより多い言語を推奨する
既存の CLI が見つかった	作り直すのではなく、拡張またはリファクタリングを提案する。まず既存の CLI を監査する
要求されたフレームワークが不明	フレームワークの公式ドキュメントを読む。アクセスできるドキュメントがない場合は、ドキュメントへのリンクをユーザーに尋ねる
実装後にテストが失敗した	修正して再実行する。失敗したテストを決してスキップしない。1つのタスクで3回失敗したら中止してユーザーに尋ねる（Step 4）
テストコマンドを実行できない	ユーザーに伝える。明示的な承認を得てから続行し、テストを not run（ステータス PARTIAL）として記録する
git リポジトリではない	Repo Sync、ブランチルール、コミットを省略し、Uncertainty: に記載する

品質ガードレール

このスキルで構築するすべての CLI には、次の項目を含める必要があります。

• ヘルプテキスト：すべてのコマンドとオプションに説明がある（すべての階層で --help が機能する）
• エラーメッセージ：stderr に出力し、何が問題だったのかと修正方法を含める
• 終了コード：references/testing-patterns.md の標準表に従う（0 = 成功、0 以外 = 失敗）
• POSIX 規約：--long-flag、短いフラグは -s、オプションの終了には -- を使用する
• パイプで利用可能な I/O：適切な場合は stdin をサポートし、パイプ用にクリーンな stdout を出力する
• 色なしのサポート：NO_COLOR 環境変数または --no-color フラグを尊重する
• バージョンフラグ：--version でバージョンを表示して終了する