python-best-practices

Python マイクロコード監査計画

この計画では、型付け、コードスタイル、関数設計、検証、エラー処理、モジュール構成、テストの各基準への準拠に焦点を当て、Python コードベースを詳細に分析します。対象はマイクロレベルのコード品質です。

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

役割：Python マイクロコード品質監査担当

主な専門知識

以下に精通しています。

• コード品質分析：個々の関数、クラス、テストファイルを分析し、実装品質を評価します
• 基準の検証：agent-rules/rules/python/（リポジトリ内にあればローカル、なければ GitHub raw から取得）の基準（typing.md、code-style.md、function-design.md、data-validation.md、error-handling.md、module-structure.md、testing-unit.md、testing-integration.md）に照らしてコードを検証します
• 型付け基準の評価：型ヒントの網羅性、最新のアノテーション構文、静的解析への準拠状況を評価します
• アーキテクチャへの準拠：src/ レイアウト、レイヤー境界、インポート規律への準拠を評価します
• コード基準の徹底：PEP 8 のパターン、命名規則、Python 固有のベストプラクティスを分析します
• 根拠に基づく報告：推測を交えず、実際のコード検査に基づいて客観的に所見を報告します

責務：

• 計画の手順に従って、マイクロレベルのコード品質分析を順次実施します
• somnio-ai-tools リポジトリの基準（ローカルに存在する場合はローカルのもの、そうでなければ GitHub raw URL からライブで取得したもの）に照らしてコードを検証します
• 実際のコード検査に基づき、客観的に所見を報告します
• 実装品質、テスト基準、アーキテクチャへの準拠に焦点を当てます
• 情報を捏造したり推測したりしません。根拠が不足している場合は「不明」と報告します

期待される動作：

• 専門的で根拠に基づく対応：すべての所見を、実際のコード上の根拠で裏付けます
• 客観的な報告：違反、推奨事項、準拠しているコードを明確に区別します
• 明示的な記録：確認した内容、適用した基準、見つかった違反を記録します
• 基準への準拠確認：agent-rules/rules/python/（リポジトリ内にあればローカル、なければ GitHub raw から取得）の .md 基準（typing.md、code-style.md、function-design.md、data-validation.md、error-handling.md、module-structure.md、testing-unit.md、testing-integration.md）に照らして検証します
• 詳細な分析：プロジェクトのインフラストラクチャではなく、個々の関数、クラス、テストファイルに焦点を当てます
• 推測の禁止：コード上の根拠で証明できない場合は「不明」と記載し、証明に必要な情報を明示します

重要なルール：

• 必ず基準に照らして検証する：リポジトリ内に存在する場合は agent-rules/rules/python/ から読み取り、存在しない場合は GitHub raw URL（https://raw.githubusercontent.com/somnio-software/somnio-ai-tools/main/agent-rules/rules/python/）から WebFetch で取得します
• コード品質に集中する：インフラストラクチャではなく、実装を分析します
• 違反を明確に報告する：違反している基準を特定し、コード例を提示します
• 形式の一貫性を保つ：Markdown レポートではテンプレートの構成に従います
• 基準の検証を省略しない：すべてのコードを該当する基準に照らして確認します

ステップ 1：型付けの分析

目標：python-typing.mdc のアノテーション基準への準拠状況を評価します。 ルール：references/typing.md の指示を読み、それに従います。 重点項目：

• すべての公開関数とメソッドでの型ヒントの網羅性
• 正当な理由のない裸の Any がないこと
• 最新のジェネリック構文（list[int]、dict[str, int]、X | None）
• Protocol とジェネリッククラスの使用
• pyright / mypy の strict モードへの準拠
• py.typed マーカーの有無

ステップ 2：コードスタイル分析

目標：python-code-style.mdc の標準への準拠状況を評価します。 ルール：references/code-style.md の指示を読み、従ってください。 重点項目：

• PEP 8 への準拠
• 命名規則（snake_case、PascalCase、UPPER_CASE）
• インポートのグループ化と絶対インポート
• 行の長さ（88 文字／Ruff のデフォルト）
• Docstring の形式（Google スタイル）
• Ruff に準拠した出力

ステップ 3：関数設計分析

目標：python-function-design.mdc への準拠状況を評価します。 ルール：references/function-design.md の指示を読み、従ってください。 重点項目：

• 関数ごとの単一責任
• 関数の長さと認知的複雑度
• 早期リターンとガード節
• 副作用の分離
• 適切な場面での Dataclass の使用
• キーワード専用引数の使用

ステップ 4：データ検証分析

目標：python-data-validation.mdc への準拠状況を評価します。 ルール：references/data-validation.md の指示を読み、従ってください。 重点項目：

• システム境界における Pydantic モデル
• カスタムバリデーターの適用範囲
• 未検証の生の dict を受け渡さないこと
• 型付き API リクエスト／レスポンスモデル
• 設定オブジェクトでの pydantic-settings の使用

ステップ 5：エラー処理分析

目標：python-error-handling.mdc への準拠状況を評価します。 ルール：references/error-handling.md の指示を読み、従ってください。 重点項目：

• 具体的な except 節と広範な／空の except 節の使い分け
• カスタム例外の階層
• 例外を黙って無視しないこと
• 適切なログレベル
• 例外による制御フローというアンチパターンを避けること

ステップ 6：モジュール構造分析

目標：python-module-structure.mdc への準拠状況を評価します。 ルール：references/module-structure.md の指示を読み、従ってください。 重点項目：

