CLIの外部仕様をJSONで設計する
CLIは、ターミナルからコマンドと引数を渡して実行するプログラムです。人が使うだけでなく、シェルスクリプトも出力や終了コードを読み取ります。そのため、同じ操作でも作者によってコマンド名、JSONの形、エラーの扱いが変わると、利用する側の手順も変わります。
このパターンでは、その外部仕様をspecs/<name>/cli.jsonにまとめます。生成器で仕様を作り、リファレンスとヘルプの文面を生成し、別途作ったCLIを適合テストで実行して仕様と照合します。実装言語を選ぶ前に、利用者から見える振る舞いを決められる構成です。
同梱する見本は、メモとタグを管理するnotes、ファイル内の単語を集計するcount-wordsです。検査ツールと見本の実装はPythonの標準ライブラリだけで動きます。Go・Python・Node.js・Rustで実装するための対応表も同梱しますが、各言語のCLI本体を自動生成するものではありません。
全体像
ZIPを展開すると、次の構造になります。設計するCLIの仕様はspecs/、仕様を検査するプログラムはtools/clispec/に分かれています。
cli-design/
├── README.md 環境・使用・検証の手順
├── AGENTS.md / CLAUDE.md エージェント向けの作業規約
├── Makefile / .python-version 操作の入口とPythonの系列
├── specs/
│ ├── notes/
│ │ ├── cli.json メモ管理の外部仕様
│ │ ├── cli.md 仕様から生成するリファレンス
│ │ └── released/1.0.0.json 互換性比較の基準
│ └── count-words/ 単語集計の同じ3種類のファイル
├── tools/clispec/
│ ├── scaffold.py CLI・コマンド・項目の生成器
│ ├── model.py / vocab.py 仕様の読み方と共通の決定表
│ ├── check.py / canon.py 仕様検査と正規のJSON表記
│ ├── helptext.py / gen.py ヘルプとリファレンスの生成
│ ├── compat.py 公開済み仕様との互換性比較
│ ├── conform.py 実装を外から実行する適合テスト
│ └── tests/fixtures/ 見本2種類のPython実装
├── docs/design/ ルール・構造・判断理由・開発記録
├── .claude/ 設計・レビュースキルとhooks
├── .foundation/ ルール検査・違反例・評価資料
├── ci.json ZIP検証の環境とコマンド
└── .ci/verify.py ZIP内で完結する準備・検証
作者はmake new・make command・make fieldで仕様を作り、依頼に合わせて必要な値を決めます。make fixが整形と版計算を行い、cli.mdを生成します。make checkで仕様と生成物の整合を確認してから、実装者がその仕様に従ってCLIを作り、make conformで確かめます。
この順序にする理由は、実装ごとにCLIの形を決め直さないためです。例えばnotes note list --jsonの結果はJSON配列と決め、その1行が持つ項目を型に定義します。Pythonで書いても別の言語で書いても、この約束を適合テストの共通の期待値にできます。
1. 仕様がコマンドの形を決める
仕様全体の7つのキー
specs/count-words/cli.jsonは次の値から始まります。配列の中身は後の節で説明します。
{
"name": "count-words",
"version": "1.0.0",
"summary": "Count words in files",
"storage": "none"
}
これは先頭部分の抜粋です。実ファイルには続けてcommands・types・envがあり、7つのキーをすべて指定します。任意のキー省略を許すと、同じ設計でも書き方が変わるためです。未知のキーも検査で拒否します。
| キー | 役割とこの見本での動作 |
|---|---|
name | 起動名と仕様ディレクトリ名。count-wordsはヘルプ・版表示・エラー接頭辞に使い、環境変数の接頭辞はCOUNT_WORDSになる |
version | 利用者に見せる版。初版は1.0.0で、公開済み仕様があれば差分から次の版を計算する |
summary | ヘルプに載せる英語の説明。既定値や必須条件は別のキーに書き、文と設定の二重管理を避ける |
storage | noneは管理データを保存しないCLI、dataは管理データを保存するCLI。単語集計はnone、メモ管理はdata |
commands | 操作ごとのパス・入力・出力・終了コード。単語集計はルート操作1つ、メモ管理は名詞と動詞の組 |
types | JSON出力1件分の項目。単語集計ではword_count、メモ管理ではnoteとtag |
env | 許可する環境変数。単語集計では最小文字数、メモ管理ではデータ保存先を指定する |
CLI名は小文字・数字・ハイフンで2〜20文字とし、英字で始めます。出力項目名はcreated_atのようなsnake_case、オプションは--min-lengthのようなkebab-case、環境変数は大文字とアンダースコアにします。名前から役割を読み取れ、環境変数名も機械的に導ける形です。
summaryは大文字で始まるASCIIの英語で、末尾のピリオドを付けず60文字以内にします。標準の操作にはCreate a noteのような決まった文を使います。これはこのパターンの規約であり、CLI全般に英語を必須とする標準ではありません。
操作が1つならルート、複数なら名詞と動詞
specs/notes/cli.jsonのcommandsから、メモ作成の要素を抜粋します。
{
"commands": [
{
"path": ["note", "create"],
"summary": "Create a note",
"args": [],
"options": [
{
"name": "tag",
"type": "string",
"values": [],
"default": null,
"required": false,
"repeatable": true,
"summary": "Tag of the note"
},
{
"name": "title",
"type": "string",
"values": [],
"default": null,
"required": true,
"repeatable": false,
"summary": "Title of the note"
}
],
"output": {"kind": "object", "type": "note"},
"exit_codes": [0, 1, 2]
}
]
}
pathが["note", "create"]なので、起動名と合わせてnotes note createになります。argsが空なのは、作成時の整数IDを利用者が指定しないためです。タイトルは必須オプション、タグは省略できる繰り返しオプションなので、例えばnotes note create --title "Read book" --tag home --tag studyという形になります。
操作を名詞の下へ集めるため、メモの作成・一覧・参照・編集・削除はnote create・note list・note view・note edit・note deleteに統一します。同じ意味のaddやremoveは使いません。一方、count-wordsは集計という1操作なのでpathを[]にし、count-words input.txtと実行します。ルート操作とサブコマンドは混在させません。
標準動詞の生成器は、出力の種類と終了コードも決めます。識別子が整数のidなら作成時の位置引数はなく、view・edit・deleteは識別子を位置引数で受け取ります。識別子が文字列のnameであるtag create homeは、その名前を受け取り、重複を終了コード4で返す設計です。
位置引数とオプションの値
specs/count-words/cli.jsonのルート操作には、次の位置引数があります。
{
"args": [
{
"name": "file",
"type": "file",
"values": [],
"required": true,
"variadic": true,
"summary": "File to read, or - to read stdin"
}
]
}
required: trueなので入力ファイルが必要です。variadic: trueは同じ種類の値を複数受け取る指定で、a.txt b.txtのように渡せます。file型の-は標準入力です。位置引数は最大1種類に制限し、複数の意味を持つ値は名前付きのオプションで区別します。
オプションのキーは、先のtitle・tagと同じ7つです。
| キー | 意味と指定理由 |
|---|---|
name | --を除いた名前。項目名から導ける名前にし、同じ項目の呼び名を操作ごとに変えない |
type | 値の型。解析方法と不正入力の検査を決める |
values | enumだけが持つ選択肢。それ以外は[]にし、型と制約を分ける |
default | 省略時の値。必須または繰り返し指定のオプションはnullにする |
required | 指定が必要か。titleはtrueなので欠落時に実装が終了コード2を返す |
repeatable | 同じオプションを複数回使えるか。tagはtrueで、タグの集まりを渡せる |
summary | ヘルプの説明。必須・既定値・選択肢は設定から生成するので文に重ねて書かない |
値の型は、文字列string、整数integer、小数number、選択肢enum、日付date、ファイルfile、ディレクトリdirectoryを使います。真偽値booleanは値を取らないオプションで、既定値はfalseです。日時timestampは出力項目だけに使い、UTCの秒精度のYYYY-MM-DDTHH:MM:SSZで表します。日付はYYYY-MM-DDです。
値を取るオプションは--limit 10または--limit=10、真偽値は--forceの形です。-で始まる値は--title=-draftのように渡します。--以降は位置引数とし、オプションと位置引数の前後を入れ替えても同じ意味になる実装を求めます。長い名前の前方一致省略や短い名前の束ねを仕様には含めません。
-h/--help、ルートの--version、構造化出力の--jsonは仕様に書かず導出します。短い名前も独自に追加せず、必要になった標準オプションについてall→-a、debug→-d、dry-run→-n、force→-f、output→-o、port→-p、quiet→-q、user→-uという決定表を使います。すべてを各CLIに追加するわけではありません。
Pythonの標準解析器は長い名前の省略を既定で許可するため、見本はallow_abbrev=Falseを指定します。標準ライブラリを使う場合も、生成ヘルプ・エラーの形式・入力順序はこの仕様に合わせる必要があります。Python 3.14のargparseの既定動作と、このパターンの決定を区別します。
2. 出力の型からJSONと表をそろえる
specs/count-words/cli.jsonの出力と型を抜粋します。
{
"commands": [
{
"output": {"kind": "list", "type": "word_count"}
}
],
"types": [
{
"name": "word_count",
"fields": [
{"name": "count", "type": "integer", "values": [], "list": false, "nullable": false},
{"name": "word", "type": "string", "values": [], "list": false, "nullable": false}
]
}
]
}
output.kindがlistなので、--jsonの結果はword_countの配列です。alpha beta alphaを集計した場合は[{"count":2,"word":"alpha"},{"count":1,"word":"beta"}]になります。JSONを指定しなければ、見出しをCOUNTとWORDにした表です。0件のJSONは[]、表は見出しだけになります。
output.typeは同じ仕様内の型名を参照します。型のnameは1行の意味、fieldsは全項目で、それぞれname・type・values・list・nullableを持ちます。list: trueは値の配列、nullable: trueはnullを許す指定です。項目型には別の型を参照する入れ子を許さず、表に置けるスカラーの値に限定します。
1件を返す操作はobjectとして、その型の全項目を持つJSONオブジェクトと表1行を返します。変換結果そのものを返す場合はraw、結果がない場合はnoneとし、どちらもoutput.typeをnullにして--jsonを持ちません。これにより、操作ごとにJSONの包み方を決め直す必要がなくなります。
項目の順は識別子を先頭にし、残りは名前順です。表ではnullを-、リストをカンマ区切り、真偽値をtrue・falseにします。単語集計の列がCOUNT WORDなのもこの規約の結果です。JSONの形と意味は公開面ですが、人向けの表をスクリプトから解析する前提にはしません。
項目の追加を操作へ連動させる
項目を手で各操作へ複製すると、作成にはあるのに編集にはない、といった不整合が起きます。make fieldは型の項目だけでなく、関連するcreate・editのオプションとlistの並べ替え候補を合わせて追加します。
例えば見本のnote.tagsはリストの項目なので、入力は繰り返し可能な--tagです。note editにはタグを空にする--clear-tagsもあります。通常の--tag home --tag workは既存のタグをこの2つで置き換え、追加結合にはしません。値指定と同じ項目の--clear-…を同時に渡した場合や、変更オプションを1つも指定しない編集は終了コード2です。
listには既定20件の--limitと、識別子を既定値にした--sortを置きます。絞り込みは要件が求めた項目だけ追加し、複数条件はANDで組み合わせます。--tag home --tag workなら両方のタグを持つメモだけを返します。並べ替えは昇順で、nullを末尾、同値なら識別子順にし、絞り込みと並べ替えの後で件数を制限します。これらの意味は型だけでは表せないため、同梱ルールSTATE-02の決定表と適合テストでそろえます。
3. 環境変数と終了コードを決める
specs/count-words/cli.jsonの環境変数は次の定義です。
{
"env": [
{
"name": "COUNT_WORDS_MIN_LENGTH",
"type": "integer",
"values": [],
"default": 1,
"summary": "Minimum length of a word to count"
}
]
}
nameはCLI名と--min-lengthから導きます。typeとvaluesは対応するオプションと同じにし、defaultは環境変数も未指定の場合の値です。COUNT_WORDS_MIN_LENGTH=5なら5文字以上を集計しますが、--min-length 1も渡した場合はオプションの1が優先します。設定ファイルを追加しないことで、値の解決順を「オプション→環境変数→既定値」に限定しています。
notesはstorage: "data"なので、保存先としてNOTES_DATA_DIRを定義します。macOS/Linuxでは、この環境変数の空でない絶対パス、$XDG_DATA_HOME/notes、$HOME/.local/share/notesの順に解決する規約です。JSON内のdefault: "$XDG_DATA_HOME/notes"はその規約を表す記述であり、シェルがJSONの中で展開するわけではありません。適合テストは専用の保存先を指定する経路を確認し、既定保存先の全OS分岐までは検証しません。
設定ファイル・対話入力・色・進捗表示は設けません。スクリプトから同じ入力で実行できることを優先した、このパターンの選択です。一般的なCLI指針も標準出力・標準エラーやJSON出力の扱いを説明していますが、具体的な動詞や終了コードの数値、非対話への限定は本パターンで決めたものです。Command Line Interface Guidelines
| 終了コード | 意味 | 仕様への入れ方 |
|---|---|---|
| 0 | 成功 | 全操作 |
| 1 | 読み書き失敗などの予期しない失敗 | 全操作 |
| 2 | 使い方の誤り | 全操作 |
| 3 | 指定した対象・入力ファイルなどがない | 識別子で対象を受け取る操作やファイル入力のある操作 |
| 4 | 同じ名前の対象が既にある | 識別子がnameの作成操作 |
note createは[0,1,2]、note viewは[0,1,2,3]、tag createは[0,1,2,4]です。単語集計は入力ファイルがない場合もあるため[0,1,2,3]です。エラー時はstdoutを空にし、stderrへcount-words: メッセージのように起動名を接頭辞にした1行を英語で出します。成功時はstderrを空にし、主な結果だけをstdoutへ出します。
4. 生成ヘルプと版を実装へつなげる
Makefileでは、検査ツールを次のように起動します。
PYTHON := uv run --no-project --quiet python
CLISPEC := $(PYTHON) tools/clispec
fix: version
@$(CLISPEC) fmt
@$(CLISPEC) gen
.python-versionは3.14です。--no-projectでサイトや利用先のPythonプロジェクトの依存解決を行わず、uvで指定系列のPythonを起動します。最初のversionターゲットは、系列が合うこととuv経由であることを確認します。uvによるPythonの検出・導入は公式のPython管理手順に従います。
fmtはキー順、名前順、2スペースの字下げをそろえ、公開済み仕様との差分から版も調整します。genは同じ仕様からリファレンスとヘルプを作ります。例えば単語集計のヘルプはUsage: count-words [options] <file>...から始まり、--limitの既定値20も設定から表示されます。実装はこの生成文面をそのまま使い、-hと--helpのstdoutが一致することを適合テストで確認します。
ヘルプと版表示は正常操作なので終了コード0です。--versionはcount-words 1.0.0の1行を返します。解析器が独自に生成するusageや装飾をそのまま使うと文面がずれるため、見本は生成文面を定数として持ち、引数解析の既定ヘルプを使いません。
公開済み仕様を互換性の基準にする
released/1.0.0.jsonは、版を確定したときの仕様です。compat.pyはその最新版と現在の仕様を比較します。差分がなければ同じ版、summaryだけならパッチ、任意項目などの追加ならマイナーを上げます。削除、既存の値や型の変更、既存操作への必須入力の追加などはメジャー変更です。
make fixはパッチ・マイナーを自動反映しますが、メジャー変更は承認とADRが必要なため自動で反映しません。過去のreleased/を書き換えて比較を通すことも禁止します。版を確定するmake release NAME=<name>は、利用者が公開を決めたときに実行します。ZIPの取得や検証だけでリリース操作を行う必要はありません。
5. 設計と検査の入口をそろえる
ルールの全文はZIP内のdocs/design/rules.md、ルールと検査の対応はenforcement-matrix.mdにあります。例えば仕様の未知キーはCODE-01、名前はNAM-01、生成物の不一致はSTR-04というIDで報告されるため、検査結果から理由と修正先をたどれます。
make checkは、仕様検査、整形の確認、リファレンスの再生成差分、見本実装への適合テスト、抑止記法の検査、ルールとスキル・検査の対応を確認します。44ルールすべてを機械だけで判定するわけではありません。名前が要件に合うか、保護ファイルを変えて検査を弱めていないか、破壊的変更の承認があるかは、設計・レビュースキルでも確認します。
適合テストはCLIを別プロセスとして動かし、ヘルプ・版・不正入力・出力の型・終了コード・保存と再取得・編集・絞り込みを確認します。データ用の環境変数は一時ディレクトリに向けます。任意の業務要件すべてを証明するものではなく、仕様で表せない単語の区切り方などの意味は、依頼・実装・固有の検証で決める必要があります。
Claude Codeで編集前後の処理を呼ぶ
Claude Codeで仕様を編集するときは、編集前に「検査の仕組みを変えようとしていないか」を確認し、編集後に「変更した仕様が規約に合っているか」を調べます。この2つを呼び出すのが.claude/settings.json、確認対象や実行コマンドを定めるのが.foundation/manifest.jsonです。
- 編集前に
hooks.py pre-editを呼びます。保護ファイルへの編集なら、Claude Codeへ人間の確認を求める応答を返します。 - 編集後に
hooks.py post-editを呼びます。specs/*/cli.jsonなら、整形・ヘルプ生成・対象仕様の検査を実行します。
フックはClaude Codeのツール実行に連動する仕組みです。別のエージェントやシェルから編集する場合は、後述のコマンドを手動で実行します。以下では、呼び出し元の設定と呼び出された処理を順に対応させます。
編集前:保護ファイルを変える操作を確認する
.claude/settings.jsonの編集前の設定です。
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write|MultiEdit|NotebookEdit",
"hooks": [
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/.foundation/bin/hooks.py\" pre-edit",
"timeout": 30
}
]
}
]
}
}
matcherは編集ツールの名前です。該当するツールが動く前に、type: commandで指定したPythonコマンドを起動し、編集対象などの情報を標準入力のJSONで渡します。timeout: 30は、この確認処理の待ち時間の上限です。CLAUDE_PROJECT_DIRからスクリプトを探すため、Claude CodeはZIPの展開先のcli-design/をルートとして開始します。
呼び出されたhooks.pyは、.foundation/manifest.jsonの次の値を読みます。
{
"status": "ready",
"protected": [
"Makefile",
".editorconfig",
".gitignore",
".python-version",
"tools/**",
"specs/*/released/**",
".claude/settings.json",
".foundation/**",
"docs/design/rules.md",
"docs/design/enforcement-matrix.md",
"ci.json",
".ci/**"
]
}
status: readyのとき、編集対象がprotectedのいずれかに一致すると、permissionDecision: askを返します。例えばtools/clispec/check.pyや公開済みのspecs/notes/released/1.0.0.jsonの編集は確認対象です。一方、設計中のspecs/notes/cli.jsonはこの一覧に含まれないため、この保護確認は求めません。
保護するのは、検査ツール、検査の入口、確定済み仕様、規約、フック、ZIP検証処理です。仕様の不備を直す代わりに検査や比較基準を弱めてしまう変更を、人間が確認できるようにしています。これは対象の編集ツールに対する確認であり、シェルなど、あらゆる書き込み経路を禁止する仕組みではありません。
編集後:変更した仕様を整形し、ヘルプと検査結果を更新する
.claude/settings.jsonの編集後の設定です。
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write|MultiEdit",
"hooks": [
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/.foundation/bin/hooks.py\" post-edit",
"timeout": 120
}
]
}
]
}
}
Edit・Write・MultiEditが成功した後にpost-editを呼びます。編集後は整形や生成も行うため、待ち時間の上限は120秒です。PreToolUseにあるNotebookEditは、ここには含まれていません。
どのファイルに何を実行するかは、.foundation/manifest.jsonで指定します。
{
"hooks": {
"post_edit": [
{
"glob": "specs/*/cli.json",
"command": "make -s after-edit FILE={file}"
}
]
}
}
例えばspecs/notes/cli.jsonを変更すると、{file}をその相対パスに置き換えて、基盤のルートで次のコマンドを実行します。
make -s after-edit FILE=specs/notes/cli.json
この処理が仕様の整形・版の調整、ヘルプとリファレンスの生成、対象仕様の検査を行います。生成物の更新を編集者の記憶に頼らず、仕様の変更に連動させるためです。検査に失敗した場合、フックは指摘を標準エラーへ出して終了コード2を返します。編集を自動で取り消す処理ではないので、指摘に従って仕様を直します。
globに一致しないファイルでは、この自動処理は動きません。また、対象仕様の編集後処理だけで全体の検証は終わらないため、作業の最後にはmake checkを実行します。
検査を省略する記述を検出する
自動で検査を呼んでも、検査対象のコードに「この行を無視する」「このテストを飛ばす」という記述を加えると、不備を隠せてしまいます。make checkから呼ぶguard.pyは、そのような記述を検出します。
guardの走査範囲・禁止する記述・例外
.foundation/manifest.jsonの設定です。
{
"guard": {
"rule": "TOOL-03",
"include": [
"**/*.py",
"specs/**/*.json"
],
"exclude": [
".foundation/**"
],
"suppressions": [
{
"pattern": "#\\s*noqa",
"rule": "TOOL-03"
},
{
"pattern": "#\\s*type:\\s*ignore",
"rule": "TOOL-03"
},
{
"pattern": "unittest\\.skip",
"rule": "TOOL-03"
},
{
"pattern": "skipTest\\(",
"rule": "TOOL-03"
},
{
"pattern": "expectedFailure",
"rule": "TOOL-03"
}
],
"allow": []
}
}
includeはPythonファイルと仕様JSONを走査対象にします。suppressionsのpatternは正規表現で、例えば# noqaや# type: ignore、unittest.skipを含む行を見つけると、対応するrule: TOOL-03で報告します。allowは例外の一覧ですが、この基盤では空なので個別の免除は設けていません。
検査機構自体は検出用の文字列を持つため、excludeで.foundation/**を除きます。これに加えて、guard.pyには.claude/**、docs/design/**、AGENTS.md、CLAUDE.md、README.mdを除く既定値があります。規約の説明やスキルに書いた禁止記法の例を、実装内の違反と混同しないためです。
仕様JSONの未知キーは、この正規表現の検査では判定しません。tools/clispec/check.pyが仕様の構造を検査し、CODE-01として報告します。同じmake checkから起動しますが、担当する検査は別です。
作業規約と検査コマンドの参照先をそろえる
AGENTS.mdは仕様の作成・変更・検証の作業規約です。CLAUDE.mdには@AGENTS.mdがあり、Claude Codeでも同じ規約を参照します。設計用・レビュー用の詳しい手順は.claude/skills/に分けています。
スキル名、共通コマンド、基盤の管理情報
.foundation/manifest.jsonでは、対応するスキルとコマンドを次のように宣言します。
{
"skills": {
"impl": "cli-design",
"review": "cli-design-review"
},
"commands": {
"check": "make check",
"fix": "make fix"
}
}
skills.implは.claude/skills/cli-design/、skills.reviewは.claude/skills/cli-design-review/に対応します。前者は設計・実装時、後者はレビュー時の確認事項です。この名前の宣言だけでスキルを自動実行するわけではありません。commands.checkとcommands.fixは、違反例の検証や収束評価でも使う共通の入口です。通常の作業と同じmake check・make fixへそろえ、評価だけ別の検査を通す状態を避けます。
同じファイルの管理情報は次の値です。
{
"name": "cli-design",
"status": "ready",
"mode": "new",
"domain": [
"cli-library"
],
"language": "ja",
"copy": {
"link_dirs": [],
"skip_dirs": []
}
}
nameは基盤名、mode: newは新規構築、domainはCLIライブラリ、language: jaは日本語で作業する基盤であることを記録します。status: readyは保護確認を有効にするほか、通常のルール検査を最終段階のphase 5にします。この段階では、レビュースキルとルールの対応も検査対象です。
copyは、違反例の検証などで作る一時コピーの追加設定です。link_dirsとskip_dirsが空なので、独自のリンク先や除外先は追加しません。ただし、.gitやキャッシュを除外するなど、コピー処理に組み込まれた既定値は有効です。
stackとtoolsは、元実装が調査した技術と検査ツールの台帳です。各要素のname・version・role、必要に応じたlanguage、版を固定する方針のpinnedを保持します。これらの宣言から言語環境を自動導入する処理はありません。Go・Python・Node.js・Rustの解析器について記録された版を、そのまま全環境の動作確認済みの版と扱わないでください。ZIPの検証で使うPython系列は.python-versionとci.json、導入するuvの版は.ci/verify.pyで確認します。
エディタとZIPの検証環境をそろえる
仕様の表記をそろえる設定と、展開先で検証する設定は役割が異なります。前者は編集時の文字コードや字下げ、後者は実行するPythonと検証コマンドを指定します。
エディタの文字コード・改行・字下げ
.editorconfigの設定です。
root = true
[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
indent_style = space
indent_size = 4
[*.json]
indent_size = 2
[Makefile]
indent_style = tab
root = trueで上位ディレクトリのEditorConfig探索を止め、このZIP内の方針を使います。[*]ではUTF-8、LF、末尾改行あり、行末空白の除去、空白4文字を既定にします。JSONは生成器と同じ2文字、Makefileはコマンド行に必要なタブへ上書きします。対応エディタでの編集をそろえる設定なので、CLI仕様のキー順などは引き続きmake fixで整えます。
.gitignoreは__pycache__/・*.pyc・.DS_Storeを除き、Pythonの実行やmacOS上の操作で生じるファイルを管理対象へ混ぜないようにします。
ZIPの展開先で準備と検証を実行する設定
ci.jsonの全体です。
{
"command": [
"python3",
".ci/verify.py"
],
"pythonVersion": "3.14"
}
共通のZIP検証処理がpythonVersionでPython 3.14を選び、展開したパターンのルートでcommandの配列を実行します。.ci/verify.pyは一時環境へuv 0.13.3を導入してから、全体検査、見本2種類の適合テスト、代表的な違反4件の検出、新しい仕様の生成を順に確かめます。準備や途中の検査が失敗したら後続を止め、非0で終了します。
利用先にサイトのNode.js依存関係を持ち込まず、ZIP内のファイルだけで同じ検証を行うための設定です。基盤直下にci.jsonを許可し、.ci/を保護対象へ追加した理由は、ZIP内のdocs/design/adr/0008-standalone-pattern-ci.mdに記録しています。実行手順と結果は後の「検証方法と結果」にあります。
元実装の評価設定を保管する
.foundation/convergence/には、元実装で複数のエージェントに同じ課題を解かせ、結果の一致を比較した資料があります。通常のCLI設計やZIP検証とは実行の入口が異なるため、評価条件は分けて確認します。
複数エージェントによる評価の実行条件と一致の基準
.foundation/manifest.jsonの設定です。
{
"convergence": {
"agents": 3,
"max_rounds": 3,
"parallel": 3,
"timeout_sec": 1800,
"runner": [
"claude",
"-p",
"{prompt}",
"--output-format",
"json",
"--permission-mode",
"acceptEdits",
"--no-session-persistence",
"--allowedTools",
"Skill",
"Bash(make check)",
"Bash(make fix)",
"Bash(make *)",
"Bash(git diff *)",
"Bash(git status *)"
],
"ignore": [
"**/__pycache__/**"
],
"thresholds": {
"files": 1.0,
"names": 0.8,
"content": 0.0
}
}
}
agents: 3は比較するエージェント数、max_rounds: 3は最大の評価ラウンド数です。parallel: 3で同時実行の上限を3、timeout_sec: 1800で1実行の上限を30分にします。runnerは課題を{prompt}へ差し込むClaudeの起動引数です。JSONで結果を受け取り、セッションを保存せず、編集の許可モードと利用可能なツールをこの配列で指定します。ignoreはPythonキャッシュを比較から除きます。
thresholdsは結果の一致度の下限です。変更したファイルの集合は1.0、新しく導入した名前の集合は0.8、内容は0.0とし、内容の逐語的な一致は求めません。保護ファイルの変更があれば不合格になり、検査を実行して比較する場合は全員の検査成功も条件になります。
これらは元実装の評価条件を保持したもので、make checkや.ci/verify.pyから評価エージェントを起動することはありません。今回確認したZIPの検証結果と、過去の評価資料は区別します。
導入・使用方法
1. ZIPを展開して環境を準備する
macOS/Linux、GNU Make、Python 3.14、uvを使います。検査ツールと見本に外部Pythonパッケージは不要です。自動のZIP検証はPythonのvenv・pipとネットワークを使い、一時環境へuv 0.13.3を導入します。サイトのNode.jsやDocusaurusに依存しません。
ZIPを展開し、隠しファイルを含むcli-design/全体を作業用の独立したディレクトリへ置きます。既存のAGENTS.md・Makefile・.claude/などへ上書き統合せず、まずこのディレクトリ内で手順を確認してください。以下はすべて展開先を作業場所とします。uvの導入は公式の導入手順を使います。
uv --version
make --version
uv python install 3.14
make check
準備に失敗した場合は停止します。
2. 見本の単語集計を実行する
見本の単語集計は次の入力で試せます。
printf 'alpha beta alpha\n' | uv run --no-project --quiet python tools/clispec/tests/fixtures/count_words_impl.py - --json
結果はalphaが2回、betaが1回のJSON配列です。--min-length 5を付けるとalphaだけになります。
3. 新しい管理CLIの仕様を作る
次の手順は新しい作業用コピーで行います。bookmarksという仕様が既にある場合は別名を使います。
make new NAME=bookmarks
make command NAME=bookmarks NOUN=bookmark VERB=create
make command NAME=bookmarks NOUN=bookmark VERB=list
make command NAME=bookmarks NOUN=bookmark VERB=view
make command NAME=bookmarks NOUN=bookmark VERB=edit
make command NAME=bookmarks NOUN=bookmark VERB=delete
make field NAME=bookmarks NOUN=bookmark FIELD=url TYPE=string
make fix
make check
specs/bookmarks/cli.jsonとcli.mdが作られます。識別子は整数のid、作成時の--urlは必須、版は1.0.0です。createがあるため作成時刻、editがあるため更新時刻も追加され、管理データの保存先としてBOOKMARKS_DATA_DIRが定義されます。これらは生成器の規約で決まる値であり、実行可能なブックマーク管理プログラムは別途実装します。
操作を追加するNOUN・VERB、項目のFIELD・TYPEは利用先の要件に合わせます。名前で識別する対象にはKEY=name、複数値はLIST=1、任意項目はNULLABLE=1、列挙型はVALUES=a,bを使います。1操作だけならmake new NAME=<name> SINGLE=1から始めます。生成されたTODOは依頼に合わせて埋め、cli.mdは手で直さずmake fixを使います。
4. 仕様に従って実装し、適合テストで確かめる
実装は基盤の外へ置き、同梱の.claude/skills/cli-design/references/stdlib-mapping.mdに沿って各言語の標準ライブラリで引数を解析します。次のCMDを実際の起動コマンドの絶対パスへ置き換えて確認します。
make conform SPEC=specs/bookmarks/cli.json CMD="/absolute/path/to/bookmarks"
Claude Codeと使う場合はこの基盤のルートで起動します。別のエージェントやシェル編集ではhooksの自動実行を前提にせず、スキルを読み、仕様の変更後にmake after-edit FILE=specs/<name>/cli.json、最後にmake checkを実行します。
利用時に確認する制約
この基盤の上限は、名詞8種類、位置引数1種類、明示するオプション10個、型の項目12個です。項目を増やすと編集・クリア用オプションも増えるため、型の上限より先にオプションの上限へ届く場合があります。検査結果に従って操作を見直し、上限や設計ルールを変える場合はADRから順に変更します。
見本のPython実装は、規約を理解して適合テストを試すためのものです。業務で使う場合の同時更新、障害時の保存保証、入力サイズ、独自の業務制約は別途検討します。適合テストに通ったことを、任意の用途での完全な正しさや耐障害性の証明とはしません。
保存先の既定分岐、追加前の古い保存データに新項目がない場合の移行、任意の隠しオプションが存在しないことは、適合テストだけでは網羅しません。Windows、各言語への移植、Claude Codeの実際の対話・hooksの起動は、それぞれ利用先で確認してください。
検証方法と結果
生成ZIPを別の場所へ展開し、Python 3.14で次を実行します。
python3 --version
make --version
python3 .ci/verify.py
ci.jsonはcommand: ["python3", ".ci/verify.py"]とpythonVersion: "3.14"を指定します。検証処理は一時環境へのuv導入、make check、見本2種類へのmake conform、違反4件の検出、別の一時コピーでの新規仕様生成を順に行います。途中失敗は後続を止め、非0で終了します。最後のZIP検証: 全検査・見本2種類・違反4件・新規仕様生成に成功と終了コード0が期待結果です。
ルートから同じ生成ZIPの検証を呼ぶ場合は、次のコマンドです。
npm run verify:patterns -- --id design/cli/cli-design --ci --timeout-ms 1200000
通常のZIP検証で確認する違反は、未知のCIファイル(STR-01-d)、リファレンスの手編集(STR-04-a)、禁止した動詞(NAM-04-a)、ヘルプの出力先の誤り(OPS-05-a)です。違反を入れる前の正常例が通り、違反を入れると非0と対応するエラーが返ることを一時コピーで確認します。
検査機構の保守では.foundation/bin/violation_probe.pyで全67件を再実行し、rules_check.py --final --no-writeでルールと結果の整合を確認します。収束評価の記録は元実装の評価であり、今回のZIP検証とは別です。
2026年10月21日、macOS 15.7.3、Python 3.14.2、GNU Make 3.81で確認しました。ZIP検証が導入するuvは0.13.3、全probeの再実行に使った導入済みuvは0.8.24です。掲載サイトはNode.js 24.9.0で検証しました。
| 対象 | 実施した確認と結果 |
|---|---|
| 生成ZIP | 別ディレクトリに展開して.ci/verify.pyが成功。環境準備、全検査、見本2種類、新規仕様の生成を確認 |
| 適合テスト | notesは510件、count-wordsは66件成功、失敗0件 |
| 違反検出 | 通常のZIP検証は代表4件に成功。検査機構の保守確認として全67件とmake checkへの組み込み6件も成功 |
| ルール検査 | rules_check.py --final --no-writeが成功。44ルール、エラー0件。元のルール文にある列挙表現の警告3件は残る |
| READMEの使用例 | 取得したZIPを空白のある別パスに展開し、標準入力、最小文字数、オプションの優先、適合テスト2種類を確認 |
| 掲載サイト | 配置確認・文書確認・共通テスト50件・型チェック・ビルド・ブラウザーE2E 6件が成功 |
| 実ページと配布 | PC(1440px)・モバイル(390px)の表示、一覧・ヘッダー・サイドバー・検索からの移動、補助設定の開閉、ZIP取得を確認。隠し設定を含む87ファイルを収録し、取得ZIPと生成物の一致を確認 |
制限環境ではuv導入時のネットワークアクセス、Chromiumの起動が拒否されました。また、共通E2Eの初回は準備サーバーの起動待ちで180秒を超えました。これらは成功に含めず、制限外で再実行して上表の成功を確認しています。E2Eの再現コマンドはNODE_OPTIONS=--max-old-space-size=8192 npm run test:e2eです。
GitHub Actions上のLinux環境、Go・Node.js・Rustでの実装、Claude Codeでの実際の対話とhooks起動、人間による説明・成果物の最終レビューは未確認です。WindowsのZIP検証は対応対象外として未実施です。元実装の収束評価は再実行していません。
参考資料
- Command Line Interface Guidelines:標準出力・標準エラー、JSON出力、命名などの指針。本パターン独自の制限とは区別します。
- Python 3.14 argparse:見本実装の引数解析。
- uvによるPythonの導入と管理:検査ツール用のPython系列の準備。
- uvの導入:uv本体の準備。
- ZIP内の
docs/design/rules.md・architecture.md・adr/:実装と対になる決定表、依存関係、採用理由。