| name | comment-code |
| description | コードにコメント・ドキュメンテーションコメントを追加・補強する。「コメント追加して」「コメント書いて」 「コメントを補強して」「JSDoc 付けて」「docstring 付けて」「ドキュメンテーションコメント付けて」で使用。 パッケージ・サービス視点での役割境界、呼び出し元・呼び出し先の前提と契約、他ファイル・他サービスからの 文脈を「その場で読める」形で残す。コード自体は変更しない（実装変更は implement-issue へ）。 詳細規約は code-comment-style、コミット作成は create-commit、CLAUDE.md 同期は update-docs を参照。
|
| model | sonnet |
| user-invocable | true |
| argument-hint | <対象ファイルまたはディレクトリ> [--lang <言語>] |
comment-code
コードにコメント・ドキュメンテーションコメントを追加・補強する。コードの実装は変更せず、役割の境界・呼び出し元の前提・返値の契約・他所との依存を「その場で読める」形で記述することが目的。
使い方
comment-code <対象ファイルまたはディレクトリ> [--lang <言語>]
引数を省略した場合は git diff HEAD の差分ファイルを対象とする。
--lang を指定するとドキュメンテーションコメントの形式（JSDoc / docstring / rustdoc 等）を優先言語として扱う。指定がない場合は拡張子から自動判定する。
前提条件
- 対象ファイルが読み取り可能な状態であること
- Git リポジトリ内であること（引数省略時に
git diff HEAD を使用するため）
フロー
Step 1: 対象ファイルを特定する
引数が指定された場合はそのファイル・ディレクトリを対象にする。
git diff HEAD --name-only
git ls-files --others --exclude-standard
対象が空（変更なし・引数なし）の場合はユーザーに対象を確認する。
Step 2: 対象の役割をコードベースから調査する
このステップが最も重要。 ファイル単体だけを見るのではなく、システム全体の中での位置づけを把握する。
2-1: 呼び出し元を調査する
対象ファイルが公開するシンボル（関数・クラス・型・定数）をコードベース全体で検索し、どのレイヤー・どのサービスから呼ばれているかを把握する。
grep -rn "対象シンボル名" --include="*.ts" --include="*.js" .
2-2: 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 が存在する場合はそちらを優先して従う。存在しない場合は以下の要点に従う。
書くべき内容:
| 観点 | 書く内容 |
|---|
| 役割・責務の境界 | 「このモジュールは〜サービスの〜境界を担う」「〜パッケージの公開インターフェースとして機能する」 |
| 呼び出し元の文脈 | どのレイヤー・どのサービスから呼ばれるか。呼び出し元が前提とする状態・権限 |
| 呼び出し先との契約 | 何を保証して返すか。エラー・例外の条件とその意味（null を返すのか例外を投げるのか等） |
| 他ファイル・他サービスとの依存 | 読み手がファイルを跨がないと見つけられない外部依存・設定・共有状態 |
| 非自明な制約・背景・why | なぜその実装になっているか。背景・制約・契約・仕様上の制限 |
書かないもの:
- シグネチャ・型から自明な逐語的説明（what の言い換え）
- 実装と乖離して陳腐化しやすい重複情報
- 解決済みの経緯だけを残したコメント
ドキュメンテーションコメント（言語別慣習）
言語の慣習に従った形式を使用する:
- TypeScript / JavaScript: JSDoc (
/** ... */)
- Python: docstring (
"""...""")
- Rust:
/// (アイテム) / //! (モジュール)
- Go:
// FuncName ... 形式
- Java / Kotlin: Javadoc (
/** ... */)
- その他: 言語公式ドキュメントの慣習に従う
先頭の要約行に「役割・境界」を書き、本文に呼び出し元・呼び出し先の文脈・非自明な制約を追記する。
インラインコメント
why（なぜその実装か）を書く。what はコードが示している。制約・背景・仕様上の都合は該当行またはブロックの直前に書く。参照すべき外部情報（Issue 番号・仕様書 URL）は積極的に記載する。
良い例・悪い例
悪い例（what の逐語的な言い換え）:
function getUser(userId: string): User | null { ... }
良い例（役割と他所からの観点を含む）:
function getUser(userId: string): User | null { ... }
Step 4: 自己チェックを行う
追加・補強したコメントを以下の観点でレビューする。
内容の正確性
セキュリティ（必須チェック）
上記チェックで問題が見つかった場合は、コメント内容を修正してから次に進む。
日本語スタイル
Step 5: 差分を提示して報告する
変更内容を差分形式で提示し、以下の形式でレポートする。
## comment-code 完了報告
### 対象ファイル
- `path/to/file.ts`（追加: N 件、補強: M 件）
### 追加したコメントの観点
- 呼び出し元: [どこから呼ばれるかを明記した箇所]
- 呼び出し先との契約: [返値・エラー条件を明記した箇所]
- 非自明な制約・背景: [why を記述した箇所]
### セキュリティチェック
- 結果: ✅ 問題なし / ⚠️ 警告あり（詳細）
### 次のアクション
- コミットする場合: create-commit スキルを使用
- CLAUDE.md を更新する場合: update-docs スキルを使用
コミットは create-commit スキルへ委譲する（このスキル自身はコミットを行わない）。
検証
コメント追加後、以下で確認する。
git diff HEAD
- コードのロジック（関数本体・制御フロー）が変更されていないこと
- 追加したコメントが実装と矛盾していないこと
- 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 フック回避は禁止。コミット時にフックが失敗した場合は原因を調査・修正してから再実行する
