cli-design
cli-design で CLI を設計・変更・実装する手順。「〜を管理する CLI を設計して」「〜する1コマンドのツールの仕様を作って」「notes に期限の項目を足して」「note list に絞り込みのオプションを追加して」「このコマンドを消して」「この仕様をリリースして」「この設計を Go で実装して」「実装が仕様どおりか確かめて」のように、この基盤で CLI の仕様(specs/<name>/cli.json)を作る・変える・実装する依頼では、依頼の大小にかかわらず必ず使う。依頼をパターンに振り分け、生成器(make new・make command・make field)から始め、make check と完了前チェックリストで確かめてから報告する。
- License 许可
- MIT
- 最近更新
- 2026-11-07
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- cli-design
- description
- cli-design で CLI を設計・変更・実装する手順。「〜を管理する CLI を設計して」「〜する1コマンドのツールの仕様を作って」「notes に期限の項目を足して」「note list に絞り込みのオプションを追加して」「このコマンドを消して」「この仕様をリリースして」「この設計を Go で実装して」「実装が仕様どおりか確かめて」のように、この基盤で CLI の仕様(specs/<name>/cli.json)を作る・変える・実装する依頼では、依頼の大小にかかわらず必ず使う。依頼をパターンに振り分け、生成器(make new・make command・make field)から始め、make check と完了前チェックリストで確かめてから報告する。
02 资源文件 2
- 参考文档references/patterns.md12.5 KB
- 参考文档references/stdlib-mapping.md14.7 KB
03 SKILL.md 正文
cli-design の設計手順
この基盤では、CLI の「外から見える形」(コマンド、位置引数、オプション、出力、終了コード、環境変数)を、言語に依存しない仕様 specs/<name>/cli.json として設計する。実装はこの仕様と、生成されたリファレンス specs/<name>/cli.md に従って、各言語の標準ライブラリで行う。
このスキルは次の資料と一緒に使う。パスは基盤のルートからの相対パスである。
docs/design/rules.md:ルールの全文。<接頭辞>-<番号>のルールIDで参照する.claude/skills/cli-design/references/patterns.md:パターンごとの手順と、作るファイルの一覧.claude/skills/cli-design/references/stdlib-mapping.md:仕様を各言語の標準ライブラリで実装する対応表- 見本:
specs/notes/(サブコマンドを持つ CLI)、specs/count-words/(サブコマンドを持たない CLI)、tools/clispec/tests/fixtures/(見本の実装)
既存の仕様と rules.md が食い違ったら rules.md に従い、食い違いを報告に書く。
配布用のci.jsonと.ci/はZIPを検証する入口であり、設計するCLIの実装の置き場ではない(STR-01、ADR 0008)。
1. 依頼をパターンに振り分ける
| 依頼に含まれること | patterns.md の節 |
|---|---|
| 何かを記録・管理する新しい CLI(操作が2つ以上) | 1 |
| 1回の変換・集計・出力だけを行う新しい CLI(操作が1つ) | 2 |
| 既存の CLI への新しい対象(名詞)や操作(動詞)の追加 | 3 |
| 既存の対象への新しい属性(項目)の追加 | 4 |
| 既存のコマンドへの絞り込み・標準のオプション・環境変数の追加、説明の文の変更 | 5 |
| コマンド・オプション・項目の削除、名前や型の変更、必須の追加 | 6 |
| 版の確定・公開・リリース | 7 |
| 仕様の実装、実装が仕様どおりかの確認 | 8 |
| 検査ツールの Python・uv の版を上げる | 9 |
- 複数の行に当たる場合は、表の上から順に全部行う(例:項目を足して絞り込みも足す → 4 → 5)
- どの行にも当たらない場合(設定ファイル、対話の入力、色、3段のサブコマンド、ルールの変更など)は、実装しない。必要なパターンとルールを提案として報告する(PROC-04)。見本に無い形をその場で発明すると、作者ごとに違う形が生まれるからである
2. 依頼から決まらない値
推測で決めない。聞ける状況ならユーザーに聞く。聞けない状況ならこの表の既定値で決め、報告の3に書く。
| 決めること | 何に響くか | 既定値 |
|---|---|---|
| CLI 名 | name、ディレクトリ、環境変数の接頭辞 |
依頼が指定した名前。無ければ、サブコマンドを持つ CLI は依頼に最初に出る名詞の英語の複数形(notes)、持たない CLI は <動詞>-<目的語の複数形>(count-words)(NAM-02) |
| 操作が1つか2つ以上か | 構成(STR-05) | 依頼が対象を記録・管理するなら2つ以上、入力を1回変換・集計して出すだけなら1つ |
| 名詞 | path、型の名前 |
依頼の対象を表す英語の単数形の1語(bookmark)。2語の対象は主となる1語(「読書リストの本」→ book) |
| 名詞ごとの動詞 | コマンド | 依頼が「管理する」とだけ言うなら create・list・view・edit・delete の5つ。操作を列挙していれば、その操作に当たる標準の動詞だけ(NAM-04 の表)。表に無い操作は英小文字1語の動詞 |
| 識別子 | id か name |
依頼が「名前で指定する」「名前は重複しない」と書いていれば name(KEY=name)、それ以外は id |
| 項目 | 型の fields |
依頼に出る属性だけ。id・name・created_at・updated_at は生成器が足す |
| 項目の型 | TYPE= |
日付 → date(名前は <意味>_date)、日時 → timestamp(<意味>_at)、件数・番号 → integer、金額・割合 → number、はい・いいえ → boolean、依頼が選択肢を列挙した値 → enum、それ以外(URL、メモ、名前)→ string(CODE-02) |
| 項目が複数の値か | LIST=1 |
依頼が複数持つと書いた属性(タグ、ラベル)だけ。名前は複数形 |
| 項目が空を許すか | NULLABLE=1 |
依頼が「任意」「省略できる」「後で設定する」と書いた属性、または既存の CLI に足す属性で依頼が既定値を決めていないもの |
create の必須の値の既定値 |
required・default |
依頼が既定値を書いていればその値("required": false)、無ければ必須("required": true、"default": null)(NAM-07) |
| 絞り込みのオプション | list の --<項目> |
依頼が「〜で絞り込む」「〜だけを表示する」と書いた項目だけ。値が一致するものなら --<項目>、範囲(「〜以降」「〜まで」「〜より前」「期間」「〜以上」「〜以下」)なら片側だけを求められても --<項目>-from と --<項目>-to の2つ組(date・integer・number の項目だけ。NAM-07) |
| 件数の上限と並び順 | list の --limit・--sort |
生成器が足す値のまま(20、識別子の順) |
| 確認が要る操作 | -f/--force |
一度に複数件を消す・変える操作にだけ付ける。1件の delete には付けない(STATE-01) |
| 環境変数 | env |
データの置き場(生成器が足す)だけ。オプションの既定値を変える環境変数は、依頼が求めたときだけ |
| サブコマンドを持たない CLI の入出力 | 位置引数、-o/--output |
読むファイルは file 型の位置引数 file(複数なら variadic)。依頼が結果をファイルに書くことを求めたときだけ -o/--output を置き、求めていなければ stdout に書く。- は stdin・stdout |
| サブコマンドを持たない CLI の出力の型の名前 | types |
1行が表すものを snake_case で(単語の出現回数の行なら word_count) |
| 自由な summary | ヘルプの文面 | 英語の1文。大文字で始め、ピリオドを付けず、既定値・選択肢を書かない(CODE-04、CODE-05) |
| 版 | version |
新しい CLI は 1.0.0。変更したら make fix が決める(PROC-06) |
3. 書く前に読む
-
patterns.md の該当する節を最後まで読む
-
rules.md のうち、次の表の接頭辞の節をすべて読む
パターン 読む接頭辞 1、2 STR、NAM、CODE、ERR、STATE、OPS 3、4、5 NAM、CODE、ERR、STATE、PROC 6、7 STR、PROC 8 DEP、ERR、OPS、STATE、TEST 9 PROC、TOOL -
見本の該当ファイル(patterns.md の「見本」)を開き、キーの書き方・summary の文・オプションの組を確かめる
4. 作る順序
PROC-01 の順で作る。生成器を使わずに cli.json を白紙から書かない(STR-02)。
- 依頼から、CLI 名・名詞・動詞・項目を2節の表で書き出す
make new NAME=<name>(操作が1つならSINGLE=1)- 名詞ごとに
make command NAME=<name> NOUN=<名詞> VERB=<動詞>(識別子がnameなら最初にKEY=name) - 名詞ごとに
make field NAME=<name> NOUN=<名詞> FIELD=<項目名> TYPE=<型>(LIST=1・NULLABLE=1・VALUES=a,b) cli.jsonのTODOを埋め、依頼の既定値・絞り込み・標準のオプションを足す- 環境変数を STATE-01 で足す(必要なときだけ)
make fix(整形、版、cli.mdの生成)make check
cli.json を編集して保存するたびに、hooks が make after-edit で整形・版・cli.md の生成・その仕様の検査を回す(TOOL-02)。指摘が出たら、次の編集に進む前に直す。
5. 検証する
-
make checkを実行する -
落ちたら、エラーの先頭のルールID(
NAM-07 specs/notes/cli.json:42 ...)を rules.md で引き、cli.jsonを直す。エラー文に期待する値が書いてあれば、その値にする -
次の方法で検査を黙らせない(TOOL-03)
- 検査ツール(
tools/)、Makefile、.foundation/、docs/design/rules.mdなどの保護ファイルを変える - 仕様に表に無いキー(
x-、_、$comment)を書く - Python に抑止コメント(
# noqaなど)やテストの skip を書く
どうしても直せない場合は、その状態のまま報告する
- 検査ツール(
-
実装の依頼(パターン 8)では、
make conform SPEC=specs/<name>/cli.json CMD="<起動コマンドの絶対パス>"を全項目通す(TEST-01)
6. 完了前チェックリスト
該当するファイルを開き、1つずつ確かめる。
- [ ] 依頼文の操作・対象・属性・絞り込みの1つ1つが、
cli.jsonのコマンド・型・項目・オプションにある。依頼に無いものを足していない - [ ]
cli.jsonにTODOが残っていない(STR-02) - [ ]
cli.mdをmake fixで作り直し、手で直していない(STR-04)。released/のファイルを変えていない - [ ]
versionがmake fixの書いた値である。メジャーを上げた場合は、ユーザーの承認を書いた ADR が同じ変更にある(PROC-06) - [ ] CLI 名を NAM-02 の表で選んだ(依頼の指定 → 最初の名詞の複数形 →
<動詞>-<目的語の複数形>) - [ ] 各項目・オプションの型が値の意味に合っている(日付が
stringになっていない。CODE-02) - [ ] 一度に複数件を消す・変える操作に
-f/--forceがある(STATE-01) - [ ] ファイルに書くコマンドは、データの置き場(
storageがdata)か-o/--outputだけに書く(DEP-05) - [ ] 実装の依頼では、仕様に無いオプション・別名・環境変数を実装に足していない(DEP-02)
- [ ] 保護ファイル(
.foundation/manifest.jsonのprotected)を変えていない(TOOL-03) - [ ]
make checkが通った(PROC-05)
7. 報告する
次の順で書く(PROC-05)。
- 何を作ったか(使ったパターンの番号と名前)
- 変えたファイルの一覧(作る順序の順)と、使った生成器のコマンド
- 2節で決めた値と、その根拠(依頼文、ユーザーの回答、既定値のどれか)
make checkの結果(出力の末尾)。実装の依頼ではmake conformの結果- 決めきれずに残したこと、ルールと既存の仕様の食い違い、レジストリで CLI 名が空いているかの確認(この基盤は確かめない)
04 同仓库更多 Skills
setup
このDocusaurusパターンの初期設定・設定変更を、OSSと独自設定の台帳に沿った質問とCLIで行う。site.settings.jsonとsetup/settings.catalog.jsonがある配布先で使用する。
sample
日付の表記を ISO 8601(YYYY-MM-DD)にそろえる見本のスキル。テストで使う。
skill-tune
既存の Claude Code スキルを評価データで改善する。正解データがあれば学習用・検証用・テスト用に分け、無ければ人と評価項目を決め、独立した学習と検証のラウンドを回し、最後にテスト用で測って報告する。
review
skill-tune-kit の変更をレビューする手順。差分、プルリクエスト、ブランチ、特定のファイルのレビューを頼まれたとき、また「この実装で問題ないか確認して」「ルールに沿っているか見て」と頼まれたときは必ず使う。機械の検査を先に回し、機械で拾えないルールをルールIDごとに確かめ、固定の形式で指摘と判定を返す。
impl
skill-tune-kit で実装・変更・追加・修正を行う手順。「検査の種類を足して」「サブコマンドを追加して」「プロンプトの文言を直して」「plan.json に項目を足して」「status の表示を変えて」「採否の規則を変えて」「〜の不具合を直して」「skill-tune の手順を直して」などの依頼で使う。この基盤のコードや配布物を書く・変える依頼では、依頼の大小にかかわらず必ず使う。依頼をパターンに振り分け、決められた順序で作り、`make check` と完了前チェックリストで確かめてから報告する。
sample
議事録の日付をそろえる。議事録の整形を頼まれたときに使う。