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

python-reduce-complexity

Pythonコードの複雑さを計測・削減します。同梱のスクリプトで命令的語彙トークン数をカウントし、簡略化案を提案、機能的等価性を検証し、トークン数の減少を確認します。

python-reduce-complexity とは?

このスキルは、Pythonコードの複雑さを体系的に削減するためのAIエージェントツールです。同梱の`imperative_tokens.py`スクリプトを使用して、コード内の命令的なPython語彙トークン(制御構文、演算子、関数呼び出しなど宣言以外のトークン)のみをカウントし、複雑さを定量化します。ユーザーが複雑さの削減、計測、比較、監査を依頼したときに機能し、`.py`ファイルや`.ipynb`ノートブックを処理対象とします。 主な機能として、(1)コードのベースライン計測とテスト実行、(2)デッドコード削除、標準ライブラリ活用、より簡潔な構文への置き換えなど、実質的なリファクタリングを含む簡略化案の提案、(3)テストや直接比較による等価性の検証(非厳密等価な変更には証拠とユーザーの同意が必要)、(4)変更後の再計測と結果報告、の4ステップで進みます。 標準ライブラリのパターン(`@dataclass`、`defaultdict`、`itertools`など)への置き換え例が多数用意されており、単なるパターンマッチではなくコードの意味を理解して最適化します。各ファイルと統合結果のトークン数変動を報告し、複数ファイルにわたるリファクタリングにも対応します。Claude Code、Cursor、Codexなどの主要なAIエージェントプラットフォームで使用できます。

対応✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/jachymb/skills/tree/main/python-reduce-complexity

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

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

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

ドキュメント

Pythonの複雑さを削減する

ファイル: $ARGUMENTS

コードの複雑さは可能な限り低く保つのが望ましいです。複雑さは、命令的コード(何かを実行する構文)を構成するPython語彙トークンの数として計測されます。宣言はコードを整理するだけでロジックを追加しないため、カウント対象外です。

カウント対象

このファイルの隣にあるimperative_tokens.pyが定義です。

カウントしないもの:

  • defおよびclassのヘッダー(最初のデコレーターからボディを開くコロンまで):デコレーター、パラメーター、デフォルト値、基底クラス、戻り値のアノテーション。これらはすべて定義時に一度だけ評価され、インターフェースを宣言します。
  • 型アノテーション(x: int = 1はx = 1としてカウント、x: intは何もカウントしない)およびtypeエイリアス。
  • インポート、コメント、ドキュメント文字列、改行、インデント。
  • 呼び出しにおけるキーワード引数名:f(key=value)はf(value)と同じ重みです。ほとんどの状況ではキーワードで引数を渡す方が推奨されるため、コストはかかりません。
  • 属性修飾: a.b.c.dはdと同じ重みです。ドット付きパスは1つのオブジェクトを指定します。これをカウントするとfrom numpy import logをnp.logよりも報いることになり、ローカルエイリアスself.xも同様ですが、どちらもロジックを変更しません。

カウント対象:それ以外のすべてのトークン。ステートメント(if、for、while、try、with、return、raise、…)、代入、演算子、呼び出し、リテラル、内包表記、ラムダ、およびそれらのカンマ、コロン、括弧(両方のペア)。したがって、呼び出しは同じ処理を行う演算子より1つ多く重くなります:a.update(b)は4トークン、a |= bは3トークンです。

ノートブック(.ipynb)の場合、コードセルがカウントされます。マジック行またはシェル行(%config …、!pip …)は、IPythonが変換する呼び出しとしてカウントされます。セルマジック(%%bash、%%html)の下のセルは0とカウントされます。例外は、本体をPythonとして実行するセルマジック(IPythonのExecutionMagics、例:%%time、%%capture)です。マジックはラインマジックとしてカウントされ、本体はコードとしてカウントされます。インストールされたIPythonに組み込まれていないマジック(拡張機能からのものなど)は0とカウントされ、スクリプトは警告を出力します。その警告をレポートで伝えてください。カーネルがPythonでないノートブックは0とカウントされます。スクリプトはPythonノートブックが指定された場合にのみIPythonをインポートし、どのマジックが組み込みかを問い合わせます。

カウントはプロキシです

低いカウントは簡略化の証拠であり、簡略化そのものではありません。

  • 重要なリファクタリングは許可されます: 新しいヘルパー関数、新しい基底クラス、新しいファイル。その場合、影響を受けるすべてのファイルを合計してカウントを比較します(ステップ4)。したがって、ファイル間で移動されたロジックは差し引きゼロになります。
  • 独自の正当化が必要です: スクリプトの監視範囲外にロジックを移動する場合(デフォルト値、デコレーター引数、基底クラスの式、新しい依存関係)。提案では、カウントが低いこと以外に、その変更が良い理由を述べてください。
  • 禁止: evalやexec、または同様の外部実行のための文字列内のコード。
  • 1回しか使用されない変数のインライン化は、可読性を損なわない場合にのみ許容されます。中間変数に適切な名前を付けることは、読者が意図を理解するのに役立ちます。
  • 削減ではないもの: 動作の削除(境界でのバリデーション、エラーハンドリング、サポートされているケース)、および可読性を数トークンと引き換えにすること(密集したワンライナー、末尾のカンマの削除)。

