mcpField
A
api-review

api-review

github.com/atholaテスト・品質343105 回インストール4 日前に更新
リポジトリ

api-review について

api-review は、公開 API の変更や新しい API 設計を確認し、リリース前にドキュメントの網羅性を監査するワークフロースキルです。API の一覧化、参考例の調査、一貫性チェック、根拠付きの指摘を組み合わせます。

主な機能

  1. 01公開 API の一覧化
  2. 02言語別の参考例調査
  3. 03API の一貫性監査
  4. 04ドキュメントとバージョン管理の確認
  5. 05指摘の記録と検証

活用シーン

  1. 01リリース前の公開 API 変更レビュー
  2. 02新しい API サーフェスの設計
  3. 03命名やエラー処理の一貫性確認
  4. 04ドキュメントや移行ノートの不足発見

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/athola/claude-night-market --skill api-review

インストール後、Claude Code で/api-reviewを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

modules/
consistency-audit.md
exemplar-research.md
surface-inventory.md

詳細

API レビューワークフロー

使用しない場合

  • 安定した公開インターフェースの背後にある内部リファクタリング（ pensive:code-refinement を使用）
  • 結合やレイヤー構造に関する検討（pensive:architecture-review を使用）

使用方法

このスキルは、公開 API の変更をレビューし、新しい公開インターフェースを設計し、一貫性を監査し、ドキュメントの網羅性を検証するために使用します。プロジェクトのガイドラインに沿っていることを確認するため、API をリリースする前に実行してください。

必須の進捗管理

  1. api-review:surface-inventory
  2. api-review:exemplar-research
  3. api-review:consistency-audit
  4. api-review:docs-governance
  5. api-review:evidence-log
  6. api-review:findings-verified

ワークフロー

ステップ 1：公開インターフェースの一覧化

言語ごとにすべての公開 API を一覧化します。安定性レベル、機能フラグ、バージョン管理メタデータを記録します。rg などのツールを使って公開シンボルを検索します（例：Rust の pub、Python のアンダースコアで始まらない def）。開始前に git status で作業ツリーの状態を確認してください。

ステップ 2：参考例の調査

該当する言語について、pandas、requests、tokio など、質の高い API リファレンスを少なくとも 2 つ特定します。監査の基準として役立てるため、名前空間、ページネーション、エラー処理、構成に関する各例のパターンを記録します。

ステップ 3：一貫性の監査

プロジェクトの API を、特定した参考例のパターンと比較します。命名規則、パラメーターの順序、戻り値の型、エラーの意味を分析します。重複、抽象化の漏れ、機能ゲートの欠如、ドキュメントの不足を特定します。

ステップ 4：ドキュメントのガバナンス

ドキュメントにエントリーポイント、クイックスタート、完全な API リファレンスが含まれていることを検証します。変更履歴と移行ノートが維持されていることを確認します。SemVer への準拠、安定性に関する保証、明確な非推奨化のスケジュールを確認します。rustdoc、Sphinx、OpenAPI などのツールを使って、ドキュメントが自動生成されていることを確認します。

ステップ 5：証跡ログ

実行したコマンドと調査結果をすべて記録します。最終的な推奨事項を「承認」「条件付きで承認」「差し止め」のいずれかでまとめます。担当者と期限を割り当てた具体的な対応事項を含めます。

API 品質チェックリスト

命名

一貫した規則に従い、言語固有の慣習に沿った、説明的な名前になっていることを確認します。

パラメーター

順序が一貫していることを検証し、省略可能なパラメーターに明示的なデフォルト値が設定されていることを確認します。型注釈がすべて揃っていることを確認します。

戻り値

戻り値のパターンに一貫性があるか分析します。エラーケースが文書化され、ページネーションが統一された構造になっていることを確認します。

ドキュメント

すべての公開 API に使用例が含まれ、変更履歴に最新の変更が反映されていることを確認します。

出力形式

最終レポートには、API の公開インターフェースの概要、エンドポイントと公開型の数値一覧、調査した参考例との整合性分析を含める必要があります。一貫性の問題とドキュメントの不足について、正確なファイル名と行番号を示して記録します。明確な判断と、期限を定めた対応計画で締めくくります。

各指摘は次の形式に従う必要があります。

[A1] Title
- Location: file.py:42
- Anchor: `verbatim source text at line 42`
- Issue: what is wrong | Fix: remediation | Evidence: [E1]

Anchor は Location にある正確なソーステキストであり、citation_verifier.py が再読み込みして指摘が実在することを証明するために使われます。

技術的な連携

再現可能なコマンド記録には imbue:proof-of-work を、指摘の形式化には imbue:structured-output を使用します。破壊的変更を評価する際は imbue:diff-analysis/modules/risk-assessment-framework を参照してください。

モジュールリファレンス

  • API のカタログ化パターンについては modules/surface-inventory.md を参照
  • API 標準の調査については modules/exemplar-research.md を参照
  • API 間の一貫性チェックについては modules/consistency-audit.md を参照
指摘の根拠を検証する（api-review:findings-verified）

指摘を .review/findings.json に書き込み、引用検証ツール（Skill(imbue:review-core) のステップ 5）を実行します。検証ツールが却下した指摘は削除するか、UNVERIFIED と表示します。

完了条件

  • 対象範囲の棚卸し、事例の調査、一貫性の監査、ドキュメントガバナンスの確認が完了し、証拠が記録されています。
  • 報告されたすべての指摘事項に、citation_verifier.py（終了コード 0）で確認された Location と逐語的な Anchor が付いているか、未検証の指摘事項が除外されるか UNVERIFIED と表示されています。

トラブルシューティング

監査コマンドが見つからない場合は、依存関係がインストールされており、システムの PATH からアクセスできることを確認してください。アクセスエラーが発生する場合は、ファイルのアクセス許可を確認してください。ツールが予期しない動作をする場合は、--verbose フラグを使用して実行ログを確認してください。

コメント

Markdown 対応