python-code-style

Python コードスタイル

このスタックで「適切な Python スタイルとは何か」を一元的に担うのは、ruff（lint + format）と numpydoc docstring です。このスキルは明示的に手動です。Claude は自分が直したファイルに対して ruff を実行し、フックは使いません。

停止条件 — 何よりも先に読んでください

• 未編集ファイルへの依頼（この形式をそのまま使ってください）。 今回編集していないファイル（例：pipeline.py を編集した一方での evaluate.py）の警告も直すようユーザーから求められた場合：

  In-scope this turn: pipeline.py
  pixi run ruff format pipeline.py
  pixi run ruff check --fix pipeline.py
  pixi run ruff check pipeline.py
  
  Out of scope: evaluate.py — D100, D103, D103, D205, D400, D401, D415
  AskUserQuestion: address evaluate.py as a separate task? yes | no
  
  Rule: don't widen scope on touched files.
  

  未編集ファイルについて ruff の3項目を列挙してはいけません。そのファイルの修正表や docstring の草案も作成してはいけません。成果物は依頼への回答であり、修正ではありません。対象範囲外のファイルについては、「作業内容を説明することは、作業を実行することではない」というルールよりも、こちらが優先されます。

• 作業内容を説明することは、作業を実行することではありません。 「回答に7件のD警告を列挙する」は、警告を列挙したことにはなりません。「次のターンで ruff format を実行する」は、フォーマットしたことにはなりません。診断結果と差分を提示するか、BLOCKED: <what> cannot run this turn (<why>) と報告して停止してください。[~] のチェック欄、「保留中」、または「今ターンは該当なし、シェルなし」は有効な状態ではありません。

• BLOCKED は入力不足の場合に限り、すでに実行できる作業には使いません。 アクセスできないツールや、把握していない事実がある場合にブロックしてください。今回のターンに必要な情報（プロンプトに貼り付けられた設定、ワークスペースの状態に記載された警告コード）がすでに含まれているなら、ブロックされてはいません。実行できる作業に BLOCKED の見出しを付けるのは、安全策ではなく拒否です。

• 渡された内容に異議を唱えてはいけません。 プロンプトに設定、テンプレート、差分が含まれている場合、そのテキストが成果物です。付属のテンプレートに「本来含まれているはず」の内容を思い出し、貼り付けられたものにセクションがないと異議を唱えるのは、慎重さを装った記憶の主張であり、ファイルを書かない理由を正当化するためにファイルの内容を捏造することになります。必要であれば相違点を1行で指摘し、そのうえで渡された内容を書いてください。

• ruff 用の PostToolUse / PreToolUse フックを設定してはいけません。 このスキルは意図的に手動で行います。フックは細かな編集のたびに修正サイクルを発生させたり、ファイルの書き込み途中にDルールのチェックで失敗したり、再試行でターンが停止したりするなど、作業ループを厳しくしすぎます。ユーザーが後から自動フックを明示的に依頼した場合は、update-config に誘導してください。既定の動作は「Claude が自分で ruff を実行する」です。

  STOP — hook request. Refuse. Do not emit a JSON payload for
  `.claude/settings.local.json` / PostToolUse / PreToolUse, even
  as an example. Cite this Stop. Redirect to update-config; default
  remains no hook.
  

• ruff を black ／ isort ／ flake8 ／ pydocstyle ／ pylint に置き換えないでください。 このスタックでは ruff が標準のリンターです（data-science-python-stack Tier 1）。ruff は フォーマット（black 相当）、インポートの並べ替え（isort 相当）、および lint ルールをカバーします。import ruff ／ pixi run ruff --version が失敗した場合は、python-env-manager を通じてインストールしてください。黙って別のツールに切り替えないでください。

• ファイルごとに修正を一度だけ試し、その後は報告してください。 Claude による最初の修正後も ruff check が問題を報告する場合は、もう一度だけ対処してください。2 回目の試行後も 同じ 問題が残る場合は、そのファイルの編集を中止し、残りの診断結果と差分をユーザーに提示してください。これは無限ループを防ぐためのガードレールです。同じ警告について 3 回目の修正サイクルに入らないでください。