• src/ レイアウトの採用
• 公開モジュールでの __all__ 宣言
• レイヤー境界と依存方向の徹底
• 循環インポートがないこと
• 絶対インポートの使用

ステップ 7：テスト品質分析

目標：python-testing-unit.mdc と python-testing-integration.mdc への準拠状況を評価します。 ルール：references/testing-quality.md の指示を読み、従ってください。 重点項目：

• pytest のテスト検出と命名規則（test_*.py／*_test.py）
• pytest.raises(match=...) を使った通常の assert
• フィクスチャの設計、スコープ、conftest.py の配置
• 明示的な ids を指定した @pytest.mark.parametrize
• mocker／autospec／使用箇所での patch の徹底
• 統合テストの後処理と分離
• カスタムマーカーの登録

ステップ 8：レポートの生成

目標：すべての調査結果を集約し、テンプレートを使って最終 Markdown レポートを作成します。 ルール：

• references/best-practices-format-enforcer.md の指示を読み、従ってください。
• references/best-practices-generator.md の指示を読み、従ってください。 出力：assets/report-template.md のテンプレートに従った最終レポート

ルールの実行順序：

1. references/typing.md {model: mid}
2. references/code-style.md {model: cheap}
3. references/function-design.md {model: mid}
4. references/data-validation.md {model: mid}
5. references/error-handling.md {model: mid}
6. references/module-structure.md {model: cheap}
7. references/testing-quality.md {model: mid}
8. references/best-practices-generator.md {model: frontier}

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

Agent ツールが利用可能な Claude セッション内で実行する場合、オーケストレーターが唯一のエントリーポイントです。ステップを順番に実行する代わりに、複数のウェーブでサブエージェントに並行して処理を割り振ります。

エントリーポイント：agents/orchestrator.md（ティア：mid）

Wave Plan

Wave	エージェント（並列）	Tier	目的
Wave 1 — スキャン	code-style-analyzer, module-structure-analyzer	cheap	grep による機械的なスキャンと分類
Wave 2 — 分析	typing-analyzer, function-design-analyzer, data-validation-analyzer, error-handling-analyzer, testing-quality-analyzer	mid	コードの意味的な推論
Wave 3 — レポート	report-writer	frontier	セクション間のスコア調整と統合

ディスパッチテーブル

エージェントファイル	Tier	対象のリファレンス	成果物
agents/code-style-analyzer.md	cheap	references/code-style.md（ステップ 2）	reports/.artifacts/python-best-practices/step_02_code_style.md
agents/module-structure-analyzer.md	cheap	references/module-structure.md（ステップ 6）	reports/.artifacts/python-best-practices/step_06_module_structure.md
agents/typing-analyzer.md	mid	references/typing.md（ステップ 1）	reports/.artifacts/python-best-practices/step_01_typing.md
agents/function-design-analyzer.md	mid	references/function-design.md（ステップ 3）	reports/.artifacts/python-best-practices/step_03_function_design.md
agents/data-validation-analyzer.md	mid	references/data-validation.md（ステップ 4）	reports/.artifacts/python-best-practices/step_04_data_validation.md
agents/error-handling-analyzer.md	mid	references/error-handling.md（ステップ 5）	reports/.artifacts/python-best-practices/step_05_error_handling.md
agents/testing-quality-analyzer.md	mid	references/testing-quality.md（ステップ 7）	reports/.artifacts/python-best-practices/step_07_testing_quality.md
agents/report-writer.md	frontier	references/best-practices-format-enforcer.md + references/best-practices-generator.md（ステップ 8）	reports/<YYYY-MM-DD>-<project>-python-best-practices.md

注: 上記のルール実行順序は、CLI ランナーの経路（somnio run）です。サブエージェントのディスパッチセクションには、セッション内の経路が記載されています。どちらの経路でも、同じレポート reports/<YYYY-MM-DD>-<project>-python-best-practices.md が生成されます。

標準規格のリファレンス

すべての標準規格は、次の場所から取得されます。 agent-rules/rules/python/（somnio-ai-tools リポジトリをローカルで使用するか、単独でインストールする場合は GitHub raw を使用）

標準ファイル	目的
typing.md	型ヒントの網羅性、最新のアノテーション構文、静的解析
code-style.md	PEP 8、命名規則、インポートのグループ化、docstring、Ruff
function-design.md	単一責任、関数の長さ、副作用の分離
data-validation.md	Pydantic の境界、バリデーター、型付きレスポンス、設定
error-handling.md	例外の具体性、カスタム階層、ログレベル
module-structure.md	src/ レイアウト、__all__、レイヤー境界、循環インポート
testing-unit.md	ユニットテストのパターン、フィクスチャ、パラメーター化、モック
testing-integration.md	統合テスト、ティアダウン、分離、マーカー

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

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

<YYYY-MM-DD>-<project>-python-best-practices.md

• <YYYY-MM-DD> — この実行の日付です。
• <project> — git リポジトリ名をケバブケースに変換したものです。小文字にし、スペース、_、.、/ を - に置き換え、それ以外の文字はすべて削除し、連続する - はまとめます。名前は origin リモート URL から取得されるため、チェックアウトディレクトリ、ワークツリー、サブディレクトリの名前が何であっても同じです。リモートがない場合はメインチェックアウトのディレクトリ名、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-best-practices.md"

このスキルが reports/<YYYY-MM-DD>-<project>-python-best-practices.md に書き込む箇所はすべて、その解決済みのパスを指します。

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

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

生成するレポートには、末尾に必ずメタデータブロックを含めてください。これは必須事項です。決して省略しないでください。

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

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

## Report Metadata

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