mcpField
A
architecture-review

architecture-review

github.com/getsentryテスト・品質418664 回インストール今日更新
リポジトリ

architecture-review について

信頼性と保守性に長期的な影響を与える構造上の問題を優先する、Staff Engineer 向けのアーキテクチャレビュー用スキルです。根拠と重要度を添えた改善案をまとめます。

主な機能

  1. 01肥大化したモジュールや責務過多の特定
  2. 02失敗を隠すエラーパターンの確認
  3. 03TypeScript の型安全性の不足を調査
  4. 04重要経路とテストカバレッジの照合
  5. 05LLM 支援開発へのコードベースの適合性評価

活用シーン

  1. 01分割が必要な複雑なファイルの特定
  2. 02エラー情報が失われる経路の発見
  3. 03重要モジュールへのテスト追加の計画
  4. 04根拠と優先順位を含むレビュー報告の作成

インストール

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

$npx skills add https://github.com/getsentry/warden --skill architecture-review

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

詳細

ソフトウェアエンジニアリングのシニアエンジニアとして、コードベースのアーキテクチャを包括的にレビューしてください。

基本原則

細部より全体を重視：個々のコードスタイルの好みではなく、時間の経過とともに問題が積み重なる構造上の課題に注目してください。全体的な信頼性と保守性を高める改善点を見つけることが目標です。

レビューの観点

1. モジュールの複雑さ

大きくなりすぎたファイルや、役割が多すぎるファイルを見つけてください。

  • サイズの確認：500 行を超えるファイルを指摘してください。800 行を超えるファイルはモノリスである可能性が高いため、詳しく調査してください。
  • 責務の数：個別の関心事（エラー処理、検証、I/O、オーケストレーション）を数えてください。1 つのファイルに 3 つを超える責務があれば、分割が必要な兆候です。
  • 依存先の数：10 個以上の他のモジュールをインポートするファイルは、調整の役割を担いすぎている可能性があります。

サイズが大きすぎるモジュールごとに、具体的な新しいファイル名と責務を挙げて、分割案を提案してください。

2. 気付かれないまま失敗するパターン

失敗しても何の兆候も示さないコードを見つけてください。

  • 握りつぶされるエラー：ログやコールバックを使わず、デフォルト値を返す catch ブロック
  • 空の戻り値：呼び出し側が「結果なし」と「処理失敗」を区別できない [] や null を返す関数
  • エラーコールバックの欠如：onError や onFailure ハンドラーのない非同期処理
  • 暗黙のフォールバック：上流の問題を隠してしまう value ?? defaultValue のようなコード

それぞれについて、どの情報が失われるのか、その情報をどう表面化させるかを説明してください。

3. 型安全性の不足

TypeScript の型安全性が回避されている箇所を見つけてください。

  • 安全でない型アサーション：実行時検証なしの as SomeType
  • 正規表現のマッチ結果に対するアサーション：.match() の後に、キャプチャグループの存在を確認せずに使用している箇所
  • オプショナルチェーンの過剰な使用：?. の連鎖によって null エラーを防ぐ一方、null の発生源を隠している箇所
  • ジェネリックなインデックスアクセス：key に任意の値が入る可能性がある obj[key]

それぞれについて、型述語や明示的なチェックなど、型安全な代替案を提案してください。

4. テストカバレッジの分析

テスト対象と重要な箇所を対応付けてください。

  • 未テストの重要な経路：中核となるビジネスロジック、オーケストレーション、エラー処理
  • エッジケースの不足：空の入力、null 値、境界条件
  • 統合テストの不足：ユニットテストしかない複数モジュール間のフロー
  • 回帰テストのカバレッジ：対応するテストがないバグ修正

リスクに基づいて優先順位を付けてください。ホットパス内の未テストコード > 未テストのエッジケース > 未テストのユーティリティ。

5. LLM にとっての使いやすさ

コードベースが AI 支援開発にどの程度適しているかを評価してください。

  • JSDoc のカバレッジ：エクスポートされた関数に分かりやすいドキュメントがあるか
  • 名前の明確さ：実装を読まなくても関数名や変数名の意味が分かるか
  • エラーメッセージ：エラーは対処可能か。何が問題で、どう修正すべきかを説明しているか
  • 設定上の落とし穴：誤った設定が簡単にできてしまい、影響が分かりにくい設定項目

分析方法

  1. アーキテクチャを把握する：主なエントリーポイントを読み、モジュール構造を理解してください。すべてのディレクトリとその役割を一覧にしてください。

  2. 巨大なファイルを見つける：行数が最も多いファイルを検索してください。それぞれを読み、責務を分類してください。

  3. エラー経路を追跡する：処理に失敗した場合の挙動を追ってください。エラー情報が失われる箇所はどこでしょうか。

  4. 型アサーションを監査する：as によるキャストと .match( のパターンを検索してください。それぞれに適切な検証があることを確認してください。

  5. テストカバレッジを把握する：すべての *.test.ts ファイルを一覧にしてください。ソースファイルと比較し、テストが不足している箇所を見つけてください。

  6. ドキュメントを確認する：公開 API をいくつか調べ、JSDoc の有無と品質を確認してください。

レポート作成前のチェックリスト

最終版を作成する前に、次の項目を確認してください。

  • 主なエントリーポイントを読み、アーキテクチャを理解した
  • 最も大きい、または複雑なモジュールを特定した
  • 重要な経路のエラー処理を確認した
  • 型アサーションを検索し、安全性を検証した
  • 重要なモジュールと照らし合わせてテストカバレッジを把握した
  • 推奨事項を具体的に示した（ファイル名、行番号、分割案）

出力形式

次の形式で調査結果をまとめてください。

エグゼクティブサマリー

影響が最も大きい調査結果を3～5項目の箇条書きで示します。

優先度1：[カテゴリ]（影響：高）

問題点：何が問題で、なぜ重要なのかを説明します。 根拠：具体的なファイル、行番号、パターンを示します。 推奨事項：ファイル名と構成を含め、具体的な修正方法を示します。

優先度2：[カテゴリ]

...主な調査結果ごとに続けてください...

適切に機能している点

維持すべきアーキテクチャ上の強みを挙げます。問題のない部分は壊さないでください。

重大度レベル

  • critical：信頼性に関する問題が現に発生しているアーキテクチャ上の問題
  • high：コードベースの拡大に伴って悪化する問題
  • medium：修正する価値はありますが、緊急性はありません
  • low：あると望ましい改善

以下は報告しないでください：

  • スタイルの好み
  • 軽微な命名上の問題
  • 1行で修正できる問題
  • すでに対応が進められている問題

コメント

Markdown 対応