kamakura.go #8 で「コーディングルールの鮮度を保ちたい」というLTをしてきました

バックエンドエンジニアの長田です。

先日行われた kamakura.go #8 で、「コーディングルールの鮮度を保ちたい」というLTをしてきました。 LTの内容を、当日は触れられなかった要素も含めて紹介します。

コーディングルールの運用

Nature の backend アプリケーションには、10年以上の歴史があります。新旧コードが入り混じり、コーディングスタイルも変化してきました。当時はベストプラクティスだった書き方も、最近では非推奨になっている、というパターンがしばしば発生します。

推奨されるコーディングスタイルを示すドキュメントとして、コーディングルールを定めています。公式ドキュメントである Effective Go や Go Wiki: Go Code Review Comments などには書かれていない、Nature 独自のルールをまとめたものです。実際にコードを書いたり、コードレビューしたりする際に参照し、コーディングスタイルが共通化されることを期待しています。

以前はコーディングルールの管理には Notion を利用¹していました。

Notion 上でデータベースを作成し、項目ごとにデータベースアイテムをつくる形です。使い慣れたツール上に作成されたドキュメントということで、十分に機能はしていました。

コーディングルールにまつわる課題

Notion 上で管理されいたコーディングルールも機能はしていました。少なくともその時点で記載されているものについては。参照しやすい場所にありましたし、コードレビュー時にもしばしば引用されていました。

課題は2つ。

AI エージェントから参照させづらい
メンテナンスコストがかかる

Notion 上のコーディングルールは AI エージェントの仕組みに載せにくいという問題もあります。 Notion MCP を使用すれば参照は可能ですが、そのためのオーバーヘッドが発生します。

また、アプリケーションのコードは日々書き換えられていきます。そのためのルールも、コードに合わせて更新していく必要があります。一般的なコーディングルール、いわゆる Go におけるベストプラクティスと呼ばれるものについてはそうそう変わることはないでしょう。そもそも一般的なので自分たちで管理する必要はないはずです。

一方、プロダクト固有のコーディングルールは自分たちでメンテナンスしていく必要があります。実情にそぐわない古いルールが残っていれば、それを参考にコードが書かれることになり、修正のための手戻りが発生します。そのようなコードが発見できればいいですが、発見できなかった場合は古い非推奨なコードが生まれてしまうことになります。

ソリューション

コーディングルールの Agent Skill 化

1つ目の課題である「AI エージェントから参照させづらい」を解決するために、コーディングルールを Agent Skill go-internal-conventions 化することにしました。

Notion 上のコーディングルールを抜き出し、progressive disclosure² できるよう構成し直しました。カテゴリーごとに Markdown ファイルを分割し、エージェントがキーワードに対応するカテゴリーを素早く特定できるよう検索スクリプト(search_conventions.py)を用意しました。

$ tree .claude/skills/go-internal-conventions/
.claude/skills/go-internal-conventions/
├── SKILL.md
├── references
│   ├── comments.md
│   ├── constants.md
:   :
:
└── scripts
    └── search_conventions.py

Agent Skill 化されたコーディングルールは、明示的な指示がなくとも AI エージェントが作業をこなう際に適宜参照されます。これで AI エージェントがコーディングルールを参照する際のオーバーヘッドは解消できました。

レビューコメントをコーディングルールに反映する仕組み

2つ目の課題「メンテナンスコストがかかる」の解消には、Pull Request につけられたコードレビューコメントを活用するという手段を取りました。

コードレビューは日常的に行われており、そこでは「このような書き方のほうが適切」「最近はこういう内部ライブラリを使っている」などの、プロダクト固有のルールについて議論されています。しかし、議論はその Pull Request の中で閉じてしまうことが多く、レビュワーとしてアサインされていないメンバーには共有されないことがありました³。

