Communityコーディング&開発github.com

sk-python

Pythonコードの作成とデバッグに特化。ミュータブルなデフォルト引数、遅延バインディングクロージャ、シャローコピー、握りつぶされた例外といった、サイレントに誤った動作を引き起こす落とし穴に注意。型ヒント、uv/venvを用いた環境構築・パッケージ管理、pytest構造にも対応。Pythonスクリプト・サービス・ライブラリの作成、Pythonプロジェクトのセットアップ、あるいは不可解に見える動作のデバッグに使用。

sk-python とは?

このスキルは、Python開発においてよくあるが静かに誤った動作を引き起こす落とし穴(ミュータブルなデフォルト引数、遅延バインディングクロージャ、シャローコピーなど)を体系的に回避するための知識を提供します。また、pyproject.tomlベースの依存関係管理、uvまたはvenvによる仮想環境のセットアップ、ロックファイルによる再現可能な環境構築など、Pythonプロジェクトのベストプラクティスを網羅。型チェッカー(mypyなど)のCI統合、pytestを用いたテーブル駆動テスト、パフォーマンス計測・最適化手法にも言及しており、AIエージェントがPythonコードを生成・レビューする際に、単なる構文正しさを超えた堅牢性を確保するための包括的なガイドとなります。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/vanhuydotcom/sk-skills/tree/HEAD/skills/sk-python

Installed? Explore more コーディング&開発 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

Python

Pythonは書きやすい言語ですが、微妙に間違ったコードになりやすい言語でもあります。ここでは、静かに失敗する落とし穴と、壊れた環境を避けるためのプロジェクト設定について説明します。

静かに失敗する落とし穴

ミュータブルなデフォルト引数は、定義時に一度だけ評価され、すべての呼び出しで共有されます。

def add(item, bucket=[]):   # 誤り:bucketは呼び出し間で維持される
def add(item, bucket=None): # 正しい
    bucket = [] if bucket is None else bucket

クロージャは遅延バインディングされます。ループ内で作成されたラムダは、値ではなく変数をキャプチャするため、すべてのラムダが最終的な値を見ることになります。デフォルト引数を使って明示的にバインドするか、functools.partialを使用してください。

isは同一性であり、等価性ではありません。 None、True、Falseに対しては動作しますが、それ以外では使ってはいけません。小さな整数や短い文字列ではインターンされるため動作しているように見えますが、まさにそれがテストをすり抜けるバグの原因です。

コピーはシャローコピーです。list(xs)、xs[:]、dict(d)はコンテナをコピーしますが、要素は共有されます。ネストされた構造にはcopy.deepcopyが必要です。

裸のexcept:はすべてをキャッチします。KeyboardInterruptやSystemExitも含まれます。特定の例外をキャッチし、except Exception: passと決して書かないでください。本当に無視できる例外なら、ログに記録しその理由を説明しましょう。

整数の除算と浮動小数点の等価比較。 /は常に浮動小数点数を生成します。//は負の無限方向に切り捨てられるため、-7 // 2は-4になります。浮動小数点数の比較に==は使わず、math.isclose、または金額計算にはDecimalを使用してください。

コレクションを変更しながら反復処理すると、要素がスキップされます。新しいリストを作成するか、コピーに対して反復処理を行ってください。

ジェネレータは一度しか消費できません。 同じジェネレータを2回目のパスで処理すると何も生成されず、エラーではなく空の結果のように見えます。

環境とパッケージング

システムインタプリタにインストールしてはいけません。プロジェクトごとに仮想環境を作成して有効化するか、uvに管理させてください。

uv venv && uv pip install -e ".[dev]"     # または: python -m venv .venv

依存関係はpyproject.tomlに宣言し、ロックファイルをコミットして環境が再現可能になるようにします。バージョンを固定していないrequirements.txtは再現可能ではなく、将来のマシンで壊れます。

プロジェクトがサポートするPythonバージョンを固定し、pyproject.tomlに明記してください。マイナーバージョン間での動作の違いは、思っている以上に大きいものです。

ある場所ではインポートできて別の場所ではできない場合、原因はほとんどの場合コードではなくインタプリタにあります。インポートをデバッグする前に、which pythonとpython -c "import sys; print(sys.executable)"を確認してください。

