ルールではなくskillに指示を書くことで、Claudeのコメントを減らせた

Sallyのエンジニアは、Claude Codeに実装させるとコメントが長くなる問題に対して、「コードから復元できない情報だけを書く」というルールを.claude/rulesとグローバルのCLAUDE.mdに置いた。ところが自分がマージしたPRの差分を集計すると、ルール導入後もコメントの比率はほとんど下がらず、わずかに増えていた。前回記事での減少は直近数十件だけの集計によるもので、期間と本数を広げると再現しなかった。そこで同じ内容を/prスキルの手順に組み込み、追加したコメント行をgit diffで機械的に抜き出して、1行ずつ残すか消すかを判定させた。

面白いのは、ルールの文面を一文字も変えず、「思い出すもの」から「必ず通る手順」に変えただけで数字が動いた点だ。ルールは書こうとしている瞬間に思い出されなければ効かない。しかもAIはセッションごとに白紙に戻り、実装直後の自分のコメントほど「これは非自明な情報だ」と見えてしまう。人間の職場でも、マニュアルを増やすより、提出前に必ず通る関所を一つ作った方が効くことがある。本音を言えば、ルールを増やしても効かないときは、ルールの数を疑うより、判断の対象を機械的に切り出せているかを疑うべきだ。

それでも手順で消えないものがあった。タスクIDの参照は追加コメント1000行あたり23.5行から8.0行に減ったが、「旧実装は〜だった」という変更履歴は4.7行から5.6行にわずかに増えた。正規表現で一意に決まるものは機械的に落とせるが、その1行が有用かを考えなければならないものは残る。中小企業でAIにコードや文書を作らせる場合も、形式のチェックは仕組みに任せ、中身の判断は人間が担うと線を引くのが現実的だ。