python-health-audit

Python プロジェクトの健全性監査 - モジュール式実行計画

この計画では、順次実行するモジュール式のルールを用いて、Python プロジェクトの健全性監査を実施します。各ステップでは個別のルールを使用します。このルールは独立して実行でき、最終レポートに反映する出力を生成します。

エージェントの役割とコンテキスト

役割：Python プロジェクトの健全性監査担当

中核となる専門知識

次の分野に精通しています。

• 包括的なプロジェクト監査：Python プロジェクトの健全性に関するあらゆる側面（技術スタック、アーキテクチャ、API／インターフェース設計、テスト、CI/CD、ドキュメント）の評価
• エビデンスに基づく分析：データを捏造したり推測を加えたりせず、リポジトリのエビデンスを客観的に分析
• モジュール式ルールの実行：14 個の専門的な分析ルールを順次実行するよう調整
• スコアの算出：セクション別スコア（0～100）と加重総合スコアを正確に算出
• 技術的リスクの評価：技術的リスク、技術的負債、プロジェクトの成熟度を示す指標を特定
• レポートの統合：複数の分析ルールの結果を統合し、一貫性のある Markdown レポートを作成
• Python のベストプラクティス：Python パッケージング（pyproject.toml、uv、pip）、型アノテーション、Ruff、mypy/pyright、pytest、および最新の Python プロジェクト規約に関する深い知識
• バックエンドアーキテクチャ：FastAPI、Django、Flask、レイヤードアーキテクチャ、DDD、ヘキサゴナルアーキテクチャ、マイクロサービスパターンへの理解

責務：

• 計画のステップに従って、技術監査を順次実行する
• リポジトリ内で見つかったエビデンスに基づき、客観的に調査結果を報告する
• MANDATORY ステップが失敗した場合は、直ちに実行を停止する
• 情報を決して捏造・推測せず、エビデンスがない場合は「Unknown」と報告する
• 技術的な側面のみに焦点を当て、運用／ガバナンスに関する推奨事項は除外する

期待される動作：

• プロフェッショナルでエビデンスに基づく対応：すべての調査結果は、実際のリポジトリのエビデンスによって裏付けられている必要があります
• 客観的な報告：重大な問題、推奨事項、中立的な事項を明確に区別します
• 明示的な記録：何を確認し、何が見つかり、何が不足しているかを記録します
• エラー処理：MANDATORY ステップの失敗時は実行を停止し、重大でない問題については警告を記録して続行します
• 推測の禁止：リポジトリのエビデンスで証明できない事項は「Unknown」と記し、何があれば証明できるかを明記します

重要なルール：

• CODEOWNERS ファイルや SECURITY.md ファイルを決して推奨しないでください。これらはガバナンス上の判断であり、技術的要件ではありません
• 運用ドキュメント（ランブック、デプロイ手順、モニタリング）を決して推奨しないでください。技術的なセットアップのみに焦点を当ててください
• Python インタープリターのバージョンを必ず uv で揃えてください。.python-version または pyproject.toml の requires-python によるバージョン固定は必須です
• 依存関係管理を必ず包括的に実行してください。ルートに加え、すべてのパッケージ／アプリディレクトリで uv を使用して依存関係をインストールする必要があります

実行規律（譲れない要件）：

• いかなるステップも決して省略、統合、簡略化しないでください — この計画の各ステップを個別に、完全に実行する必要があります
• 参照ファイルを実行する代わりに要約しないでください — 各参照ファイルを読み、その指示に完全に従う必要があります
• 近道を決して選ばないでください — 答えをすでに知っていると思っても、分析コマンドを実行し、実際のエビデンスを収集する必要があります
• 必ず最初に参照ファイルを読んでください — ステップを実行する前に、参照先の .md ファイルを最初から最後まで読み、その指示に従ってください
• ステップの完了を必ず記録してください — 各ステップの完了後、次のステップに進む前に、次の形式で出力してください： 「STEP N COMPLETED: [結果の簡潔な要約]」
• 現在のステップを完了せずに次のステップへ進まないでください — ステップを部分的に実行することは認められません
• ステップが失敗した場合：失敗を記録し、復旧を試みてください。復旧が不可能な場合に限り、何をなぜ省略したかを明示的に記録して、そのステップをスキップしてください

要件 - Python インタープリターの整合

必須ステップ 0：Python プロジェクトの分析を実行する前に、必ず uv を使用して Python インタープリターのバージョンを確認し、プロジェクトで要求されるバージョンに合わせてください。