プロジェクト独自のルール(CLAUDE.md、コーディングガイドライン)はカウントより優先されます。

厳密に等価ではない変更

変更によって動作が変わる場合でも、プログラムが正しいままであることを示す議論があれば許容されます。提案では、何が異なるか、どの入力に対してか、コード内の証拠とともに議論を述べてください:

  • 異なる入力は発生し得ない。 証拠:値を構築または検証するコード。
  • 誰もその違いを観測しない。 証拠:その値のすべての消費者をリストする。
  • 違いは観測可能だが無害: シードされたジェネレーターからの別の抽出、より遅いアルゴリズム、より早く発生するエラー。これにはユーザーの明示的な同意が必要です。パブリックな戻り値、書き出された出力、またはテストで確認できる違いも同様です。

議論の形を示すいくつかの例。動作を変更するその他の変更も、以下のいずれかに似ているかどうかに関わらず、同じ方法で議論されます:

より単純な形式置き換える対象何が異なるか
x or defaultx if x is not None else default偽のx(0、"/"、[])も置き換えられる
zip(a, b)range(len(a))で両方をインデックス指定短いbは黙って切り詰められる;strict=Trueでチェックを維持
a // bint(a / b)負の被演算子は逆方向に丸められる
max(xs, key=f)sorted(xs, key=f)[-1]同点の場合、最初の等しいアイテムが勝ち、最後ではない
xs.sort()xs = sorted(xs)呼び出し元が渡したリストが変更される
Counter(xs)カウントループ欠落キーは0を読み取り、例外を発生させない
@dataclass、row.nameとして読み取りdictレコード、row["name"]として読み取りインデックス、.get、**アンパック、レコードのJSONシリアル化が機能しなくなる

議論はコードに基づき、今日のデータに基づいてはいけません:「ファイルに重複がない」という議論はできず、「おそらく一意」という議論もできません。動作の削除は依然として除外されます:境界でのバリデーションは議論によって取り除くことはできません。

確信が持てない場合は、ユーザーが決定します。 証拠が不完全(リポジトリ外の消費者、読み取れないコードによって構築された値)である場合、または違いが無害かどうかが不明確な場合は、どちらかに決めつけないでください。何が異なり、何が不明かを示して変更を提案し、他の提案を続け、ユーザーの同意があった場合のみ適用してください。

標準ライブラリの形式

頻繁なケースのサンプル。どのような置き換えになるかを示します。これはカタログではありません:組み込み関数、標準ライブラリ、プロジェクトのインストール済み依存関係にはさらに多くのものがあり、表にない置き換えも表にあるものと同様に有効です。

標準形式置き換える対象何が異なるか
@dataclass、field(default_factory=list)、order=True、frozen=Trueを使用パラメーターを保存するだけの__init__;手書きの__eq__、__repr__、__lt__、__hash____eq__を持たなかったクラスは値で比較されるようになり、ハッシュ不可になる(eq=Falseで同一性を維持);__eq__はクラスも比較する;明示的なNoneはデフォルトにならなくなる
any(p(x) for x in xs)、all(…)、next(filter(p, xs), None)break付きのフラグまたは検索ループなし
defaultdict(list)if key not in groups: groups[key] = []欠落キーの読み取りがそれを挿入する
@cache、@cached_propertyメモ辞書;if self._x is None遅延属性メソッドの@cacheは、呼び出された各インスタンスを生存させ続ける;プロパティはdelでリセットされ、Noneの代入ではリセットされない
itemgetter("foo")、str.strip、operator.mul1つのメソッドを呼び出すか1つの演算子を適用するだけのラムダstr.stripはstrでない値に対して例外を発生させる
Path(path).read_text()with open(path) as file:とfile.read()なし
name.removeprefix(prefix)、line.partition("=")startswithとスライス;splitと長さチェックなし
chain.from_iterable(xss)[x for xs in xss for x in xs]イテレータ:結果がインデックス指定されるか2回読み取られる場合はlistでラップする
batched(xs, n)range(0, len(xs), n)でxs[i:i + n]スライスのリストではなく、タプルのイテレータ
@singledispatchisinstanceチェーン最も具体的に登録されたクラスが勝ち、最初に一致したテストではない;ディスパッチされる引数は最初のもので、位置で渡される

@singledispatchと@dataclassの引数は、ロジックをスクリプトが監視しないヘッダーに移動します。カウント以外の理由:生成されたメソッドはフィールドリストに従い、そこから逸脱できません。また、各型は独自の関数を持ち、新しい型はそれに触れません。

他の形式はコンテキストに依存して初めて役立つため、追加の考慮が必要です:

  • itertools.productまたはitertools.combinationsはネストされたループを置き換える可能性があります。
  • functools.reduceは組み込み関数がない畳み込みを置き換える可能性があります。

