OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add fandhe-ai/agent-cli-skills --skill comment-code
コードにコメント・ドキュメンテーションコメントを追加・補強する。「コメント追加して」「コメント書いて」 「コメントを補強して」「JSDoc 付けて」「docstring 付けて」「ドキュメンテーションコメント付けて」で使用。 パッケージ・サービス視点での役割境界、呼び出し元・呼び出し先の前提と契約、他ファイル・他サービスからの 文脈を「その場で読める」形で残す。コード自体は変更しない（実装変更は implement-issue へ）。 詳細規約は code-comment-style、コミット作成は create-commit、CLAUDE.md 同期は update-docs を参照。
npx skills add fandhe-ai/agent-cli-skills --skill comment-code
コードにコメント・ドキュメンテーションコメントを追加・補強する。コードの実装は変更せず、役割の境界・呼び出し元の前提・返値の契約・他所との依存を「その場で読める」形で記述することが目的。
引数を省略した場合は git diff HEAD の差分ファイルを対象とする。
--lang を指定するとドキュメンテーションコメントの形式（JSDoc / docstring / rustdoc 等）を優先言語として扱う。指定がない場合は拡張子から自動判定する。
git diff HEAD を使用するため）引数が指定された場合はそのファイル・ディレクトリを対象にする。
対象が空（変更なし・引数なし）の場合はユーザーに対象を確認する。
このステップが最も重要。 ファイル単体だけを見るのではなく、システム全体の中での位置づけを把握する。
対象ファイルが公開するシンボル（関数・クラス・型・定数）をコードベース全体で検索し、どのレイヤー・どのサービスから呼ばれているかを把握する。
対象ファイルが依存している外部モジュール・サービス・設定を把握する。
package.json・go.mod・Cargo.toml 等でパッケージ名・公開 API を確認する同じファイル・同じパッケージ内の既存コメントを読み、スタイル（JSDoc / docstring / rustdoc 等）・言語（日本語/英語）を把握する。
Step 2 で把握した「他ファイル・他サービスからの観点」をコメントとして書き込む。
対象リポジトリに .claude/rules/code-comment-style.md が存在する場合はそちらを優先して従う。存在しない場合は以下の要点に従う。
書くべき内容:
| 観点 | 書く内容 |
|---|---|
| 役割・責務の境界 | 「このモジュールは〜サービスの〜境界を担う」「〜パッケージの公開インターフェースとして機能する」 |
| 呼び出し元の文脈 | どのレイヤー・どのサービスから呼ばれるか。呼び出し元が前提とする状態・権限 |
| 呼び出し先との契約 | 何を保証して返すか。エラー・例外の条件とその意味（null を返すのか例外を投げるのか等） |
| 他ファイル・他サービスとの依存 | 読み手がファイルを跨がないと見つけられない外部依存・設定・共有状態 |
| 非自明な制約・背景・why | なぜその実装になっているか。背景・制約・契約・仕様上の制限 |
書かないもの:
言語の慣習に従った形式を使用する:
/** ... */)"""...""")/// (アイテム) / //! (モジュール)// FuncName ... 形式/** ... */)先頭の要約行に「役割・境界」を書き、本文に呼び出し元・呼び出し先の文脈・非自明な制約を追記する。
why（なぜその実装か）を書く。what はコードが示している。制約・背景・仕様上の都合は該当行またはブロックの直前に書く。参照すべき外部情報（Issue 番号・仕様書 URL）は積極的に記載する。
悪い例（what の逐語的な言い換え）:
良い例（役割と他所からの観点を含む）:
追加・補強したコメントを以下の観点でレビューする。
上記チェックで問題が見つかった場合は、コメント内容を修正してから次に進む。
変更内容を差分形式で提示し、以下の形式でレポートする。
コミットは create-commit スキルへ委譲する（このスキル自身はコミットを行わない）。
コメント追加後、以下で確認する。
| 問題 | 回避策 |
|---|---|
| シグネチャ・型から自明な内容を逐語的に書く（what の言い換え） | 「なぜその実装か」「呼び出し元の前提」など自明でない情報のみ書く |
| 呼び出し元を調査せず推測でコメントを書く | Step 2 で必ず grep で呼び出し元を確認してから記述する |
| コメントにシークレット・個人情報を混入する | Step 4 のセキュリティチェックで秘密情報・PII がないことを確認する |
| コードのロジックを「整理しながら」変更してしまう | 実装変更が必要な箇所はコメントで TODO を残し、implement-issue へ誘導する |
implement-issue スキルへ誘導する.claude/rules/code-comment-style.md が存在する場合はそちらを優先する。本スキルの Step 3 の要点はそのファイルが未配備の場合のフォールバックとして機能する--no-verify など pre-commit フック回避は禁止。コミット時にフックが失敗した場合は原因を調査・修正してから再実行する# シンボル名で呼び出し元を検索（例: exportされる関数名）
grep -rn "対象シンボル名" --include="*.ts" --include="*.js" .# import 文の一覧
grep -n "^import\|^from\|require(" 対象ファイル/**
* ユーザー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 { ... }## comment-code 完了報告
### 対象ファイル
- `path/to/file.ts`（追加: N 件、補強: M 件）
### 追加したコメントの観点
- 呼び出し元: [どこから呼ばれるかを明記した箇所]
- 呼び出し先との契約: [返値・エラー条件を明記した箇所]
- 非自明な制約・背景: [why を記述した箇所]
### セキュリティチェック
- 結果: ✅ 問題なし / ⚠️ 警告あり（詳細）
### 次のアクション
- コミットする場合: create-commit スキルを使用
- CLAUDE.md を更新する場合: update-docs スキルを使用git diff HEAD