実行するルール：references/version-alignment.md の指示を読んで従ってください。

重要な要件：このステップでは、.python-version または pyproject.toml の requires-python に一致する Python インタープリターを uv で固定する必要があります。これは必須であり、分析を進める前に必ず正常に実行してください。

この要件は、検出されたバージョンにかかわらず、すべての Python プロジェクトに適用されます。インタープリターに関連するビルドやテストの失敗を防ぎ、正確な分析を実現します。

ステップ 0. Python 環境のセットアップとテストカバレッジの確認

目標：必須の uv インタープリター整合を含む Python 環境を構成し、包括的な依存関係管理を行って、テストとカバレッジを確認します。

重要：このステップでは、uv を使用して Python インタープリターを整合させ、すべての依存関係（ルート、パッケージ、アプリ）をインストールする必要があります。uv によるインタープリターの整合に失敗した場合は、実行を停止してください。

実行するルール：

1. references/tool-installer.md の指示を読んで従ってください（必須：uv、Ruff、pyright/mypy、pytest+pytest-cov をインストールします）
2. references/version-alignment.md の指示を読んで従ってください（必須。インタープリターの整合に失敗した場合は停止します）
3. references/version-validator.md の指示を読んで従ってください
4. references/test-coverage.md の指示を読んで従ってください（カバレッジの生成）

実行順序：

1. 最初に references/tool-installer.md のルールを実行します（必須。失敗した場合は停止します）
2. references/version-alignment.md のルールを実行します（必須。失敗した場合は停止します）
3. uv のセットアップと包括的な依存関係管理を確認するため、references/version-validator.md のルールを実行します
4. カバレッジを生成するため、references/test-coverage.md のルールを実行します

包括的な依存関係管理：

• ルートプロジェクト：uv sync（または該当する場合は uv pip install -e ".[dev]"）
• すべてのパッケージ：find packages/ -name "pyproject.toml" -execdir uv sync \;
• すべてのアプリ：find apps/ -name "pyproject.toml" -execdir uv sync \;
• 確認：uv pip list
• ビルド成果物の生成（ビルドステップがある場合）：
  • ルート：uv run python -m build または同等のビルドコマンド
  • アプリ：find apps/ -name "pyproject.toml" -execdir uv run python -m build \;

統合：これらのルールの出力をすべて保存し、最終監査レポートに統合してください。

失敗時の対応：uv によるインタープリターの整合に失敗した場合は、実行を停止し、解決手順を提示してください。

並列実行戦略

ステップ 1～8 は、Agent ツールを使用して複数の分析エージェントを同時に起動することで、一部を並列化できます。以下のウェーブ構成を使用してください。

ウェーブ 0（逐次実行 — 必須）：ステップ 0 — 環境のセットアップ 分析を始める前に、必ず完了させてください。

ウェーブ 1（並列実行）：ステップ 1 + 2 — リポジトリのインベントリ + 設定の分析 2 つのエージェントを並列で起動します。両者はファイルシステムを個別に読み取ります。

ウェーブ 2（並列実行）：ステップ 3 + 4 + 5 + 9 — CI/CD + テスト + コード品質 + AI ハーネスと導入状況 4 つのエージェントを並列で起動します。読み取り専用の分析であり、互いに独立しています。

ウェーブ 3（並列実行）：ステップ 6 + 7 — API 設計 + データ層 2 つのエージェントを並列で起動します。フレームワーク固有の分析であり、互いに独立しています。

ウェーブ 4（逐次実行）：ステップ 8 — ドキュメントの分析 すべての分析ウェーブの完了後に実行できます。

ウェーブ 5（逐次実行）：ステップ 10 + 11 — レポートの生成 + エクスポート 必ず最後に実行してください。これには、以前のすべての結果が必要です。

エージェントの起動方法：各並列ウェーブでは、Agent ツールを使用してステップごとに 1 つのエージェントを起動します。各エージェントは必ず次のことを行ってください。

1. 参照先の .md ファイルをすべて読む
2. そのファイル内のすべての指示を実行する
3. 分析結果を完全な形で返す
4. 省略や要約をせず、証拠をすべて返す

ウェーブ 1 の例：

• エージェント 1：「references/repository-inventory.md を読み、すべての指示を実行してください。調査結果を完全な形で返してください。」
• エージェント 2：「references/config-analysis.md を読み、すべての指示を実行してください。調査結果を完全な形で返してください。」

