AGENT SKILL

cli-design-review

cli-design の CLI の仕様(specs/<name>/cli.json)とその実装の変更をレビューする手順。差分、プルリクエスト、ブランチ、特定のファイルのレビューを頼まれたとき、また「この設計で問題ないか確認して」「ルールに沿っているか見て」「この実装は仕様どおりか見て」と頼まれたときは必ず使う。機械の検査を先に回し、機械で拾えないルールをルールIDごとに確かめ、固定の形式で指摘と判定を返す。

License 许可
MIT
最近更新
2026-11-07
Stars
★ 0
Forks
0

01 前言 Front Matter

name
cli-design-review
description
cli-design の CLI の仕様(specs/<name>/cli.json)とその実装の変更をレビューする手順。差分、プルリクエスト、ブランチ、特定のファイルのレビューを頼まれたとき、また「この設計で問題ないか確認して」「ルールに沿っているか見て」「この実装は仕様どおりか見て」と頼まれたときは必ず使う。機械の検査を先に回し、機械で拾えないルールをルールIDごとに確かめ、固定の形式で指摘と判定を返す。

03 SKILL.md 正文

cli-design のレビュー手順

指摘は、ルールの正本である docs/design/rules.md のルールIDに結び付ける。ルールに無いことを理由に差し戻さない。レビュアーごとに基準が変わるのを防ぐためである。

1. 対象を決める

  • 指定があれば、それを対象にする
  • 指定が無ければ、未コミットの変更(git diff HEAD と未追跡のファイル)を対象にする
  • 未コミットの変更も無ければ、現在のブランチと基準のブランチの差分を対象にする
  • git が無ければ、specs/ の下で依頼に関係する CLI のディレクトリを対象にする

対象のファイル一覧を、出力の「対象」節に書く。

2. 機械の検査を回す

make check を実行する。落ちたら、出力の要点(ルールIDと場所)を「機械の検査」節に載せる。機械が拾った違反を、人手の指摘として重複して書かない。対象に実装(この基盤の外)が含まれていれば、make conform SPEC=specs/<name>/cli.json CMD="<起動コマンドの絶対パス>" も回し、FAIL の行を載せる。

3. 抜け道を確かめる

ルールID 確認 見るもの
TOOL-03 保護ファイルの変更 .foundation/manifest.json の protected に当たるファイル(Makefile、tools/**、specs/*/released/**、.foundation/**、docs/design/rules.md など)が差分にあるか
TOOL-03 抑止の書き方 差分に、manifest の guard.suppressions のパターン(# noqa、# type: ignore、unittest.skip、skipTest(、expectedFailure)や、仕様の x-・_・$ で始まるキーがあるか
TOOL-03 テストの skip・削除 tools/clispec/tests/ のファイルの削除、テストの関数の削除
STR-04 生成物とリリース済みの仕様 specs/*/cli.md の差分が make fix の結果と同じか(make check の STR-04 で確かめる)。specs/*/released/ の既存のファイルが変わっていないか

4. 機械で拾えないルールを確かめる

rules.md で強制に review を含むルールは、3節かこの表の1列目に全部載っている。差分に関係する行を確かめる。

ルールID 確認方法 違反の典型例
STR-04 specs/*/released/ の差分に、既存のファイルの変更・削除が無いか released/1.0.0.json の summary を直す
DEP-02 実装のオプション定義・環境変数の読み込みを、仕様の options・env と突き合わせる 実装だけにある --verbose、-l(--limit の別名)、NOTES_DEBUG
DEP-05 ファイルに書くコマンドについて、storage が data か、-o/--output を持つか export コマンドがカレントディレクトリに notes.csv を書くのに --output が無い
NAM-02 CLI 名が NAM-02 の表の順(依頼の指定 → 最初の名詞の複数形 → <動詞>-<目的語の複数形>)で選ばれているか。依頼文と name を突き合わせる 依頼は「ブックマークを管理する」なのに name が bm や bookmark-manager
CODE-02 各項目・オプションの型が値の意味に合うか 日付の項目が string、件数が string、選択肢を列挙した値が string
STATE-01 一度に複数件を消す・変える操作に -f/--force があるか。設定ファイル・対話の入力を前提にしていないか note purge に --force が無い
PROC-06 メジャーを上げる差分に、ユーザーの承認を書いた ADR が同じ変更にあるか version が 2.0.0 なのに docs/design/adr/ に新しいファイルが無い

配布用のci.jsonはSTR-01が許可するCIメタデータで、.ci/はその検証処理である(ADR 0008)。CLIの実装を基盤の外に置く規約とは区別して確認する。

5. ファイルをまたぐ対応を確かめる

rules.md の PROC-02 の表の組ごとに、両側を開いて突き合わせる。

変更 突き合わせるもの 確かめ方
cli.json の変更 cli.md、version make check の STR-04 と PROC-06 が通っているか
型に項目を足す・変える create・edit のオプション、list の --sort 項目ごとに --<項目名の _ を - に替えた名前> が create・edit にあり、型・values が同じか(make check の NAM-07)
名詞に edit を足す 型の updated_at make check の NAM-02
環境変数を足す 同じ名前のオプション make check の STATE-01
依頼文 cli.json のコマンド・項目・オプション 依頼の操作・属性・絞り込みが全部あり、依頼に無いものが無いか。足りない・多いものは、該当する節のルールID(STR-02、NAM-07 など)で指摘する

6. 出力の形式

必ず次の形で出す。

# レビュー結果

## 判定
承認 または 差し戻し

## 対象
- <ファイルの一覧>

## 機械の検査
<check の結果。通った、または落ちた(要点)>

## 指摘
| # | ルールID | 場所 | 根拠(実際の記述) | 直し方 |
|---|---|---|---|---|
| 1 | <ID> | <パス>:<行> | `<該当の記述>` | <直し方> |

指摘が無ければ「なし」と書く。

## ルール追加の提案
<ルールには無いが、揺れや問題になりうる点。指摘とは分けて書く。無ければ「なし」>
  • 判定は機械的に決める。check が通り、かつ指摘が0件なら「承認」、それ以外は「差し戻し」
  • 指摘は場所の順に並べる
  • 同じ違反が複数の箇所にあれば、箇所ごとに1行ずつ書く

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