コードにコメント・ドキュメンテーションコメントを追加・補強する。「コメント追加して」「コメント書いて」「コメントを補強して」「JSDoc 付けて」「docstring 付けて」「ドキュメンテーションコメント付けて」で使用。パッケージ・サービス視点での役割境界、呼び出し元・呼び出し先の前提と契約、他ファイル・他サービスからの文脈を「その場で読める」形で残す。コード自体は変更しない（実装変更は implement-issue へ）。詳細規約は code-comment-style、コミット作成は create-commit、CLAUDE.md 同期は update-docs を参照。

comment code コードにコメント・ドキュメンテーションコメントを追加・補強する。コードの実装は変更せず、役割の境界・呼び出し元の前提・返値の契約・他所との依存を「その場で読める」形で記述することが目的。使い方引数を省略した場合は git diff HEAD の差分ファイルを対象とする。 lang を指定するとドキュメンテーションコメントの形式（JSDoc / docstring / rustdoc 等）を優先言語として扱う。指定がない場合は拡張子から自動判定する。前提条件対象ファイルが読み取り可能な状態であること Git リポジトリ内であること（引数省略時に git diff HEAD を使用するため）フロー Step 1: 対象ファイルを特定する引数が指定された場合はそのファイル・ディレクトリを対象にする。対象が空（変更なし・引数なし）の場合はユーザーに対象を確認する。 Step 2: 対象の役割をコードベースから調査するこのステップが最も重要。ファイル単体だけを見るのではなく、システム全体の中での位置づけを把握する。 2 1: 呼び出し元を調査する対象ファイルが公開するシンボル（関数・クラス・型・定数）をコードベース全体で検索し、どのレイヤー・どのサービスから呼ばれているかを把握する。 2 2: import・依存関係を確認する対象ファイルが依存している外部モジュール・サービス・設定を把握する。 2 3: パッケージ・サービス境界を確認する package.json ・ go.mod ・ Cargo.toml 等でパッケージ名・公開 API を確認するサービス間通信（HTTP クライアント・イベント発行・メッセージキュー）が含まれる場合は接続先を特定する認証・認可のミドルウェアやセッション管理と対象の関係を確認する 2 4: 既存コメントスタイルを確認する同じファイル・同じパッケージ内の既存コメントを読み、スタイル（JSDoc / docstring / rustdoc 等）・言語（日本語/英語）を把握する。 Step 3: コメントを追加・補強する Step 2 で把握した「他ファイル・他サービスからの観点」をコメントとして書き込む。コメントスタイルの規約（中心思想）対象リポジトリに .claude/rules/code comment style.md が存在する場合はそちらを優先して従う。存在しない場合は以下の要点に従う。書くべき内容: 観点書く内容役割・責務の境界「このモジュールは〜サービスの〜境界を担う」「〜パッケージの公開インターフェースとして機能する」呼び出し元の文脈どのレイヤー・どのサービスから呼ばれるか。呼び出し元が前提とする状態・権限呼び出し先との契約何を保証して返すか。エラー・例外の条件とその意味（null を返すのか例外を投げるのか等）他ファイル・他サービスとの依存読み手がファイルを跨がないと見つけられない外部依存・設定・共有状態非自明な制約・背景・why なぜその実装になっているか。背景・制約・契約・仕様上の制限書かないもの: シグネチャ・型から自明な逐語的説明（what の言い換え）実装と乖離して陳腐化しやすい重複情報解決済みの経緯だけを残したコメントドキュメンテーションコメント（言語別慣習）言語の慣習に従った形式を使用する: TypeScript / JavaScript: JSDoc ( / ... / ) Python: docstring ( """...""" ) Rust: /// (アイテム) / //! (モジュール) Go: // FuncName ... 形式 Java / Kotlin: Javadoc ( / ... / ) その他: 言語公式ドキュメントの慣習に従う先頭の要約行に「役割・境界」を書き、本文に呼び出し元・呼び出し先の文脈・非自明な制約を追記する。インラインコメント why（なぜその実装か）を書く。what はコードが示している。制約・背景・仕様上の都合は該当行またはブロックの直前に書く。参照すべき外部情報（Issue 番号・仕様書 URL）は積極的に記載する。良い例・悪い例悪い例（what の逐語的な言い換え）: 良い例（役割と他所からの観点を含む）: Step 4: 自己チェックを行う追加・補強したコメントを以下の観点でレビューする。内容の正確性 [ ] 自明な逐語的説明・what の言い換えになっていないか [ ] 実装と乖離した内容を書いていないか（シグネチャと矛盾しないか） [ ] Step 2 の調査結果（呼び出し元・依存関係）が正しくコメントに反映されているかセキュリティ（必須チェック） [ ] コメントにAPIキー・トークン・パスワード等の秘密情報を書いていないか [ ] コメントに個人情報（PII）を直接記載していないか（ユーザーIDの例示等） [ ] 認証・認可の前提条件を誤解を招く形で記述していないか（「認証不要」等の誤記） [ ] セキュリティ上の制約・権限の前提は明確かつ正確に記述されているか上記チェックで問題が見つかった場合は、コメント内容を修正してから次に進む。日本語スタイル [ ] 常体（だ・である調）で記述されているか [ ] コマンド・識別子・ファイル名は英語のまま（翻訳しない） [ ] 絵文字の多用がないか Step 5: 差分を提示して報告する変更内容を差分形式で提示し、以下の形式でレポートする。コミットは create commit スキルへ委譲する（このスキル自身はコミットを行わない）。検証コメント追加後、以下で確認する。コードのロジック（関数本体・制御フロー）が変更されていないこと追加したコメントが実装と矛盾していないこと Step 4 の自己チェックリストがすべて通過していることよくある失敗問題回避策シグネチャ・型から自明な内容を逐語的に書く（what の言い換え）「なぜその実装か」「呼び出し元の前提」など自明でない情報のみ書く呼び出し元を調査せず推測でコメントを書く Step 2 で必ず grep で呼び出し元を確認してから記述するコメントにシークレット・個人情報を混入する Step 4 のセキュリティチェックで秘密情報・PII がないことを確認するコードのロジックを「整理しながら」変更してしまう実装変更が必要な箇所はコメントで TODO を残し、 implement issue へ誘導する注意事項コードのロジックは変更しない — コメントの追加・補強のみ行う。実装に問題があると判断した場合は implement issue スキルへ誘導するコメントは実装と同期させる — 既存コメントが実装と乖離している場合は修正する（乖離したコメントは正確なコメントより有害）詳細規約は対象リポジトリに従う — .claude/rules/code comment style.md が存在する場合はそちらを優先する。本スキルの Step 3 の要点はそのファイルが未配備の場合のフォールバックとして機能する AI エージェントも読み手と想定する — 「他のファイルを参照すれば分かる」は通用しないと想定して書く。Claude 等のエージェントはコメントを主要な文脈源として使用する no verify など pre commit フック回避は禁止。コミット時にフックが失敗した場合は原因を調査・修正してから再実行する

comment-code