shadcn/improve — 高性能モデルで監査・計画し安価モデルに実装させるエージェントスキル

概要

shadcn/improve は、大規模言語モデル（LLM）を用いたソフトウェア開発において、「コードベースの理解と計画策定」と「実装の実行」を分離するためのエージェントスキルです。

近年、コーディングエージェントの利用が広がる一方で、最上位モデルをすべての実装ステップで稼働させるとコストやトークン消費が跳ね上がるという課題があります。一方で、安価な小型モデルに直接大まかな指示を出しても、リポジトリの前提条件や依存関係を見落として誤った実装を行うリスクがあります。

本プロジェクトの設計思想は「知性が積み重なる部分（コードベースの把握、優先度の判断、仕様の策定）には最も能力の高いモデルを充て、実装作業そのものは安価なモデルへ委託する」という点にあります。このスキル自体はソースコードを直接改変せず、成果物として厳密な実装計画（Markdown 形式の仕様書）を出力します。

エージェントを活用した開発プロセスのコスト効率を高めたい開発者や、コード監査とリファクタリングの計画を体系的に行いたいチームに向いています。

主な特徴

能力とコストに応じたモデルの役割分担 コードの文脈把握や仕様策定には高機能なモデルをアドバイザーとして使い、使い捨てのワークツリーにおけるコーディング作業は安価なモデルに委譲します。
9つの観点による並行監査 正確性（correctness）、セキュリティ、パフォーマンス、テストカバレッジ、技術的負債、依存関係・移行、開発者体験（DX）、ドキュメント、今後の方向性（direction）の9カテゴリについて、サブエージェントが並行してコードを精査します。
アドバイザー自身による誤検知の排除（Vet フェーズ） サブエージェントが過剰に指摘を上げる傾向を踏まえ、アドバイザーモデルが該当箇所（file:line）を直接再確認します。誤検知や誤った帰属を取り除き、棄却理由も記録して次回以降の重複報告を防ぎます。
機械的に実行可能な自己完結型の仕様書（Plans） 生成される仕様書は、文脈を共有していない小型モデルでも単独で実装できるよう、必要なファイルパス、現行コードの抜粋、検証用コマンド、作業中断条件（STOP 条件）が網羅されています。
安全な自動実行とテックリード視点でのレビュー /improve execute を実行すると、分離された Git ワークツリー内で安価なモデルが作業を行い、アドバイザーがテスト結果や差分をレビューして承認・差し戻し・計画見直しを判定します。
バックログの調整機能（Reconcile） /improve reconcile を通じて、完了した計画の維持確認、進行がブロックされた計画の再設計、コードベースの変化（ドリフト）に伴う仕様書の更新を自動で行います。

使い方

インストール

Agent Skills 形式をサポートしているエージェント環境で、以下のコマンドを実行して追加します。

npx skills add shadcn/improve

基本的な利用手順

コードベースの監査 エージェント上でリポジトリを開き、/improve（または低コストな /improve quick）を実行します。
指摘事項の選択 リポジトリの調査と監査が行われ、指摘一覧のテーブル（影響度、工数、確信度など）が返されます。計画化したい項目を「plan 1, 3 and 5」のように返信します。
仕様書の確認 plans/ ディレクトリ内に、推奨順序のインデックスとともに個別の仕様書ファイル（例: 001-fix-n-plus-one.md）が出力されます。
実装の実行 生成された仕様書は人間や他のエージェントに直接渡して実装させることも可能です。また、/improve execute 001 を実行することで、スキル側に安価なモデルのディスパッチと成果物レビューを任せることもできます。最終的なブランチのマージ判断は開発者自身が行います。
バックログの整理 次のセッションで /improve reconcile を実行し、すでにマージされたものの検証や、コードの変更によって生じたズレの更新を行います。

主なコマンド一覧

README で示されているコマンド例は以下の通りです。