ステップ

  1. ベースライン。 プロジェクトのインタープリター(Python 3.12以降)で引数のファイルに対してスクリプトを実行し、出力を保持します:

    python "${CLAUDE_SKILL_DIR}/imperative_tokens.py" <file.py | notebook.ipynb> [...]
    

    今テストを実行します:変更前に失敗するスイートは、変更後に何も検証できません。ユーザーが計測のみを依頼した場合は、それを報告して停止します。

  2. 提案。 コードが何を計算しているかを読み、パターンを一致させるためではなく、各関数、ループ、分岐について、同じ結果をより少ないコードで表現できないかを問います。このスキルのリストと表は、簡略化がどのように見えるかを示しています。それらは検索空間ではありません:削減可能なもののほとんどはそのコードに固有であり、リストでは予測できません。リストされたパターンのみをチェックするパスは不完全です。

    通常見つかるもの(おおよそ収穫の多い順):

    • デッドコード:未使用の関数、パラメーター、到達不能な分岐;
    • 同じロジックがここまたは別のファイルに2回書かれているもの。共有ヘルパーまたは基底クラスが一度に保持するもの;
    • 標準ライブラリ、組み込み関数、またはインストール済み依存関係がすでに提供している手書きコード;itertools、functools、operator、collections、dataclassesなどの標準ライブラリユーティリティが役立つ可能性があり、上記の「標準ライブラリの形式」に頻繁なケースがリストされています;
    • 値を構築するループ:内包表記は通常ループより優れており、場合によってはfilterやmapの組み込み関数が内包表記より簡潔です;
    • オーバーロードされた演算子に置き換わるメソッド呼び出し:a | b for a.union(b)、a |= b for a.update(b)、a @ b for a.dot(b)。最初に被演算子の型を確認してください:セットの|=はセットを必要としますが、.update()は任意のイテラブルを受け取ります;
    • データ(マッピング)または汎用パスに collapse する分岐;
    • 元に戻すためだけに存在する状態と変換;
    • プログラム境界から離れた防御的チェック;
    • 入力が必要以上に厳格なコード。より単純な形式が発生し得ない入力でのみ異なるか、誰も観測しない方法で異なる場合(上の表)。

    その後、最長の関数から順に、これらのどれにも当てはまらないものについてコードをもう一度確認します:簿記を不要にする別のアルゴリズムやデータ構造、特別なケースが消えるように並べ替えられた計算、プロジェクトがすでに使用している依存関係の関数でジョブ全体を行うもの、1つの値だけが異なる2つの関数。このような提案も、リストされたものと同じルールに従います。

    スニペット(提案の前後の行など)を評価するには、ファイル引数なしでスクリプトにパイプします。カウントのみが出力されます。スニペットは単独でパース可能でなければならないため、アンデントしてください:

    python "${CLAUDE_SKILL_DIR}/imperative_tokens.py" <<'EOF'
    uncounted |= set(range(first, last))
    EOF
    

    各提案をコードの形状、重要な前後の行、期待されるトークン削減数、影響を受ける他のファイル、上記のセクションで要求される正当化や議論とともに示します。ユーザーの了承を得て適用するか、ユーザーがすでに変更を依頼している場合は直接適用します。

  3. 適用して検証、一度に1つの提案ずつ。これにより、障害がその原因を指し示します。

    • ベースラインにないファイルへの最初の編集の前に、それを計測してベースラインに追加します。新しいファイルは0から始まります。
    • テストは変更せずにパスします。テストをチェックするコードと一緒に編集されたテストは、もはやそれをチェックしません。変更が必要な場合(削除されたヘルパーを呼び出す場合)、その旨を述べてください。
    • 変更された行を決して実行しないテストは何も証明しません。それらの行については、古いバージョン(git stash、またはgit show HEAD:<path>でスクラッチファイルに)と新しいバージョンを同じ入力(エッジケースを含む)で実行し、出力を比較します。浮動小数点の結果は同一か、レポートで差異の大きさを述べてください。
    • 厳密に等価でない変更は、その議論が認める入力で比較します。次に、議論自体を確認します:値を構築するコードを読むか、すべての消費者を検索します。成立しない証拠は提案を破棄します。
    • パブリックな動作の変更(シグネチャ、例外の型、出力の順序)は等価な変更ではありません。ユーザーの明示的な同意が必要です。
  4. 再計測。 影響を受けるすべてのファイルに対してスクリプトを実行します:引数のファイルと、変更が編集または作成した他のすべてのファイル。削除されたファイルは0で終了します。結合された合計が結合されたベースラインより低いか、変更は元に戻されます。ステップ3で失敗した場合も同様です。

  5. 報告。 影響を受けるファイルごとおよび結合:前後のトークン数とその差。次に、等価性を検証したもの(どのテスト、どの直接比較)、厳密に等価でないすべての変更(何が異なり、その議論)、ユーザーの決定を待つすべての変更、および理由とともに破棄されたすべての提案。

関連スキル