型

関数シグネチャ(パラメータと戻り値)にアノテーションを付けましょう。本体にはアノテーションはほとんど必要ありませんが、境界部分には常に必要です。なぜなら、それが他のコードが依存する部分だからです。

CIで型チェッカーを実行してください。検証されないアノテーションは古くなり、誤解を招くドキュメントになります。

慣習によるオプショナルではなく、X | Noneを使用し、オプショナルであることをシグネチャで可視化してください。Anyよりも具体的な型を優先し、型が本当に不明な場合は、unknownに相当するもの(object)を使用して絞り込みを行い、チェッカーが絞り込みを強制するようにします。

構造化データにはdataclassを、外部からデータが到着する境界では検証モデルを優先してください。関数間で文字列の辞書を受け渡すと、最初のタイポですべての保証が失われます。

重要なイディオム

マッピングやフィルタリングを行う場合は内包表記を、それ以外の場合はループを使用してください。副作用や3つの節を持つ内包表記は、置き換えられたループよりも読みにくくなります。

文字列パスではなくpathlib.Pathを使用し、閉じる必要があるもの(ファイル、接続、ロック、一時ディレクトリ)にはコンテキストマネージャを使用してください。

入力が大きい場合や無制限の場合は、リストを構築する代わりにジェネレータからyieldしてください。これが、ストリーミングするスクリプトとメモリを枯渇させるスクリプトの違いです。

インデックス演算やメンバーシップチェックの代わりに、enumerate、zip、デフォルト値付きのdict.getを使用してください。これらは高速で、オフバイワンエラーの一種を排除します。

テスト

pytestを、単純なassertとともに使用します。テーブル駆動型のテストケースには、1つのテスト内でループを回すのではなく@pytest.mark.parametrizeを使用し、各ケースが個別に報告されるようにします。

共有のセットアップは、動作する最も狭いスコープを持つフィクスチャに配置します。セッションスコープのフィクスチャがミュータブルな状態を保持すると、テスト間でリークが発生し、順序依存の障害を引き起こします。

特定の例外はpytest.raisesでアサートし、必要に応じてメッセージも含めてください。

パフォーマンス(重要な場合)

最適化の前に計測してください。おおまかな数値にはtime.perf_counter、処理の内訳にはcProfileを使用します。

典型的な勝利は、インタプリタから処理を移動することです。組み込み関数、内包表記、繰り返しの連結の代わりのstr.join、リストのスキャンの代わりのset/dictルックアップ、数値処理のためのベクトル化されたライブラリ呼び出しなどです。

I/Oバウンドな並行処理にはasyncioまたはスレッドを、CPUバウンドな処理にはプロセスを使用してください。グローバルインタプリタロック(GIL)により、スレッドはCPUバウンドな処理には役に立ちません。

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

sk-api

Design and change API contracts (REST, gRPC, protobuf, events) so existing callers keep working, covering resource and method shape, error models, pagination, versioning and the deploy order a breaking change requires. Use when adding or altering an endpoint, message or event, or when judging whether a proposed change breaks a consumer.

sk-code-review

Shows an agent how to design, debug, or review "sk code review" so the concrete output is a code change with a check. The procedure moves through Code review, Establish the diff first, What to look for, in priority order. Use it when a new assignment calls for this craft.

sk-go-service

Implement, extend or debug a handler, service or repository in a Go backend service, covering context propagation, error wrapping, transaction boundaries, tenancy scoping and table-driven tests. Use when writing or changing Go server code, adding an endpoint or gRPC method, touching a repository query, or diagnosing a panic, leak or flaky test in a Go service.

sk-react

Build and fix React and TypeScript components, covering state placement, effect dependencies, data fetching, list rendering and the re-render traps that cause stale or looping UI. Use when writing or changing a React component or hook, debugging stale data, an infinite render loop or a lost input, or reviewing frontend code.

sk-system-design

Design or evaluate a distributed system from its constraints — service boundaries, synchronous versus event-driven communication, consistency, failure behaviour and capacity — and state the trade-off each choice buys. Use when splitting or merging services, choosing between a call and an event, deciding where data lives, reviewing an architecture proposal, or answering a system design question.

関連スキル