これらの議論から有用そうなものを抽出し、それをもとにコーディングルールを更新する Agent Skill update-go-internal-conventions を用意しました。指定日数以内にマージされた Pull Request からコーディングルールとして取り込めるコメントを抽出し、先程の go-internal-conventions に追加するようにしています。

Claude Code 上で以下のように custom command を実行することで、自動でコーディングルールが更新されるわけです。

/update-go-internal-conventions --days 7

レビューコメントの抽出には専用のスクリプトを用意し、効率よくコメントを収集できるようにしました。好意的な返信やリアクションがついているコメントであれば、より現在のプロダクトに沿った内容であろうということで、これを加味した順位付けを行うようなプロンプトにしています。

コーディングルールレベルの話題は積極的には周知されていませんでした。周知するかどうかが議論に参加したメンバーに委ねられているため、メンバーのコーディングルールに対する積極性や、そのときの忙しさやに左右されてしまうというのもあります。

更新されたコーディングルールのレビュー

Agent Skill update-go-internal-conventions を GitHub Actions の cron trigger で毎週実行し、定期的にコーディングルールが更新されるようにしました。 Actions の workflow 末尾で変更を Pull Request として投稿し、それを開発メンバーがレビューするようにしています。

レビューの結果、合意を得られたものをマージ(=採用)しています。

コーディングルール更新に対するレビューコメントの取り込み

合意のためのレビューでより良い提案がなさせることがあります。これについても Skill update-go-internal-conventions を実行することでその場で取り込めるようにしました。 Pull Request のコメントとして所定のコマンド(/update_go_internal_conventions)を投稿すると、当該 Skill が Action として実行⁴され、新たなコミットとして反映される仕組みです。

"/update_go_internal_conventions" とコメントした様子

Agent Skill の定期実行とコメントからの実行、この2つを組み合わせることで、 いつもどおりコードレビューをしていればコーディングルールが更新されていく仕組み ができました。

全体像

Agent Skill を使用したコーディングルール更新の仕組みは、全体像としては以下のようになります。

ふたつの Agent Skill が登場したので少々紛らわしいですが、

コードレビューする
レビューコメントをコーディングルールに反映する

の2つをサイクルとして回す形になっています。

コードレビューへの応用

Agent Skill 化したコーディングルールは、他の Agent Skill からも参照することができます。

Pull Request をチームメンバーにレビュー依頼する前に、手元で AI エージェントによるコードレビューを行えるようにしました。今回作成した Agent Skill go-internal-conventions を明示的に指定し、Subagent にレビューさせることで、 Pull Request 作成時点でのコード品質をある程度担保することができます。

AI エージェントによるコードレビューの実行も Agent Skill として定義し、/codereview という slash command で呼び出せるようにしています。

現在はまだ対応できていませんが、「データベースのパフォーマンス観点でのレビュー」「セキュリティ観点でのレビュー」を行う Agent Skill あるいは Subagent を用意することで、複数観点でのレビューが行えるつくりにしています。このような仕組みは Subagent が登場した頃から使われているものですので、詳細は割愛します。

まとめ

今まで通りコードレビューしているだけで、コーディングルールが更新されていく仕組み を作りました。「今まで通りコードレビューしているだけで」というのが大きなポイントだと考えています。新規に更新手順を加えようとしても、チーム内で一般化するまで時間がかかりますし、そのための労力も増えることになります。 Pull Request のレビューコメントという、今までは流れてしまっていた知識の山を、最小限の労力でドキュメント化できる良い仕組みだと思います。

コーディングルールの更新自体を Pull Request にすることで、いつ、なぜ、そのルールが追加されたのかが明確になりました。古くなってしまったルールを削除する際の判断材料にもなるでしょう。

わかりやすさを優先して「コーディングルール」という書き方をしましたが、実際にはもう一歩引いた視点としてアーキテクチャの明文化も含まれています。今後運用を続け、Agent Skill のボリュームが増してきた際には、コーディングルール用とアーキテクチャガイド用のふたつに分割することも考えられでしょう。