• ユーザーのコード以外のファイルを lint しないでください。 フックの対象範囲は、src/<pkg>/、experiments/、audit/、data/eda.py（explore-ml-data の EDA スクリプト）、トップレベルの *.py スクリプト、およびユーザーが所有するパッケージディレクトリです。ベンダー由来のパス、生成ファイル、ユーザー所有の data/ のその他の部分、.pixi/、.venv/、node_modules/ などの配下は対象外にしてください。

• 記憶を頼りに ruff.toml を作成しないでください。 同梱の templates/ruff.toml が唯一の信頼できる情報源です。このファイルには、ファイルごとの除外設定（experiments/**）、numpydoc の規約、このスタックが想定するルール選択が記載されています。初期設定では、まず .agents/skills/python-code-style/templates/ruff.toml をこのターンで Read し、続いてその内容をそのまま <project-root>/ruff.toml に Write してください。学習データの記憶を頼りに独自の ruff.toml を作成すると、契約の半分が気づかれないまま失われます。このターンでテンプレートを Read しないまま [lint] ／ [format] ／ select = [...] を入力していることに気づいたら、作業を中断し、まず Read してください。テンプレートがすでにプロンプトに貼られている場合は、これは 初期設定です。その TOML をフェンスで囲んでそのまま出力してください（ruff.toml を言語として指定するのが望ましいです）。要約しないでください。[lint.per-file-ignores] を追加しないでください。検証手順として pixi run ruff check --show-settings . を明記してください。

• ユーザーから明示的に依頼されない限り、warnings.filterwarnings(...) を呼び出さないでください。 warnings.simplefilter、@pytest.mark.filterwarnings、および pytest.ini ／ pyproject.toml 内の filterwarnings = [...] も同様です。このスタックでは警告は重要なシグナルです。

• ドキュメントには問題を記述し、ワークフローを記述しないでください。 コミットするファイルのモジュール docstring、ヘッダー、コメントでは、データサイエンス上の問題と、その中でのファイルの役割を記述してください。スキル、ゲート（G-*）、セルランナー、実行ダイジェスト、ジャーナル／バックログ／設計ノートの仕組み、「現在進めているプロセス」を記述してはいけません。このガイダンスはエージェント向けであり、ユーザーのファイルではなくスキルに記載します。実際の内容が入ったファイルを編集する場合は、残っている汎用的なテンプレート文やワークフロー文を、現在のコンテキスト（プロジェクトの目標、実験の仮説、データセット）に基づく簡潔で具体的なドキュメントに書き換えてください。ファイルがまだ空のひな形（内容もコンテキストもない状態）であれば、プレースホルダーはそのまま残してください。具体化するのは内容が追加されるときです。詳細は「コメントをコンテキストに合わせる」を参照してください。

事前確認 — ruff の実行前に、このチェックリストを表示テキストとして出力してください

Pre-flight (python-code-style):
- [ ] ruff importable in the project's env (`pixi run ruff --version`
      succeeds, per `data-science-python-stack` Tier 1)
- [ ] `ruff.toml` present at project root.
      If absent AND stack + workspace are already set up: the
      bundled template MUST be read **this turn** before being
      written verbatim.
      Evidence: Read .agents/skills/python-code-style/templates/ruff.toml
                (this turn) + Write <project-root>/ruff.toml (this turn)
                | "n/a — ruff.toml already at project root"
      **Inline-authored ruff.toml from memory is NOT evidence.**
- [ ] File list ready: <abs paths of .py files touched this turn>
- [ ] Decision recorded: this is the first ruff pass on these files
      (proceed) | second pass (proceed but stop on persistent
      issues) | third pass on same warning (STOP, surface to user)
- [ ] One-fix-per-file rule acknowledged: max two passes per warning,
      then surface remaining diagnostics + diff to the user.
- [ ] Comments contextualized: each touched file with real content has
      problem-specific docs and NO workflow/skill/gate/runner/digest
      meta (§ "Contextualize the comments")
      Evidence: per file, "rewrote header to <problem context>" |
                "no leftover template/workflow prose" |
                "n/a — empty skeleton, no context yet"

対象範囲

• 対象: Claude が直前に生成または編集した Python ファイルに対する ruff format ＋ ruff check --fix ＋ ruff check の実行、公開関数およびクラスへの numpydoc docstring の作成、編集した各ファイルのコメントをデータサイエンス上の問題に合わせて具体化し、ワークフロー／プロセスに関するメタ情報を取り除くこと（「コメントをコンテキストに合わせる」を参照）、新規プロジェクトへの ruff.toml テンプレートの配置。
• 対象外: 型ヒント（mypy ／ pyright はこのスタックに含まれません）、ruff が適用しない命名規則、PostToolUse ／ PreToolUse フックの設定、Python 以外のファイルの lint。

何をどの順番で実行するか

このターンで編集したすべての Python ファイル（以下、<files>）に対して、プロジェクトの環境マネージャー内で次を実行します。pixi プロジェクトでは pixi run を使用し、uv／poetry／conda では同等の方法を使用します（python-env-manager に従ってください）。

pixi run ruff format <files>
pixi run ruff check --fix <files>
pixi run ruff check <files>

次の 3 つの手順を順番に実行します。

1. ruff format — フォーマッターを適用します（行の長さ、引用符、末尾のカンマ、定義の前後の空行）。冪等です。
2. ruff check --fix — ruff が修正できるすべての項目をその場で自動修正します。対象はインポートの並べ替え（I）、古い構文（UP）、検出可能なバグパターン（B）です。
3. ruff check（--fix なし）— 最終チェックです。ここで報告された項目には Claude の対応が必要です。ドキュメント文字列の不足（D）、未定義の名前（F）、コード構造の問題などを修正し、3 つの手順を再実行してください。「停止条件」のファイルごとに修正を 1 つにするルールに従ってください。

experiments/ または audit/ 内のファイル、あるいは data/eda.py の EDA スクリプトで、D100（「モジュールのドキュメント文字列がありません」）または D103（「関数のドキュメント文字列がありません」）の警告が出る場合、これは # %% セルでは想定どおりです。同梱の ruff.toml では、experiments/**、audit/**、data/eda.py に対して、ファイルごとに D100、D103（および E402、B018）を無視する設定になっています。これらの警告が出る場合、ruff.toml が読み込まれていません。プロジェクトのルートにあるか確認してください。

監査ファイル（audit/<NN>_<short_name>.py。所有スキルは audit-ml-pipeline）と EDA スクリプト（data/eda.py。所有スキルは explore-ml-data）は、実験ファイルと同じ方法で lint します。# %% セルの規約、ファイルごとの無視設定、ヘルパー関数に対する NumPyDoc の規約も同じです。これらのファイルを書き込んだり編集したりした後は、同じ 3 つの手順（ruff format → ruff check --fix → ruff check）を実行してください。

コメントに文脈を反映する

ruff はファイルを正しい形式に整えます。この工程では、問題に即した十分なドキュメントがある状態にします。テンプレートには中立的なプレースホルダーと簡単な作成用の補助情報が含まれており、生成スキルが各セル／モジュールの用途を把握できるようになっています。これらをユーザーがコミットするファイルに残してはいけません。ユーザーのファイルには、生成プロセスではなく、データサイエンス上の問題を記述します。

ruff の 3 つの手順を終えたら、実際の内容が入った編集済みファイルすべてについて、簡単なドキュメント確認を行います。

1. この問題に即したヘッダーを記入します。 <placeholder> や汎用的なヘッダーを、このファイルが今回のプロジェクトで何をするのかを説明する 1～2 行に置き換えます。たとえば、実験の仮説（experiment.py）、パイプラインにおけるこのモジュールの役割（src/<pkg>/*.py）、このファイルが確認するレポートとテスト内容（audit/<stem>.py）、データセットの内容と分析の対象（data/eda.py）を記述します。表現は、プロジェクトの目的、承認済みの設計メモ、データセットなど、現在の文脈から取り入れてください。
2. ワークフローに関する記述を取り除きます。 作業プロセスについての説明が残っていれば削除します。スキル名、ゲート ID（G-*）、§ の相互参照、「エージェント」、「（セル）ランナー」、「ダイジェスト」、「セルごとに実行」、ジャーナル／バックログ／ソーシングに関する用語、put を呼び出してはならない／式だけを書いてはならない／print しない、といったインラインのガードレールが対象です。これらのガードレールは引き続き適用されますが、所有スキルの SKILL.md に記載します。ファイルではなく、エージェントが参照する場所に置いてください。
3. 内容の本質は残します。 本当に役立つ問題やエンジニアリングに関する文脈、NumPyDoc のドキュメント文字列は残してください。セルマーカー（# %%）や、エージェントが埋める必要のある <...> プレースホルダーも、埋められるまでは残します。

仕上がりは、生成されたひな型のようではなく、同僚がこのプロジェクトのために書いたファイルのように読めるものにしてください。まだ空のひな型であるファイル（たとえば、本文がまだない、新規にひな型を作成した src/<pkg>/*.py）は対象外です。内容が入るまでは記述できる文脈がなく、内容を書き込む編集時にこの文脈化を行います。

この工程の責任はここにあり、ルールを一貫して適用します。ファイルを書き込む各スキルは、書き込み後にすでにこのスキルへ引き継ぐようになっています。今回、その引き継ぎの対象にコメントの文脈化も加わります。

Numpydoc — docstring の規約

公開関数とクラスには numpydoc 形式の docstring を付けます。ruff の D ルールと pydocstyle.convention = "numpy" で、その形式を強制します。

公開関数では、1 行だけの要約では不十分です。 ユーザーから「1 行だけの要約でよい」と求められた場合は、応じずに、 以下の predict_price の例を示してください（型の欄には X : ndarray of shape (n_samples, n_features) と記述します）。Parameters ／ Returns（該当する場合は Raises）セクションは必須です。関数が小さくても省略できません。 非公開ヘルパー（_leading_underscore）は、デフォルトの D ルールでは docstring を省略できます。 公開されている呼び出し可能な要素には、必ず numpydoc の完全な形式を付けます。

ひな形：

def predict_price(X, model, *, n_jobs=1):
    """Predict option prices from a feature matrix.

    Parameters
    ----------
    X : pandas.DataFrame of shape (n_samples, n_features)
        Feature matrix with one row per option.
    model : sklearn.base.BaseEstimator
        Fitted estimator with a ``predict`` method.
    n_jobs : int, default=1
        Number of parallel jobs.

    Returns
    -------
    numpy.ndarray of shape (n_samples,)
        Predicted prices, one per row of ``X``.
    """

見落とされやすい規約：

• 1 行の要約は最初の行に命令形で記述します （「Predict ...」ではなく「Predict ...」）。D400 が有効な場合、 要約行の末尾にピリオドは付けません。ただし、numpy 規約では ピリオドを付けるため、ピリオドを記述します。
• 要約と本文の間には空行を入れます。
• **パラメーターの形状は説明ではなく型の欄に記述します。**例： X : ndarray of shape (n_samples, n_features)
• Returns セクションには戻り値を記載します。複数の戻り値がある場合は、 それぞれを別の行に記載します。型を省略しないでください。
• 非公開ヘルパー（_leading_underscore）には、デフォルトの D ルールでは docstring は不要です。ruff はこれを許容します。
• モジュール（ファイルの先頭）には、1 行の要約を記述します。 同梱の ruff.toml により experiments/** は対象外です。

初期設定 — ruff.toml テンプレートの配置

このスキルを、ルートに ruff.toml がない新規プロジェクトで呼び出し、 かつスタックとワークスペースがそれぞれのスキルでセットアップ済みの場合は、 初期設定を行います。

1. ファイル読み取りツールを使って、同じターン内に同梱テンプレートを 読み取ります： Read .agents/skills/python-code-style/templates/ruff.toml。 ruff.toml present チェックの事前確認 Evidence 行では、この読み取りが 必須です。記憶を頼りに設定を直接書いても、要件を満たしません。 テンプレートがすでにプロンプトに貼り付けられている場合は、Read を省略して そのまま出力します。
2. 内容を <project-root>/ruff.toml に一字一句そのまま書き込みます。 編集、「改善」、ルールの追加はしないでください。このテンプレートには、 ファイル単位の除外設定（experiments/**）、 pydocstyle.convention = "numpy" の設定、およびこのスタックが想定する ルール選択が含まれています。テンプレートと異なる内容にすると、 要件の半分が失われます。ツールを使えないターンでは、コードフェンス内に 貼り付けることが書き込みに相当します。
3. ruff が設定を読み込むことを確認します： pixi run ruff check --show-settings . を指定します （シェルを使える場合は、実行すれば確認したことになります）。テンプレートの numpy 規約と select リストが表示されるはずです。

ruff の設定を pyproject.toml に自動的にまとめないでください。 プロジェクトに pyproject.toml がない場合や、ユーザーが別ファイルを 希望する場合があります。単独の ruff.toml なら明確です。

禁止されている近道：

近道	なぜ誤りなのか
「ruff.toml に何を書くか分かっている」→ 記憶を頼りに作成する	同梱テンプレートには、experiments/** のファイル単位の除外設定、numpydoc 規約、厳選されたルール選択が含まれています。記憶ではこれらが抜け、要件が気づかれないまま破られます
テンプレートの説明があるこのスキルの SKILL.md を読む → それをもとに書く	SKILL.md は説明するだけです。実体はテンプレートファイルです。ファイル自体を読み、一字一句そのまま書き込んでください

Claude が書いていない箇所を ruff が検出した場合

よくあるケースとして、ファイル内の関数を 1 つ Claude が編集すると、無関係な D ルール違反もすでに存在していて、ruff がそれらも報告することがあります。

• 今回の作業範囲内：Claude が変更した行です。そこを修正してください。 今回の作業範囲内のファイルは、今回編集したファイルです。
• 作業範囲外：未編集コードに以前から存在する警告です。 ユーザーが対応するか選べるよう、回答で触れてください。ただし、現在のタスクにすべての警告を持ち込まないでください。
• ユーザーが未編集ファイルのコードを報告した場合（例： 今回 pipeline.py を編集した一方で、evaluate.py に 7 件の D* 警告がある場合）：
  1. 今回の作業範囲内のファイルとして pipeline.py を挙げ、そのファイル向けの ruff の 3 コマンド（ruff format、ruff check --fix、 ruff check）を列挙します。 シェルを実行できない場合、コマンドを示すことが成果物です。コマンド名を次のターンまで先延ばしにしないでください。
  2. 未編集ファイルについて、報告されたコードを列挙します。
  3. そのファイルを別タスクとして対応するか、はい／いいえで尋ねてください。pipeline.py と一緒に予定に入れないでください。次回の ruff 実行にまとめると言わないでください。

これにより、PR の範囲を適切に保ち、ユーザーが求めていない「ついでの」拡張を防げます。

関連スキル

• data-science-python-stack — ruff を Tier 1 の必須ツールとする判断を担います。このスキルでは、ruff がすでにインストールされていることを前提とします。 pixi run ruff --version が失敗した場合は、インストールについてはこちらに戻ってください。
• python-env-manager — 「ruff がない」という状況に対し、プロジェクトのマネージャーに適したインストールコマンドを示します。pixi プロジェクトで pip install ruff を実行しないでください。
• organize-ml-workspace — 同梱の ruff.toml にあるファイルごとの無視設定（experiments/** と audit/**）が参照するディレクトリ構成を設定します。このスキルの実行後にテンプレートを配置し、無視対象のパスが実際に存在するようにしてください。
• audit-ml-pipeline — audit/<NN>_<short_name>.py に監査ファイルを生成します。このスキルのファイルごとの無視設定は、experiments/ と同じように audit/ パスを対象とします。
• explore-ml-data — EDA スクリプト data/eda.py を生成します（同じ # %% セル規約を使用します）。同梱の ruff.toml は data/eda.py を audit/** と同様にファイルごとの無視対象にします。生成後、同じ 3 コマンドでリンティングしてください。
• update-config — ユーザーが後から自動リンティングフックを明示的に求めた場合のみ関係します。デフォルトではフックを設定しません。

規約

• 手動で実行し、自動化しません。 Claude がファイルごとに ruff を実行します。フックは設定しません。
• ファイルごとに修正は 1 回まで。 再試行は最大 2 回目までとし、その後は結果を伝えます。
• プロジェクトルートの設定のみ使用します。 ruff.toml はプロジェクトのルートに置き、唯一の信頼できる情報源とします。ユーザーから求められない限り、ディレクトリごとの上書き設定を追加しないでください。
• 変更したファイルの作業範囲を広げないでください。 Claude が書いた箇所を修正し、それ以外に以前からある問題は自動修正せず、ユーザーに伝えてください。