fix-code-comments
branch で変更した Go、JavaScript、TypeScript、CSS、HTML、XML、Vue、Svelte、Astro、Java、Kotlin、Scala、Ruby、Perl、Lua、R、Python、Shell、SQL、YAML、TOML、PHP、C、C++、C#、Rust、Swift、Dart のコメントを全件確認し、検証に通った変更を commit する skill です。PR の review workflow を始めずに、実装と食い違う説明や識別子名の言い換え、過剰なコメントを直せます。
使い方
/fix-code-comments
通常は origin/main と現在の HEAD の merge-base から差分を調べます。stacked branch で上流 branch の変更を除外したい場合は、base ref を明示します。
/fix-code-comments base-ref=<上流branch>
密度の範囲は、CLI で指定した値、repository の .multi-review-validation.json、3% から 15% の固定値の順に決まります。
明示実行では、対応 file の changed comment hunk をすべて確認します。PR flow の自動起動に使う密度逸脱、name_echo、追加非空行数では対象を絞りません。
明示実行では、追加行を持つコード変更 hunk も code_change_hunks として target に入ります。changed comment hunk が無い file の selection_reason は changed_code になり、changed comment hunk がある file は changed_comment のまま code_change_hunks を併記します。
コード変更 target では、コードと識別子名だけでは残らない制約、理由、invariant、外部契約に限ってコメントを補います。名前や構造で意図を表せる場合は追加しません。
comment-fixer agent は comment-fixer-context.v2 にある言語、file ごとの範囲、選定理由、diff hunk を読みます。元 diff で追加または削除されたコメント行の整形と、code_change_hunks 内の変更コード行の直前へのコメント行の挿入だけを行い、未変更の context 行は対象に含めません。空行、既存コメント行、file の 1 行目の直前は挿入先になりません。shebang や XML declaration のように先頭固定の行を押し下げないためです。
agent は対象 file と diff を read-only で確認します。コードだけでは分からない制約や外部契約は残し、コメントを説明対象のコードに隣接させます。agent 自身は worktree を変更せず、coordinator が返却 patch を検査します。
automatic mode は test file を除外し、密度逸脱または name_echo がある場合だけ agent を起動します。明示実行する manual mode は test file の changed comment hunk も対象にします。
test file は code_change_hunks の対象にしません。test file のコード変更だけでは target を作らず、no_comment_changes で終了します。
Python の docstring と複数行文字列、Shell の heredoc は string として扱います。shebang は code として扱うため、いずれも通常コメントの整形対象には入りません。
SQL、YAML、TOML はコメント密度だけを観測し、name_echo を作りません。quoted value や multiline string の中にある comment marker はコメントから除外します。
実行結果
対象がある時だけ comment-fixer agent を 1 回起動します。Go は適用前後の非コメント token 列を比較し、ほかの対応言語は非コメント byte 列を比較します。HTML 系では markup、script、style、Astro frontmatter の境界も分けます。JVM 系では triple-quoted string と doc comment を分け、Kotlin と Scala の nested block comment を分類します。Ruby / Perl の heredoc、Perl POD、Lua long string、R の文字列もコメントと分けます。PHP では HTML text、PHP tag、文字列、heredoc、nowdoc を分けます。Rust、Swift、Dart では nested block comment と documentation comment を分類します。
文字列、protected directive、cgo preamble、対象外の行が変わる patch は適用しません。
C 系では C++ / C# の raw string を文字列として扱い、preprocessor / compiler directive 行をコメント整形の対象から外します。
protected directive には Go directive に加えて HTML conditional comment、@ts-ignore、@ts-expect-error、eslint、stylelint、Vue / Svelte / Astro の ignore directive、JVM 系の noinspection と静的解析 directive、RuboCop、Perl::Critic / perltidy、StyLua / luacheck、styler / lintr、noqa、type: ignore、ShellCheck directive、SQLFluff、yamllint、Taplo、PHPStan / Psalm directive、clang-format、NOLINT、cppcheck、ReSharper、rustfmt、clippy、SwiftLint、Dart analyzer、formatter toggle を含みます。automatic mode では再計測で元の観測が解消し、新しい観測が増えていない patch だけを適用します。manual mode では既存の密度逸脱を編集目標にせず、新しい name_echo を作らない patch だけを適用します。
manual mode でコメントを増やした file は、再計測後の追加行コメント密度が max_pct 以下である必要があります。超える場合は patch 全体を適用せず、開始前の worktree に戻します。
適用後は refactor: コメントの過不足を整形する という message で commit し、変更した file と commit SHA を返します。commit に失敗した場合は patch を取り消し、開始前の worktree に戻します。
対応言語がない場合は no_supported_language_changes、コメント変更がない場合は no_comment_changes を返します。agent が全件を確認して修正不要と判断した場合は no_quality_findings で正常終了します。いずれも commit は作りません。
検証不通過、agent unavailable、timeout、異常終了、出力の解析失敗でも commit しません。結果には適用しなかった理由が残ります。
local mode の履歴は branch ごとに記録します。PR flow の 2 回上限には数えず、PR 単位の history も変更しません。