write-code-comments

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 側が失効扱いにするが、漏れを防ぐため明示的に削除すること。