comment-code

コードにコメント・ドキュメンテーションコメントを追加・補強する。コードの実装は変更せず、役割の境界・呼び出し元の前提・返値の契約・他所との依存を「その場で読める」形で記述することが目的。

使い方

comment-code <対象ファイルまたはディレクトリ> [--lang <言語>]

引数を省略した場合は git diff HEAD の差分ファイルを対象とする。 --lang を指定するとドキュメンテーションコメントの形式（JSDoc / docstring / rustdoc 等）を優先言語として扱う。指定がない場合は拡張子から自動判定する。

前提条件

• 対象ファイルが読み取り可能な状態であること
• Git リポジトリ内であること（引数省略時に git diff HEAD を使用するため）

フロー

Step 1: 対象ファイルを特定する

引数が指定された場合はそのファイル・ディレクトリを対象にする。

# 引数なしの場合: 直近の差分ファイルを列挙（staged / unstaged 両方を HEAD と比較）
git diff HEAD --name-only
# untracked（新規未追跡）ファイルも対象にしたい場合
git ls-files --others --exclude-standard

対象が空（変更なし・引数なし）の場合はユーザーに対象を確認する。

Step 2: 対象の役割をコードベースから調査する

このステップが最も重要。 ファイル単体だけを見るのではなく、システム全体の中での位置づけを把握する。

2-1: 呼び出し元を調査する

対象ファイルが公開するシンボル（関数・クラス・型・定数）をコードベース全体で検索し、どのレイヤー・どのサービスから呼ばれているかを把握する。

# シンボル名で呼び出し元を検索（例: exportされる関数名）
grep -rn "対象シンボル名" --include="*.ts" --include="*.js" .

2-2: import・依存関係を確認する

対象ファイルが依存している外部モジュール・サービス・設定を把握する。

# import 文の一覧
grep -n "^import\|^from\|require(" 対象ファイル

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 が存在する場合はそちらを優先して従う。存在しない場合は以下の要点に従う。

書くべき内容:

書かないもの:

• シグネチャ・型から自明な逐語的説明（what の言い換え）
• 実装と乖離して陳腐化しやすい重複情報
• 解決済みの経緯だけを残したコメント

ドキュメンテーションコメント（言語別慣習）

言語の慣習に従った形式を使用する:

• TypeScript / JavaScript: JSDoc (/** ... */)
• Python: docstring ("""...""")
• Rust: /// (アイテム) / //! (モジュール)
• Go: // FuncName ... 形式
• Java / Kotlin: Javadoc (/** ... */)
• その他: 言語公式ドキュメントの慣習に従う

先頭の要約行に「役割・境界」を書き、本文に呼び出し元・呼び出し先の文脈・非自明な制約を追記する。

インラインコメント

why（なぜその実装か）を書く。what はコードが示している。制約・背景・仕様上の都合は該当行またはブロックの直前に書く。参照すべき外部情報（Issue 番号・仕様書 URL）は積極的に記載する。

良い例・悪い例

悪い例（what の逐語的な言い換え）:

/**
 * ユーザーIDを受け取り、ユーザー情報を返す。
 * @param userId ユーザーID
 * @returns ユーザー情報
 */
function getUser(userId: string): User | null { ... }

良い例（役割と他所からの観点を含む）:

/**
 * 認証レイヤーの公開インターフェース。API ハンドラーから呼ばれ、
 * セッション検証済みの呼び出しのみを前提とする（未認証は上流ミドルウェアで遮断）。
 *
 * UserRepository に委譲し、DB から取得した値を返す。
 * 存在しない場合は null を返す（例外は投げない）——
 * 呼び出し元は null チェックを必ず行うこと。
 *
 * 注: soft delete されたユーザーも null として扱う（仕様: issue #142）。
 */
function getUser(userId: string): User | null { ... }

Step 4: 自己チェックを行う

追加・補強したコメントを以下の観点でレビューする。

内容の正確性

• 自明な逐語的説明・what の言い換えになっていないか
• 実装と乖離した内容を書いていないか（シグネチャと矛盾しないか）
• Step 2 の調査結果（呼び出し元・依存関係）が正しくコメントに反映されているか

セキュリティ（必須チェック）

• コメントにAPIキー・トークン・パスワード等の秘密情報を書いていないか
• コメントに個人情報（PII）を直接記載していないか（ユーザーIDの例示等）
• 認証・認可の前提条件を誤解を招く形で記述していないか（「認証不要」等の誤記）
• セキュリティ上の制約・権限の前提は明確かつ正確に記述されているか

上記チェックで問題が見つかった場合は、コメント内容を修正してから次に進む。

日本語スタイル

• 常体（だ・である調）で記述されているか
• コマンド・識別子・ファイル名は英語のまま（翻訳しない）
• 絵文字の多用がないか

Step 5: 差分を提示して報告する

変更内容を差分形式で提示し、以下の形式でレポートする。

## comment-code 完了報告

### 対象ファイル
- `path/to/file.ts`（追加: N 件、補強: M 件）

### 追加したコメントの観点
- 呼び出し元: [どこから呼ばれるかを明記した箇所]
- 呼び出し先との契約: [返値・エラー条件を明記した箇所]
- 非自明な制約・背景: [why を記述した箇所]

### セキュリティチェック
- 結果: ✅ 問題なし / ⚠️ 警告あり（詳細）

### 次のアクション
- コミットする場合: create-commit スキルを使用
- CLAUDE.md を更新する場合: update-docs スキルを使用

コミットは create-commit スキルへ委譲する（このスキル自身はコミットを行わない）。

検証

コメント追加後、以下で確認する。

git diff HEAD

• コードのロジック（関数本体・制御フロー）が変更されていないこと
• 追加したコメントが実装と矛盾していないこと
• Step 4 の自己チェックリストがすべて通過していること

よくある失敗

注意事項

• コードのロジックは変更しない — コメントの追加・補強のみ行う。実装に問題があると判断した場合は implement-issue スキルへ誘導する
• コメントは実装と同期させる — 既存コメントが実装と乖離している場合は修正する（乖離したコメントは正確なコメントより有害）
• 詳細規約は対象リポジトリに従う — .claude/rules/code-comment-style.md が存在する場合はそちらを優先する。本スキルの Step 3 の要点はそのファイルが未配備の場合のフォールバックとして機能する
• AI エージェントも読み手と想定する — 「他のファイルを参照すれば分かる」は通用しないと想定して書く。Claude 等のエージェントはコメントを主要な文脈源として使用する
• --no-verify など pre-commit フック回避は禁止。コミット時にフックが失敗した場合は原因を調査・修正してから再実行する