python-foundational

Python 基礎コーディング標準スキル

概要

すべての差分が満たすべき、Python の基礎的な品質基準です。このスキルは、.py の変更がある場合に最初に読み込まれます。より高度なスキルはすべて、この基盤の上に成り立ちます。

この内容が指示ファイルではなくスキルである理由は、3 つあります。スキルは CLI プラグインと VS Code 拡張機能を通じて配布されるため、利用者がリポジトリにファイルをコピーする必要がありません。新しい言語スキルを追加する際に、レビューエージェント自体を変更する必要もありません。また、スキルは必要に応じて読み込まれるため、差分に Python が含まれない場合はコンテキストウィンドウを小さく保てます。

基本チェックリスト

1. 可読性とスタイル

• Python の命名規則を使用します。クラスには PascalCase、関数と変数には snake_case、定数には UPPER_SNAKE_CASE、非公開メンバーには _ を使用します。
• インポートは標準ライブラリ → サードパーティ → ローカルの順にまとめます（グループ間には空行を入れ、末尾に空白を残しません）。

2. Python らしいイディオム

• 単純な変換には内包表記を優先し、複雑なロジックや副作用がある場合は明示的なループを使用します。
• ファイル、ロック、DB 接続には必ず with を使用します。
• データ保持には dataclass／NamedTuple／Enum を優先します。
• os.path より pathlib を優先し、必要に応じてタイムゾーン対応の datetime を使用します。
• オプション引数が複数ある関数では、* を使ってキーワード専用引数にします。
• 厳密に必要な場合を除き、可変デフォルト引数や global／nonlocal は使用しません。

3. 関数とクラスの設計

• 関数は小さく保ち、単一の責務を担うようにします。
• すべての公開 API に docstring を追加します（リポジトリのスタイルに従ってください）。
• 避けられない副作用については説明を記載します。
• コードベースで定められている場合は、クラスメンバーの順序に従います。

4. 型安全性の基礎

• すべての公開 API、モジュール変数、クラス属性に型ヒントを追加します。
• ジェネリクスには PEP 695（3.12+）または TypeVar を使用します。
• 薄いラッパーを除き、Any は避けます。

5. エラー処理

• 具体的な例外を発生させます。裸の except: は使用しません（広範な except Exception: は、ログ記録を伴うアプリケーション境界でのみ使用できます）。
• エラーを黙って無視したり、汎用的なエラーメッセージを使用したりしません。
• すべての例外に、コンテキスト、想定される状態、対処方法を含めます。

6. 避けるべきアンチパターン

• 信頼できないデータに対して eval、exec、pickle を使用しません。
• シークレットをハードコードしません。

7. 保守性

• 自己説明的なコードを優先し、コメントは「なぜ」を説明する場合にのみ記述します。
• print ではなく、構造化ログを使用します。
• テストが難しいほど長い関数や複雑な関数には注意を促します。

8. アーキテクチャとの適合

• 既存のパターンに合わせ、共有機能を再実装したり、確立されたレイヤーを迂回したりしません。
• コードは適切なモジュール／パッケージに配置します。

9. 設計原則

• 重複をなくします。繰り返し使われるロジックを共有ヘルパーに切り出し、修正が自動的に反映されるようにします。
• 現在の要件を満たす、最もシンプルな実装を優先します。抽象化を導入するのは、具体的な2つ目のユースケースが現れてからにします。
• 変更範囲を限定します。変更するすべての行が、変更の明示された目的に結び付いている必要があります。
• 一見未使用に見えるコードを指摘する前に、それがプロトコル実装、フレームワークのフック、公開 API、または外部から呼び出されるエントリポイントではないことを確認します。
• 解決策の複雑さを、問題の複雑さに合わせます。関数の重複には共有ヘルパーを使い、イベント駆動型アーキテクチャは導入しません。

参考資料

ファイル	対象範囲	目的
design-principles.md	セクション 9	設計原則の根拠と例
code-style-patterns.md	セクション 1–5	スタイル、イディオム、型安全性、クラス設計、エラー処理の具体的なコード例

重大度の基準

重大度	定義
高	実行時に誤った動作、データ損失、またはセキュリティ上の露出を引き起こします
中	保守性や可読性を低下させる、またはプロジェクトの規約に違反しますが、実行時にただちに影響はありません
低	見た目やスタイルに関する問題、または軽微な改善の機会です

トラブルシューティング

症状	確認事項
スキルが読み込まれない	差分に .py ファイルが含まれていることを確認してください。エージェントは、変更されたファイルの種類とスキルの説明を照合してスキルを選択します。
指摘が生成されない	レビュー出力の Skills Loaded フッターに python-foundational が記載されていることを確認してください。記載されているのに指摘がない場合、差分はチェックリストをすでに満たしている可能性があります。
重大度の調整が適切でないように見える	上記の重大度の基準と照らし合わせてください。高は実行時への影響が必要で、中は保守性のみに関するものです。

貢献

このスキルを拡張する際は、以下の規約に従ってください。

• チェックリスト項目は SKILL.md に記載します。各箇条書きは、エージェントまたはレビュアーが差分に対して適用できる、実行可能なチェックを1つだけ記載してください。簡潔にし、コードは含めないでください。
• 参照ファイルは references/ に配置し、対象となるチェックリスト項目の例や根拠を示します。各参照ファイルでは、連続するセクション範囲を扱ってください。新しいファイルを追加する場合は、References テーブルを更新してください。
• 新しいチェックリスト項目を追加する前に、どのセクションにも同じ箇条書きが既存していないことを確認してください。主な懸念事項に合ったセクションに配置します。複数の懸念事項にまたがる場合は、より具体的なセクションを優先してください。
• 新しい参照ファイルには、対象トピックに基づいた名前を付けてください（例：async-patterns.md）。対応するセクションを記載したフロントマターの description を含めてください。SKILL.md の References テーブルに行を追加してください。
• チェックリスト項目と例は、さまざまなコードベースで利用できる内容にしてください。汎用的なモジュール名を使い、特定のディレクトリ名やファイル名ではなく、アンチパターンの動作を説明してください。