hyhmrright/brooks-lint

Portable AI code quality reviews for Codex, Cursor, Copilot and other coding agents: six Agent Skills for architecture, technical debt, tests and remediation.

概要

brooks-lint は、さまざまなエージェントプラットフォーム（Claude、Gemini、Codex、Cursor など）で AI を活用したコードレビューの「スキル」を実行できるツールです。構文やスタイルをリントするのではなく、著者が 12 冊の古典的なソフトウェア工学の書籍（例：人月の神話、クリーンアーキテクチャ、リファクタリング）から抽出した 6 つの劣化リスク次元に基づいて、本番コードとテストスイートを評価します。各リスクについて、構造化された所見を生成します。

症状 → 原因 → 結果 → 対策

各所見は元の書籍に引用され、重大度（🔴 重大、🟡 警告、🟢 提案）でラベル付けされ、全体的なヘルススコア（0〜100）に貢献します。このツールは、アーキテクチャ図（Mermaid）、負債ランキングテーブル、安全な修正を自動的に適用する「スイープ」モードも生成できます。

このパッケージは Agent-Skills として配布され、小さなインストーラスクリプトで多くの AI アシスタントプラットフォームにインストールできます。インストール後、6 つのスラッシュコマンド（/brooks-review、/brooks-audit など）を呼び出すか、アシスタントに「この PR をレビューして」と依頼します。

主な機能

機能	説明	重要性
6 つの劣化リスク次元	認知過負荷、変更伝播、知識重複、偶発的複雑さ、依存関係の混乱、ドメインモデルの歪み（さらに 6 つのテストスイートリスク）	行数指標を超えた、原理に基づいた書籍に裏付けられたコード健全性のビューを提供
構造化された所見	各問題は症状 → 原因 → 結果 → 対策として報告され、古典的な書籍への引用が含まれる	開発者とレビュアーにとってフィードバックを追跡可能で実用的にする
ヘルススコア（0〜100）	設定可能な厳格度プリセット（厳格、バランス、レガシー対応）を使用して重大度カウントを集約	PR、リリース、またはリポジトリ全体の迅速で比較可能な健全性指標を提供
アーキテクチャ監査	Mermaid 依存関係グラフを生成し、循環と Conway の法則の不一致を強調	リンターが見逃す高レベルの設計ドリフトを特定するのに役立つ
技術負債ロードマップ	所見を痛み × 広がりでランク付けし、重大 / 計画済み / 監視対象の層にグループ化	チームに段階的な改善のための具体的な計画を提供
テストスイート監査	テストの不明瞭さ、脆弱性、重複、モックの乱用、カバレッジの幻想、アーキテクチャの不一致をチェック	同じリスクモデルをテストコードベースに拡張
自動修正 / スイープモード	安全な単一ファイル修正を自動的に適用。大きな変更は手動レビューのために記録	低リスクの問題に対する手動作業を削減
マルチプラットフォーム Agent-Skills	単一のスクリプトで Claude、Gemini、Codex、Cursor、OpenCode、Windsurf、IBM Bob などにインストール可能	好みの AI アシスタントに関係なく、チームは同じレビューロジックを使用できる
ゼロ設定デフォルト	すぐに使用可能。オプションの `.brooks-lint.yaml` でカスタム厳格度、無効化されたリスク、無視パターンを設定可能	導入の障壁が低い

仕組み（高レベルフロー）

インストール – 提供された install.sh スクリプトをターゲットプラットフォーム名（例：bash scripts/install.sh codex）で実行します。スクリプトはスキルファイルをプラットフォームのスキルディレクトリにコピーします。
呼び出し – チャット/IDE で、スラッシュコマンド（/brooks-review）を発行するか、アシスタントに PR のレビューを依頼します。
モデル呼び出し – スキルは関連コード（差分、ファイル全体、または依存関係グラフ）を、6 つのリスク質問と引用スタイルをエンコードしたプロンプトとともに、基盤となる LLM（Claude、Gemini など）に送信します。
解析 – LLM は Markdown レポートを返します。brooks-lint のパーサーは各所見を抽出し、標準的なリスクコードにマッピングし、重大度カウントを計算します。
スコアリングと出力 – ツールはカウントをヘルススコアに集約し、オプションで Mermaid グラフをレンダリングし、構造化されたレポートをユーザーに返します。
オプションのスイープ – /brooks-sweep モードでは、ツールは自動化しても安全な「対策」ステップを適用しようとし、「修正ログ」と更新されたスコアを報告します。

典型的なユースケース

