---

name: comment-detailed description: Pythonファイルの挙動を理解するために、挙動を変えずに解説コメントとdocstringを追加する。ユーザーが「XXX.pyについて、動作を理解したいから細かくコメント入れて」「挙動は変えずにコメントを足して」「このPythonファイルに解説を入れて」などと言ったときに使う。

Comment detailed

目的

• 対象の *.py を「読むだけで追える」状態にするため、コメント/Docstring を追加する。
• コードの挙動は変えない（コメントのみ）。
• コメント追加に際し、md ファイルでユーザーへの事前確認は不要

ワークフロー

1) 対象ファイルを確定する

• ユーザーがパスを出していない場合は、対象ファイルのパス（または該当コード）を要求する。
• 既存コメント/Docstring の言語・流儀が明確ならそれに合わせる。無ければ日本語で書く。

2) 全体像を把握する

• このファイルの役割（責務）を 1〜2 文で言える状態にする。
• 入力/出力/副作用（I/O・グローバル状態・乱数・時刻・環境変数など）を把握する。
• “入口” を特定する（公開 API、main()、CLI、コールバック、テストからの呼び出し等）。

3) コメントを追加する（上から順に）

• モジュール先頭 Docstring
  • 目的、入力/出力、副作用、主要依存、主要フロー（読む順番）を書く。
• 主要クラス/関数の Docstring
  • 責務、引数、戻り値、例外（投げる/握りつぶす）、副作用、前提/不変条件を書く。
  • 既に docstring がある場合は、重複を避けて「不足だけ」を追記する。
• 難所の inline コメント
  • 「何をしているか」より「なぜそうするか / 何を前提にしているか」を優先する。
  • ループや分岐は、境界条件・不変条件・単位（ms/s、px、rad/deg、座標系など）を明記する。

4) 書き方の基準（Do / Don’t）

• Do: 意図、前提、制約、落とし穴、例外系、性能上の理由を書く。
• Do: “読む順番” が分かるように、上流 → 下流の流れで情報を配置する。
• Don’t: 変数名や関数名から自明な「逐語説明」をしない。
• Don’t: 未確定の推測をコード内コメントで断定しない（必要なら返信の「要確認」にまとめる）。

5) セルフチェック（挙動変更なし）

• 差分がコメント/Docstring のみであることを確認する。
• import・式・条件・順序・名前を変えていないことを確認する。
• 空白や整形の大規模変更は避け、必要なら理由を添える。

6) 可能なら軽い検証

• 可能なら python -m py_compile <file> を実行し、失敗したらその内容を報告する。
• 近くにテストがある場合は、プロジェクトの方針に従って最小限のテストを実行する。

返答フォーマット（推奨）

• 追加したコメントの狙い（3〜6 点）
• 重点的に追記した箇所（関数/クラス名）
• 要確認（不明点が残る場合のみ）