---
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: 対象ファイルを特定する

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

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

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

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

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

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

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

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

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

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

```bash
# 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 の逐語的な言い換え）:

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

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

```typescript
/**
 * 認証レイヤーの公開インターフェース。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` スキルへ委譲する（このスキル自身はコミットを行わない）。

## 検証

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

```bash
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 フック回避は禁止。コミット時にフックが失敗した場合は原因を調査・修正してから再実行する