シナリオ	コマンド	得られるもの
プルリクエストレビュー	`/brooks-review`	変更されたファイルの劣化リスク所見のリスト。各所見には書籍の引用と修正アドバイス、および PR のヘルススコアが含まれます。
アーキテクチャ健全性チェック	`/brooks-audit`	Mermaid 依存関係グラフ、循環依存関係の警告、モジュール結合と依存関係の方向に関連するリスク所見。
技術負債トリアージ	`/brooks-debt`	ランク付けされた負債項目、痛み × 広がりスコア、ロードマップ（重大 / 計画済み / 監視対象）。
テストスイート健全性	`/brooks-test`	テストコードに固有の所見（不明瞭さ、脆弱性、モックの乱用など）と、テストのリファクタリングの提案。
クイック健全性スナップショット	`/brooks-health`	すべての次元にわたる複合ヘルススコア – リリース前やオンボーディングに役立ちます。
自動クリーンアップ	`/brooks-sweep`	安全な修正を自動適用し、修正ログを生成し、ヘルススコアの変化を表示します。

インストールクイックスタート

# Codex CLI プラットフォームの例
curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh \
  | bash -s -- codex

スクリプトはスキルファイルを適切な ~/.codex/skills（または同等の）フォルダにコピーし、6 つのスラッシュコマンドを登録します。Claude Code、Gemini CLI、または他のリストされたエージェントの場合は、codex をプラットフォーム名に置き換えます。

Claude Code の手動インストールを希望する場合：

mkdir -p ~/.claude/skills/brooks-lint
cp -r skills/* ~/.claude/skills/brooks-lint/

インストール後、アシスタントに「この PR をレビューして」と依頼するか、スラッシュコマンドのいずれかを実行します。

設定（オプション）

リポジトリのルートに .brooks-lint.yaml を作成して動作を調整します：

version: 1
strictness: balanced   # strict | balanced (デフォルト) | legacy-friendly
disable:
  - T5                 # カバレッジ指標チェックをスキップ
severity:
  R1: suggestion       # 認知過負荷の所見をダウングレード
ignore:
  - "**/*.generated.*"
  - "**/vendor/**"

strictness はヘルススコアの計算方法を変更します。
disable は特定のリスクカテゴリをオフにできます。
severity は特定のプロジェクトのリスクを再ラベル付けできます。
ignore は glob パターンを使用して生成ファイルやベンダーファイルを除外します。

制限事項と未解決の問題

制限	詳細
LLM の品質への依存	所見の正確性は基盤となるモデル（Claude、Gemini など）に依存します。リポジトリは決定的な解析ベンチマークを提供しますが、所見の意味的正確性は依然としてモデルに依存します。
プラットフォーム検証	メンテナーは Claude Code のテストが実行されなくなったと述べています。Codex 関連の機能のみが積極的に検証されています。他のプラットフォームでのコミュニティテストが推奨されます。
言語に依存しないが言語を認識しない	brooks-lint はコードをテキストとして扱うため、どの言語でも機能しますが、言語固有の AST 情報を活用できないため、言語を認識する静的解析ツールと比較して一部のパターンを見逃す可能性があります。
ベンチマーク数値は参考用	README はベンチマークテーブルが「参考用」であり、実際の評価数値は変わる可能性があると述べています。
従来のリンターの代替ではない	ESLint、Pylint、静的解析スイートなどのツールを補完することを目的としており、置き換えるものではありません。

誰が恩恵を受けるか？

エンジニアリングマネージャー は、複数のリポジトリにわたる高レベルの健全性指標を探しています。
Dev-ops / CI パイプライン は、マージ前に AI 駆動の品質ゲートを望んでいます。
個人開発者 は、元のテキストを読まなくても、実用的で書籍に裏付けられたレビューコメントを望んでいます。
複数の AI アシスタントを使用するチーム – 同じスキルが Claude、Gemini、Codex、Cursor などで機能し、一貫したフィードバックを提供します。

結論

brooks-lint は、古典的なソフトウェア工学の知恵と最新の LLM ベースのコードレビューを橋渡しします。6 つの明確に定義された劣化リスクにわたって構造化された引用豊富な所見を提供し、複合ヘルススコアを生成し、安全な修正を自動適用することもできます。従来のリンターを置き換えるものではありませんが、多くの AI 支援レビュアーが見逃すアーキテクチャおよび設計レベルの洞察の貴重な層を追加します。

上記のすべての情報はリポジトリの README から直接取得したものです。外部の仮定は追加されていません。