AGENT SKILL

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

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. 書く前に読む

  1. patterns.md の該当する節を最後まで読む

  2. 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
  3. 見本の該当ファイル(patterns.md の「見本」)を開き、キーの書き方・summary の文・オプションの組を確かめる

4. 作る順序

PROC-01 の順で作る。生成器を使わずに cli.json を白紙から書かない(STR-02)。

  1. 依頼から、CLI 名・名詞・動詞・項目を2節の表で書き出す
  2. make new NAME=<name>(操作が1つなら SINGLE=1)
  3. 名詞ごとに make command NAME=<name> NOUN=<名詞> VERB=<動詞>(識別子が name なら最初に KEY=name)
  4. 名詞ごとに make field NAME=<name> NOUN=<名詞> FIELD=<項目名> TYPE=<型>(LIST=1・NULLABLE=1・VALUES=a,b)
  5. cli.json の TODO を埋め、依頼の既定値・絞り込み・標準のオプションを足す
  6. 環境変数を STATE-01 で足す(必要なときだけ)
  7. make fix(整形、版、cli.md の生成)
  8. make check

cli.json を編集して保存するたびに、hooks が make after-edit で整形・版・cli.md の生成・その仕様の検査を回す(TOOL-02)。指摘が出たら、次の編集に進む前に直す。

5. 検証する

  1. make check を実行する

  2. 落ちたら、エラーの先頭のルールID(NAM-07 specs/notes/cli.json:42 ...)を rules.md で引き、cli.json を直す。エラー文に期待する値が書いてあれば、その値にする

  3. 次の方法で検査を黙らせない(TOOL-03)

    • 検査ツール(tools/)、Makefile、.foundation/、docs/design/rules.md などの保護ファイルを変える
    • 仕様に表に無いキー(x-、_、$comment)を書く
    • Python に抑止コメント(# noqa など)やテストの skip を書く

    どうしても直せない場合は、その状態のまま報告する

  4. 実装の依頼(パターン 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)。

  1. 何を作ったか(使ったパターンの番号と名前)
  2. 変えたファイルの一覧(作る順序の順)と、使った生成器のコマンド
  3. 2節で決めた値と、その根拠(依頼文、ユーザーの回答、既定値のどれか)
  4. make check の結果(出力の末尾)。実装の依頼では make conform の結果
  5. 決めきれずに残したこと、ルールと既存の仕様の食い違い、レジストリで CLI 名が空いているかの確認(この基盤は確かめない)

04 同仓库更多 Skills

yukihito-jokyu
yukihito-jokyu/pattern

setup

このDocusaurusパターンの初期設定・設定変更を、OSSと独自設定の台帳に沿った質問とCLIで行う。site.settings.jsonとsetup/settings.catalog.jsonがある配布先で使用する。

★ 0
yukihito-jokyu
yukihito-jokyu/pattern

sample

日付の表記を ISO 8601(YYYY-MM-DD)にそろえる見本のスキル。テストで使う。

★ 0
yukihito-jokyu
yukihito-jokyu/pattern

skill-tune

既存の Claude Code スキルを評価データで改善する。正解データがあれば学習用・検証用・テスト用に分け、無ければ人と評価項目を決め、独立した学習と検証のラウンドを回し、最後にテスト用で測って報告する。

★ 0
yukihito-jokyu
yukihito-jokyu/pattern

review

skill-tune-kit の変更をレビューする手順。差分、プルリクエスト、ブランチ、特定のファイルのレビューを頼まれたとき、また「この実装で問題ないか確認して」「ルールに沿っているか見て」と頼まれたときは必ず使う。機械の検査を先に回し、機械で拾えないルールをルールIDごとに確かめ、固定の形式で指摘と判定を返す。

★ 0
yukihito-jokyu
yukihito-jokyu/pattern

impl

skill-tune-kit で実装・変更・追加・修正を行う手順。「検査の種類を足して」「サブコマンドを追加して」「プロンプトの文言を直して」「plan.json に項目を足して」「status の表示を変えて」「採否の規則を変えて」「〜の不具合を直して」「skill-tune の手順を直して」などの依頼で使う。この基盤のコードや配布物を書く・変える依頼では、依頼の大小にかかわらず必ず使う。依頼をパターンに振り分け、決められた順序で作り、`make check` と完了前チェックリストで確かめてから報告する。

★ 0
yukihito-jokyu
yukihito-jokyu/pattern

sample

議事録の日付をそろえる。議事録の整形を頼まれたときに使う。

★ 0