| name | write-code-comments |
| description | ユーザーが明示的に指示したコードコメントを記述する。通常のコード編集ではコメント追加が comment-guard hook でブロックされるため、コメント記述が必要なときにこのスキルを使う。 |
| disable-model-invocation | true |
ユーザー指示に従いコードコメントを記述する。comment-guard hook はマーカーファイルが存在する間だけコメント付き編集を許可するため、下記の手順を厳守する。
手順
1. マーカーを作成
最初に、空のマーカーファイルを Write ツールで作成する(カレントディレクトリ基準):
.claude/tmp/.comment-guard-allow
これが無いとコメント付き編集は hook にブロックされる。
2. コメントを記述
$ARGUMENTS の指示に従いコメントを書く。コメントは自己説明的なコードを補助するものであり、悪いコードの言い訳にしない。過度なコメントは可読性を下げるため、必要な箇所に絞る。
鮮度内 (30 分以内) のマーカー下で新規コメントを書くと、コメント本文だけが unslop で lint される。AI 文章クセ (例: 助詞二重・冗長な「することが可能」・prh 用語マッピング違反) を含むと hook が deny する。指摘が返ったらコメント本文を直してから再実行する。
書くべきコメント:
- なぜそう実装したか — 非自明な判断や理由付け
- コードを読んでも即座には分からない知見・前提・制約
- 複雑な箇所や落とし穴への警告
- 複数の実装案がある中で、その方法を選んだ設計判断の根拠
- モジュール・クラス・関数冒頭の、目的と全体動作の高レベルな概要
書くべきでないコメント:
- コードの動作をそのまま言い換える冗長なコメント
- 読めば分かる当たり前の説明
- タスク文脈・レビュー経緯・変更の経緯 — これらは git のコミットメッセージに書く
- 維持できず実態と食い違う恐れのある記述(古いコメントは誤解を招く)
その他:
- 指示された箇所以外にはコメントを足さない
- 既存コメントの体裁・言語(日本語/英語)に合わせる
- TODO は慎重に。残すなら具体的な内容を書く
3. マーカーを削除
作業が完了または中断したら、次のコマンドでマーカーを必ず削除する。
rm -f .claude/tmp/.comment-guard-allow
削除を忘れても 30 分で hook 側が失効扱いにするが、漏れを防ぐため明示的に削除すること。