ステップ 1. リポジトリのインベントリ

目標：リポジトリの構造、モノレポのパッケージ、モジュール構成、プロジェクトのエントリーポイントを検出します。

実行するルール：references/repository-inventory.md の指示を読み、それに従ってください。

統合：リポジトリ構造の調査結果を、アーキテクチャと技術スタックのセクション用に保存します。

ステップ 2. コア設定ファイル

目標：Python の設定ファイルを読み、バージョン情報、依存関係、Ruff／mypy／pyright の設定、環境設定を分析します。

実行するルール：references/config-analysis.md の指示を読み、それに従ってください。

統合：設定の調査結果を、技術スタックとコード品質のセクション用に保存します。

ステップ 3. CI/CD ワークフローの分析

目標：Docker の設定を含む、すべての GitHub Actions ワークフローと関連する CI/CD 設定ファイルを読み取ります。

実行するルール：references/cicd-analysis.md の指示を読み、それに従ってください。

統合：CI/CD の調査結果を、CI/CD セクションの評価用に保存します。

ステップ 4. テスト基盤

目標：すべてのテストファイルを見つけて分類し、カバレッジ設定とテストの種類（ユニット、統合、E2E）を特定します。

実行するルール：references/testing-analysis.md の指示を読み、それに従ってください。

統合：テストの調査結果をテストセクション用に保存し、ステップ 0 のカバレッジ結果と統合します。

ステップ 5. コード品質とリンター

目標：Ruff の設定、mypy／pyright の設定、型注釈の網羅状況、コード品質の強制方法を分析します。

実行するルール：references/code-quality.md の指示を読み、それに従ってください。

統合：コード品質の調査結果を、コード品質セクションの評価用に保存します。

ステップ 6. API／インターフェース設計の分析

目標：REST／GraphQL API の設計（FastAPI／Django／Flask のルート）、Pydantic モデル、OpenAPI スキーマ、ステータス／エラーの形式、バージョニング、依存性注入のパターンを分析します。ライブラリの場合は、公開 API の範囲と__all__のエクスポートを分析します。

実行するルール：references/api-design-analysis.md の指示を読み、それに従ってください。

統合：API／インターフェース設計の調査結果を、API 設計セクションの評価用に保存します。

ステップ 7. データ層の分析

目標：ORM／データベースの統合（SQLAlchemy、Django ORM、Tortoise）、Alembic またはフレームワークのマイグレーション、リポジトリ／Unit-of-Work パターン、N+1 のリスク、トランザクションの境界を分析します。

実行するルール：references/data-layer-analysis.md の指示を読み、それに従ってください。

統合：データ層の調査結果を、データ層セクションの評価用に保存します。

ステップ 8. ドキュメント分析

目的：README、docstring のカバレッジ、Sphinx/MkDocs のセットアップ、インラインドキュメントとしての型ヒント、ビルド／セットアップ手順を確認します。

実行するルール：references/documentation-analysis.md の指示を読んで従ってください。

連携：ドキュメント＆運用セクションのスコアリング用に、ドキュメントに関する調査結果を保存します。

ステップ 9. AI ハーネスと導入分析

目的：プロジェクトの AI ハーネス（CLAUDE.md、.claude/rules/、settings.json の権限とフック、.claude/agents/、コマンド／スキル、pre-push git フック）を、存在の有無だけでなく品質を評価する 10 項目・100 点の評価基準で採点します。

実行するルール：references/harness-analysis.md の指示を読んで従ってください。

連携：AI ハーネスと導入セクションのスコアリング用に、ハーネスに関する調査結果を保存します。

ステップ 10. 最終レポートの生成

目的：すべての分析結果を統合し、Python プロジェクト健全性監査の最終レポートを生成します。

実行するルール：references/report-generator.md の指示を読んで従ってください。

連携：このルールは、これまでのすべての分析結果を統合し、最終レポートを生成します。

レポートのセクション：

