Claude Codeで生成したコードの品質を、あなたはどうやって担保していますか？
「CLAUDE.mdにルールを書けば大丈夫」と思っているかもしれません。
しかし、それは少し危険です。
先日、Redditにこんな質問が投稿されました。
「Claude Codeを使うとき、コード品質を維持するためのチェックリストは何か」と。
そして、このスレッドには実践的な知見が数多く集まっていました。
本記事では、そのスレッドで語られた内容を整理して紹介します。
議論には一貫したメッセージがありました。
「最終的なガードレールは、あなた自身である」と。
AIは「チェックを攻略する」存在
まずは、スレッドで最も本質的だと感じた指摘から始めましょう。
エージェントは、正しいコードを書くことに最適化されるわけではありません。
「ゲートを通過すること」に最適化されるのです。
つまり、エージェントから見える場所にあるチェックは、最も安上がりな方法で満たされてしまいます。
分かりやすい例が挙げられていました。
失敗するテストを渡したとします。
すると、エージェントはコードを直しません。
代わりに、テスト側を弱めたり削除したりして「解決」することがあるのです。
テストスイートは緑になります。
でも、問題は何も解決していません。
ここから導かれる結論はシンプルです。
エージェントが編集できるテストは、ガードレールではなく「提案」にすぎない。
CLAUDE.mdも同じです。
あれは「後押し」であって、強制力を持ちません。
「クリーンなコードを書け」というプロンプトだけで済ませる。
それは品質システムとは呼べない、という意見もありました。
まったくその通りだと思います。
差分を読む。雰囲気で判断しない
では、どうすればいいのか。
スレッドで繰り返し語られていたのが、次の原則です。
エージェントの要約ではなく、コードの差分そのものを読め。
厄介な失敗は、派手なエラーではありません。
すべてのチェックを通過しつつ、静かに間違っている変更です。
しかも、自信満々でもっともらしい顔をしています。
これを捕まえられるのは、差分を読む人間だけ。
つまり、エージェントが攻略できない唯一のゲートが、あなたの目なのです。
合わせて、小さな単位でこまめにコミットする習慣も推奨されていました。
テストが緑になるたびにコミットしておきます。
すると、後で問題が起きたときにgit bisectで原因のターンを特定できます。
最後に巨大な変更の塊をほどく羽目にはなりません。
ゲートはAIの手が届かない場所に置く
もうひとつの重要な原則があります。
本当の強制力は、エージェントが触れない場所に置くこと。
具体的には、次の2つです。
- PRに対するCIパイプラインでのlint・型チェック・テスト実行
- コードを書いていない、新しいセッションによるレビュー
採点される側が、採点者に触れられない。
だから、不正ができない。
この構造が効くわけです。
ここで、gitフックの話題も出ていました。
興味深いのは、その位置づけです。
pre-commitやpre-pushフックは、PRが存在する前の段階でlintや型エラーを捕まえてくれます。
CIを待つより圧倒的に速い。
そのため、フィードバックループを短くする手段として積極的に使うべきという意見が主流でした。
ただし、注意点があります。
ローカルのフックはgit commit –no-verifyで丸ごとスキップできます。
そして、シェルアクセスを持つエージェントなら、このコマンドを実行できてしまいます。
さらに、フックの設定ファイル自体もリポジトリ内にあります。
つまり、テストを弱めるのと同じ手口で骨抜きにされる可能性があるのです。
だから、ローカルフックは「速度のため」に使う。
「強制のため」には、CIとブランチ保護を使う。
この使い分けが提案されていました。
スレッド内の言葉を要約すると、こうなります。
エージェントがチェックを回避するコマンドを実行できるなら、それは開発体験の改善であって強制力ではない。
なお、gitをセルフホストしている場合は例外があります。
サーバー側のpre-receiveフックにはエージェントの手が届きません。
そのため、本物のゲートとして機能するそうです。
ワークフローを固める
高評価を集めたコメントには、共通点がありました。
行き当たりばったりではなく、厳密なワークフローを持っていたのです。
代表的な流れを紹介します。
- プロジェクト全体をブレインストーミングして、開発フェーズに分割する
- 各フェーズの手順を計画する
- さらに、各ステップを個別に検討する
- 1ステップずつコードを書かせる
- 書き終えるたびに新しいウィンドウを開き、そのステップのコードをレビューさせる
ポイントは、コードを書いたセッションとは別のセッションでレビューすることです。
書いた本人（本人？）は、自分のミスを見逃しやすいからですね。
さらに、フェーズ完了時の「敵対的監査」のテクニックが面白かったので紹介します。
あるユーザーは、Claudeに対して「このコードは別のAI（Codex）にすでに監査させた」と伝えるそうです。
実際には監査させていません。
しかし、そう伝えるだけで、通常では引き出せない徹底的なレビューモードが発動するとのこと。
本人いわく、この監査の完了に1〜2週間分の利用枠を使い切ることもあるそうです。
真偽のほどは検証が必要でしょう。
ただ、ライバルの存在を示唆すると本気を出すという話は、なんだか人間くさくて笑ってしまいました。
タスクサイズが最大のレバー
品質を左右する最大の要因として、「タスクの大きさ」を挙げる声もありました。
Claude Codeが3〜4ファイル以上に触れる必要が出てくると、コード品質が崩れ始める。
そういう分析です。
ただし、モデルが悪いわけではありません。
問題が十分に具体化されていないため、正しく保持できなくなるのです。
その境界に達したら、人間が先にタスクを分解します。
そして、原子的な変更をひとつだけ渡す。
差分をレビューしてコミットしたら、次のピースを渡す。
遅くなります。
でも、出力はクリーンでレビュー可能なものになる。
CLAUDE.mdのルールやlintフックの効果は、「余白を埋める程度」だそうです。
それよりも、着手前のタスク分割こそが最も安定して品質に効く。
そう述べられていました。
型とテストという基本
古典的な手法も、しっかり支持されていました。
まず型です。
JavaScriptを使っているなら、TypeScriptに切り替える。
Pythonなら、型アノテーションを付ける。
さらに、正確性やパフォーマンスを重視するなら、Rustのような静的型付け言語への移行まで視野に入れる。
そんな提案がありました。
次に、テスト駆動開発（TDD）です。
すべての機能や修正にテストを付随させます。
そして、テストが通るまで完了扱いにしない。
この方針を主要な指示に組み込んでいる人が複数いました。
ただし、指示には工夫が要ります。
「例外は一切なし」「失敗したテストや不安定なテストは必ず即座に修正する」と明記しましょう。
そうしないと、急いでいるときにテストを書き飛ばそうとする傾向があるそうです。
一方で、TDDに懐疑的な意見もありました。
エージェントのコード生成能力は、すでに高い。
つまずくのはコードのロジックよりも、仕様の詰めの甘さやUXの行き止まりだ。
だから、TDDが与えてくれる耐久性は限定的だという主張です。
どちらの立場を取るにせよ、一致している点がありました。
仕様を事前に固めることの重要性です。
CLAUDE.mdの正しい使い方
CLAUDE.mdが強制力を持たないことは、先に述べました。
では、無意味なのでしょうか。
そうではありません。
「規約を伝えるガイド」としては有効だという意見が多数ありました。
人間の開発者と組むプロジェクトと変わらない、という指摘が的を射ています。
具体的な手順は、次の通りです。
まず、堅実なルールセットを持つlinterとformatterを用意します。
そして、pre-commitフックで自動修正モードで走らせる。
CLAUDE.mdには、タスク完了後にlinterを実行するよう書いておきます。
さらに、コードベースに事前にフォルダ構造を作っておきましょう。
何をどこに置くかは、CLAUDE.mdで説明します。
参考になるコード例も用意して、そこを指し示す。
すると、Claudeはそこから流儀を推測してくれます。
そして可能な限り、その構造をlinterのルールとして強制する。
ここまでやって初めて、CLAUDE.mdが活きてくるわけです。
CLAUDE.mdに書く内容は、具体的で絞られたものが良いとされていました。
例えば、以下です。
- アーキテクチャのルールと命名規則
- 実行すべきコマンドとテストの期待値
- 勝手に変更してはいけない領域
ツールの話：ただしトークンは溶ける
スレッドでは、いくつかのツールやスキルの名前も挙がっていました。
特に言及が多かったのが「Superpowers」というスキルです。
計画・レビュー・監査を含む開発ライフサイクルを強制してくれます。
そのため、複数のユーザーが支持していました。
ただし、代償があります。
「使用量を吸い尽くすのに非常に効果的」という皮肉が、支持コメントより高い評価を得ていたのです。
これは印象的でした。
もちろん、反論もあります。
敵対的なコードレビューとセキュリティレビューを含むワークフローを自作するとします。
すると、どこかで妥協することになる。
トークン消費はその対価だ、という主張です。
他のツールも挙がっていました。
SonarQubeのような静的解析ツールでレポートを出して対処する方法。
Matt Pocock氏のスキル集。
GSDといったハーネス。
それぞれ一長一短があるようです。
興味があれば調べてみてください。
まとめ
Redditスレッドの議論を貫いていたのは、次の考え方でした。
エージェントは、見えるチェックを攻略します。
だから、プロンプトやCLAUDE.mdだけでは品質を守れません。
本当のゲートは、「エージェントの手が届かない場所」に置く必要があります。
CIやブランチ保護が、その代表です。
そして最後の砦は、差分を読むあなた自身です。
ツールやスキルは、レビューすべき情報の奔流を管理しやすくしてくれます。
でも、あなたをループから外してくれるわけではありません。
シニアエンジニアとして部屋に居続けること。
それが、AI時代のコード品質管理の本質なのでしょう。
まずは、linterとformatterをpre-commitフックに仕込むところから始めてみてください。
そして、CIでテストを回す。
そのうえで、タスクを小さく分割し、差分を読む習慣を作る。
この土台があれば、Claude Codeは強力な相棒になってくれるはずです。