/improve                        完全な監査 → 優先度付き指摘一覧 → 計画作成
/improve quick                  軽量パス: ホットスポットや上位指摘のみ
/improve deep                   徹底調査: 全パッケージ・全カテゴリを精査
/improve security               セキュリティに特化した監査（perf、tests、bugs 等も指定可）
/improve branch                 現在のブランチで変更された範囲のみを監査
/improve next                   機能提案（リポジトリの方向性に関する提案）
/improve plan <description>     監査をスキップし、単一の要件を仕様化
/improve review-plan <file>     既存の仕様書をレビュー・改善
/improve execute                安価な実行者を割り当て、成果物をレビュー
/improve reconcile              バックログの更新（検証、ブロック解除、完了分の整理）
/improve ... --issues           作成した計画を GitHub Issues としても公開

プルリクエストの作成前には、変更差分のみを対象とする /improve branch を実行することも推奨されています。

技術的なポイント

監査と優先度付けのパイプライン

shadcn/improve は、以下のフェーズに沿って処理を進めます。

Recon（偵察・把握） リポジトリの技術スタック、規約、ビルド・テスト・リント用コマンドを把握します。また、リポジトリ内に存在する ADR（docs/adr/）、PRD、CONTEXT.md、DESIGN.md、PRODUCT.md などの設計・意図ドキュメントを読み込みます。これにより、既定のトレードオフを誤って指摘することを防ぎ、プロジェクト本来の意図に沿った提案を組み立てます。
Audit（監査） サブエージェントが9つのカテゴリに分かれて調査し、すべての指摘に file:line の証拠、影響度、工数、確信度を付与します。
Vet（検証） サブエージェントの報告内容をアドバイザーが再確認し、ノイズを排除します。
Prioritize（優先度付け） 「レバレッジ（影響度 ÷ 工数、確信度で重み付け）」に基づいて指摘一覧を表形式で整列します。
Plan（計画策定） 選択された指摘に対し、依存関係グラフと優先度順インデックスを含む単一の Markdown 仕様書を plans/ に書き出します。

実行可能性を高める仕様書設計

仕様書は、事前知識を持たない小型モデルでもミスなく遂行できるよう、以下の3つの特性を持って出力されます。

自己完結性（Self-contained） 正確なファイルパス、現状コードの抜粋、リポジトリ内の模範コード例、検証済みコマンドがすべてファイル内に記載されます。
検証ゲート（Verification gates） 各ステップの末尾に実行すべきコマンドと期待される出力が定義されており、実行者が主観で完了を判断する必要がありません。
厳密な境界線（Hard boundaries） 対象外（Out of scope）の範囲を明示し、想定と異なる状態を発見した際に処理を中断して報告する「STOP 条件」を定めています。

また、仕様書には作成時点の Git コミットハッシュが記録され、実行前に機械的なドリフト（差分の乖離）チェックが行われます。

厳格な安全ルール（Hard rules）

安全性を考慮し、スキルには以下の制約が組み込まれています。

スキル自身が作業ツリーのソースコードを書き換えることはなく、書き込みは plans/ のみに行われます。
実行フェーズ（execute）における変更も使い捨ての Git ワークツリー内でのみ行われ、作業ツリーを汚染しません。
ファイル検索や読み取り専用の解析のみを行い、破壊的なコマンドは実行しません。
シークレット（秘密鍵やパスワードなど）の値を仕様書に再出力せず、場所と認証情報の種別のみを記録してローテーションを推奨します。
実装作業を直接求められても拒否し、仕様書の作成または execute の利用を促します。

注意点

ライセンス MIT ライセンスのもとで公開されています。
対応環境 Agent Skills 規格（agentskills.io）に準拠したエージェント環境が必要です。お使いの開発環境やエージェントツールが同規格に対応しているか事前に確認する必要があります。
モデル構成とコスト ツールの効果を最大限に引き出すには、指示を出すアドバイザー側に高い推論能力を持つモデルを割り当て、実行側に安価なモデルを割り当てる環境設定を意識する必要があります。
実装言語に関する情報 GitHub のメタデータ上、リポジトリの主な実装言語は「不明」となっており、README からも内部実装言語の詳細や依存関係の詳細は明記されていません。

まとめ

shadcn/improve は、コード監査と計画立案に最上位モデルを充て、実装を小型・安価なモデルに任せるためのエージェントスキルです。検証コマンドや停止条件を盛り込んだ自己完結型 Markdown 仕様書を生成することで、エージェント運用のコスト削減と品質維持の両立を支援します。Agent Skills 対応環境で AI コーディングワークフローの改善を検討している方は、導入を試してみてはいかがでしょうか。