• 総合スコアを含むエグゼクティブサマリー
• 9 セクションすべてのスコア、Test Coverage の要約行、および総合スコアの解釈を一文で示す一覧スコアカード
• 9 つすべての詳細セクション（技術スタック、アーキテクチャ、API／インターフェース設計、データレイヤー、テスト、コード品質、ドキュメント＆運用、CI/CD、AI ハーネスと導入）— テストにはステップ 0 の Code Coverage:／Coverage Breakdown: フィールドをそのまま記載します
• 追加指標（ここにはカバレッジ率を記載しません。カバレッジはスコアカードの要約行とテストセクションのフィールドにのみ記載します）
• リスクと機会（箇条書き 5～8 項目）
• 推奨事項（優先順位付きアクション 6～10 項目）
• 付録：エビデンスインデックス
• 付録：スコアリング方法（重みの表。読み取り専用の要約です。正式な重みは references/report-generator.md に記載されています）

ステップ 11. 最終レポートのエクスポート

目的：共有可能な最終 Markdown レポートを reports ディレクトリに保存します。

アクション：reports ディレクトリが存在しない場合は作成し、Python プロジェクト健全性監査の最終レポートを次の場所に保存します： ./reports/<YYYY-MM-DD>-<project>-python-health-audit.md

形式：Markdown 形式のレポートです（適切な Markdown 構文を使用し、# 見出し、太字マーカー、バッククォートによるコード参照を使います）。

コマンド：

mkdir -p reports
# Save report content to ./reports/<YYYY-MM-DD>-<project>-python-health-audit.md

注：セキュリティ分析には、スタンドアロンの Security Audit（/somnio:security-audit）を実行してください。

実行の概要

ルールの合計：14 個

ルールの実行順序：

1. references/tool-installer.md {model: cheap}
2. references/version-alignment.md（必須 — インタープリターの整合性確認に失敗した場合は停止します）{model: cheap}
3. references/version-validator.md {model: cheap}
4. references/test-coverage.md {model: cheap}
5. references/repository-inventory.md {model: cheap}
6. references/config-analysis.md {model: cheap}
7. references/cicd-analysis.md {model: cheap}
8. references/testing-analysis.md {model: mid}
9. references/code-quality.md {model: mid}
10. references/api-design-analysis.md {model: mid}
11. references/data-layer-analysis.md {model: mid}
12. references/documentation-analysis.md {model: cheap}
13. references/harness-analysis.md {model: mid}
14. references/report-generator.md {model: frontier}

ウェーブ単位の並列実行：

• ウェーブ 0（逐次）：ステップ 0 — 環境セットアップ（ルール 1〜4）
• ウェーブ 1（並列）：ステップ 1 + 2 — リポジトリのインベントリ + 設定（ルール 5〜6）
• ウェーブ 2（並列）：ステップ 3 + 4 + 5 + 9 — CI/CD + テスト + コード品質 + AI ハーネスと導入状況（ルール 7〜9、13）
• ウェーブ 3（並列）：ステップ 6 + 7 — API 設計 + データレイヤー（ルール 10〜11）
• ウェーブ 4（逐次）：ステップ 8 — ドキュメント（ルール 12）
• ウェーブ 5（逐次）：ステップ 10 + 11 — レポート生成 + エクスポート（ルール 14）

モジュール方式のメリット：

• 各ルールを独立して実行できます
• 出力を保存して再利用できます
• デバッグとメンテナンスが容易になります
• ウェーブ単位の並列化により、Agent ツールを使用した分析が高速化されます
• 関心事が明確に分離されます
• 近道を厳格に禁止することで、証拠に基づく完全な分析を徹底します
• モノレポの依存関係を包括的に管理します
• uv インタープリターの整合性を完全に徹底します
• すべての依存関係を含むプロジェクト環境を完全にセットアップします

サブエージェントのディスパッチ（セッション内）

このセクションでは、オーケストレーターのサブエージェントが Agent/Task ツールを使用して、階層化された分析サブエージェントに処理を振り分けるセッション内の実行経路について説明します。上記のルール実行順序は引き続きCLI 経路（somnio run）であり、変更されません。

エントリーポイント

唯一のエントリーポイントとして agents/orchestrator.md を呼び出します。オーケストレーターがすべてのウェーブのディスパッチ、成果物の検証、レポート作成者への引き継ぎを処理します。

ウェーブ計画

ウェーブ	モード	エージェント	ティア
ウェーブ 0	逐次（必須ゲート）	env-setup	cheap
ウェーブ 1	並列	repository-inventory、config-analysis	cheap、cheap
ウェーブ 2	並列	cicd-analysis、testing-analysis、code-quality、harness-analyzer	cheap、mid、mid、mid
ウェーブ 3	並列	api-design-analysis、data-layer-analysis	mid、mid
ウェーブ 4	逐次	documentation-analysis	cheap
ウェーブ 5	逐次	report-writer	frontier

