friendly-python

friendly-python

明確で保守しやすく、拡張も容易な、親しみやすい Python コードを書くための簡潔なガイダンスです。

目的と利用場面

• 新しいコードの作成、リファクタリング、レビュー、公開 API／CLI の設計に使用します。
• マイクロ最適化より、明確さと保守性を優先します。
• Python または .py ファイルに使用します。
• $piglet が利用可能な場合は、職人技を高めるための追加の例やパターンを得るため、併用を提案してください。

判断の優先順位

1. 正確性と明確な境界
2. 可読性と保守性
3. 拡張性と変更コスト
4. パフォーマンスと最適化

ワークフロー

1. 以下から該当するトピックを探します。
2. ガイダンスと例を適用します。
3. $piglet が利用可能な場合は、このスキルと併用することを推奨します。
4. references/review-checklist.md に照らして確認します。

トピック

トピック	ガイダンス	参照
原則	まず正確性、次に明確さ、最後にパフォーマンス	references/principles.md
エラー処理	対処できるものだけを捕捉し、コンテキストを保持する	references/error-handling.md
API 設計	デフォルトとシンプルなエントリーポイントを用意し、内部の配線を隠す	references/api-design.md
拡張アーキテクチャ	拡張ポイントと変更箇所を一元化する	references/extension-architecture.md
OOP 設計	明確なコンストラクターを用意し、__init__ でのモード切り替えを避ける	references/oop-design.md
再利用とコンポジション	薄いラッパーとコンポジションを優先する	references/reuse-composition.md
移植性と Python らしさ	他の言語のパターンをそのままコピーせず、Python らしく書く	references/portability-pythonic.md
Python の規約	シグネチャ、命名、パッケージ API、リソースを明示する	references/python-conventions.md
テスト	振る舞いに合わせてテストの範囲、分離、構造、時間制御を調整する	references/testing.md
アプリケーションアーキテクチャ	トランスポート、オーケストレーション、ドメインロジック、インフラストラクチャを分離する	references/application-architecture.md
AI 生成の粗雑なコードをなくす	冗長な検証、漏れ出した内部実装、プレースホルダーのエラー処理を取り除く	references/kill-ai-slop.md
CLI Argparse	パースと実行を分離し、サブコマンドを構成する	references/cli-argparse.md
レビュー	コード品質のレビューチェックリスト	references/review-checklist.md

参照資料

• トピックファイルでは、明示的な例外が適用されない限り、frontmatter の urls にソース URL を記載する必要があります。