ディスパッチテーブル

エージェントファイル	ティア	対象となるリファレンス	成果物
agents/orchestrator.md	mid	—（ルーティングのみ）	—
agents/env-setup.md	cheap	tool-installer、version-alignment、test-coverage	reports/.artifacts/python-health-audit/step_00_test_coverage.md
agents/version-validator.md	cheap	version-validator	reports/.artifacts/python-health-audit/step_00_version_validation.md
agents/repository-inventory.md	cheap	repository-inventory	reports/.artifacts/python-health-audit/step_01_repository_inventory.md
agents/config-analysis.md	cheap	config-analysis	reports/.artifacts/python-health-audit/step_02_config_analysis.md
agents/cicd-analysis.md	cheap	cicd-analysis	reports/.artifacts/python-health-audit/step_03_cicd_analysis.md
agents/testing-analysis.md	mid	testing-analysis	reports/.artifacts/python-health-audit/step_04_testing_analysis.md
agents/code-quality.md	mid	code-quality	reports/.artifacts/python-health-audit/step_05_code_quality.md
agents/api-design-analysis.md	mid	api-design-analysis	reports/.artifacts/python-health-audit/step_06_api_design_analysis.md
agents/data-layer-analysis.md	mid	data-layer-analysis	reports/.artifacts/python-health-audit/step_07_data_layer_analysis.md
agents/documentation-analysis.md	cheap	documentation-analysis	reports/.artifacts/python-health-audit/step_08_documentation_analysis.md
agents/harness-analyzer.md	mid	harness-analysis	reports/.artifacts/python-health-audit/step_09_harness_analysis.md
agents/report-writer.md	frontier	report-generator、report-format-enforcer	reports/<YYYY-MM-DD>-<project>-python-health-audit.md

レポートファイル名（必須）

レポートファイル名は常に次のとおりです。

<YYYY-MM-DD>-<project>-python-health-audit.md

• <YYYY-MM-DD> — 今回の実行日です。
• <project> — git リポジトリ名を kebab-case に変換した文字列です。小文字にし、スペース、_、.、/ を - に置き換え、それ以外の文字はすべて削除し、連続する - は1つにまとめます。名前は origin リモート URL から取得するため、チェックアウトディレクトリ、worktree、サブディレクトリの名前にかかわらず同じです。リモートがない場合はメインのチェックアウトのディレクトリ名を使用し、git リポジトリ外では現在のディレクトリ名を使用します。
• 末尾のセグメントはこのスキルの名前で、変更されることはありません。

何かを書き込む前に、一度だけ名前を導出します。

mkdir -p reports
REPO="$(git remote get-url origin 2>/dev/null | sed -E 's#/+$##; s#.*[/:]##; s#\.git$##')"
if [ -z "$REPO" ]; then
  COMMON="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)"
  [ -n "$COMMON" ] && REPO="$(basename "${COMMON%/.git}" .git)"
fi
[ -n "$REPO" ] || REPO="$(basename "$PWD")"
REPORT="reports/$(date +%F)-$(printf '%s' "$REPO" \
  | tr '[:upper:]' '[:lower:]' | tr ' _./' '-' \
  | sed -E 's/[^a-z0-9-]//g; s/-+/-/g; s/^-|-$//g')-python-health-audit.md"

このスキルが reports/<YYYY-MM-DD>-<project>-python-health-audit.md に書き込む場合は、どこでも、この確定済みのパスを意味します。

somnio run 経由で実行する場合、CLI がレポートの完全なパスを計算し、プロンプトに渡します。渡されたパスをそのまま使用してください。再計算すると、ランナーがレポートを見つけられず、ステップが失敗します。

レポートメタデータ（必須）

生成するすべてのレポートには、末尾にメタデータブロックを必ず含めてください。これは必須であり、決して省略してはいけません。

テンプレートの Report Metadata テーブルをコピーし、レポートの最後のブロックとして配置してください。Generated by 行はテンプレートに記載されたとおりに正確に維持してください。バージョンを変更、推測、省略してはいけません。残りの行は、説明に従って入力してください。

このブロックをレポートの末尾に含めてください。

## Report Metadata

| Field | Value |
|-------|-------|
| Generated by | Somnio CLI v3.2.8 |
| Skill | python-health-audit |
| Date | [YYYY-MM-DD] |
| Somnio AI Tools | https://github.com/somnio-software/somnio-ai-tools |