AIでコーディングガイドラインの運用を自動化し、レビュー知見を資産化する

AmebaLIFE事業本部でWebフロントエンドエンジニアをしている湯本航基（@yu_3in）です。

本記事では、PRレビューコメントをもとにコーディングガイドラインを継続的に更新する仕組みについて紹介します。

最近は、AIの支援を受けながら実装を進めることが当たり前になってきました。 その一方で、チームの中にある判断基準やレビュー観点が整理されていないと、成果物の品質は安定しません。

今回取り組んだのは、その判断基準をレビューの中から継続的に回収し、ガイドラインとして育てていく仕組みです。 やりたかったのは、PRレビューの中にある判断基準を、継続的に再利用できる形にすることでした。

背景にあった課題は、大きく2つありました。

レビュー知見がPRの中に埋もれて、チームの資産になりにくい

ガイドラインを作っても、更新されずに形骸化しやすい

もちろん、一般的なベストプラクティスはすでにたくさんあります。 ただ、実際の開発ではチームごとに重視する観点や許容するトレードオフが少しずつ違います。

そうしたチーム固有の判断基準がまとまっていないと、人間もAIも同じ前提を参照しづらくなります。 一般論だけではこのチームの判断基準としては足りず、実装やレビューのたびに都度すり合わせが必要になります。

レビューの中には、ガイドラインとして残す価値のある観点が日々蓄積されています。たとえば次のようなものです。

こういう実装は避けたほうがよい

この実装だとアクセシビリティが担保されない

このロジックは再利用性よりも可読性を重視したい

その実装は今は動くが、将来的に保守しづらくなる

こうした知見は、PRレビューを通じて日常的に共有されています。 ただ、その場では役に立っても、時間が経つと流れていきやすく、レビューした人とされた人の間で閉じてしまいがちです。結果として、チーム全体の資産にはなりにくい状態でした。

一度ガイドラインを整備しても、それだけでは十分ではありません。 最初はきれいに作れても、更新が止まると実際のレビュー観点とずれていき、やがて誰も見なくなります。

つまり課題は、単にガイドラインがないことではなく、暗黙知の言語化が進まないことと、作っても更新され続けないことでした。

そこで、PRレビューコメントを定期的に集めてガイドライン候補のPRを作り、その採否をドキュメントへ反映する GitHub Actions のワークフローを作りました。 狙いは、レビュー知見を資産化し、暗黙知を組織知に変えることです。

全体の流れは、次の5ステップです。

一定期間のPRレビューコメントを収集する

AIで分析し、ガイドライン案をまとめたPRを作る

人間がPR上で採用する内容を決める

判断結果をドキュメントに同期する

3 と 4 は、必要に応じて繰り返せるようにしています。

この reusable workflow は、extract

on: schedule: workflow_dispatch: pull_request: types: [edited]

workflow_dispatch

pull_request: edited

Extract: ガイドライン案をPRにまとめる

そのうえで、GitHub Actions 内で PRレビューコメントを AI に渡して分析し、ガイドライン案をまとめたPRの本文を組み立てます。 PR本文にはガイドライン候補の一覧が並び、それぞれに優先度、背景、出典、「除外する」チェックボックスを付けています。

1. ボタンにはアクセシブルな名前をつける カテゴリー: Accessibility 優先度: High 出典: ... - [ ] 除外する

AIの抽出結果はそのまま確定せず、いったん提案PRにして人がレビューできる形にしています。

Sync: 採否をドキュメントに反映する

PR本文にメタデータを埋め込む

このワークフローのポイントの1つは、PR本文に同期処理で使うメタデータも埋め込んでいることです。

<!-- coding-guidelines-metadata {"since":"2026-02-01","until":"2026-02-07","guidelines":[...]} -->

reusable workflow として切り出した

ここまでの仕組みは、レビューコメントの収集、AI実行、PR作成、採否反映の同期、commit/push まで含めて、1つの job としてまとまっています。 この処理全体を、reusable workflow として切り出しました。

reusable workflow 側は、たとえば次のように workflow_call

on: workflow_call: inputs: since: type: string description: "start date (YYYY-MM-DD), defaults to 7 days ago" required: false until: type: string description: "end date (YYYY-MM-DD), defaults to today" required: false output-path: type: string description: "output path for guidelines" required: false default: docs/CODING_GUIDELINES.md secrets: anthropic-api-key: description: "Anthropic API key (required if claude-code-oauth-token not provided)" required: false claude-code-oauth-token: description: "Claude Code OAuth token (required if anthropic-api-key not provided)" required: false

こうしておくと、利用側はイベントを定義して uses

呼び出し側は、次のような最小構成で済みます。

on: schedule: - cron: "0 1 * * 1" # Every Monday 10:00 JST workflow_dispatch: inputs: since: description: Start date (YYYY-MM-DD), defaults to 7 days ago type: string until: description: End date (YYYY-MM-DD), defaults to today type: string pull_request: types: [edited] jobs: coding-guidelines: uses: your-org/your-repo/.github/workflows/reusable_coding_guidelines.yml@v1.0.0

なぜ Human-in-the-loop にしたのか

このワークフローでは、AIが候補を出し、人間が最終判断するように、人間を挟む設計にしています。

コーディングガイドラインは、単なる要約ではなく、チームの規範になります。 そのため、「それっぽいことが書いてある」だけでは困ります。

レビューコメントには、その時の文脈に強く依存するものもあります。

あえてトレードオフを取った判断

こうした文脈を無視してAIが自動確定してしまうと、誤ったガイドラインが残る可能性があります。

そのため、AIには「候補を出す役割」を任せ、人間が「規範として残すかどうか」を決める設計にしました。 この Human-in-the-loop を前提にすることで、速度を取りつつ、判断の妥当性を保ちやすくなります。

導入したてではありますが、レビューの流れにはすでにいくつか変化が出始めています。

AIレビューでもチームの観点が反映されるようになった

Claude Code の Code Review を導入しているのですが、ガイドラインに含めた観点が、実際のレビューでも指摘として上がるようになってきました。

たとえば、Storybook の状態カバレッジ不足のような観点も、ガイドライン準拠の指摘として出るようになってきています。チームで蓄積したレビュー観点が、そのまま AI レビューにも反映され始めている感覚があります。

人間のレビューがビジネスロジックに集中しやすくなった

ベースラインとなる観点を AI レビューでも拾えるようになると、人間はレイアウトや Storybook カバレッジのような共通観点だけでなく、仕様の妥当性やビジネスロジックの確認により集中しやすくなります。

結果として、レビュー全体のコストを下げつつ、人間が本当に見るべきところに時間を使いやすくなってきました。

整備するほど次のレビューに効いてくる

一度言語化された観点は、その後のレビューで毎回ゼロから掘り起こす必要がなくなります。 人間にも AI にも参照されることで、良いレビュー観点が一回限りで終わらず、次のレビューでも共通の前提（コンテキスト）として生きるようになります。

レビュー知見をその場限りで終わらせず、次の実装やレビューでも使える形にしていく。そこにこの仕組みの価値があると感じています。

今後は、単にガイドラインを増やすだけではなく、この運用を組織的にどう広げていくかに取り組んでいきたいと考えています。

どの粒度の期間設定が最も精度と運用負荷のバランスがよいか

複数リポジトリを横断したコーディングガイドラインをどう整備していくか

他のチームや他職種でも転用しやすい形になっているか

PRレビューだけでなく、ローカルでのAIとのチャットに含まれる判断や試行錯誤をどう抽出するか

整備したガイドラインを使って、新たなAI活用の取り組みにつなげられるか

といった点は、まだ改善余地があります。

整備したガイドラインを土台にしながら、AIを使った新しい取り組みも進めていきたいと考えています。

AIの支援を前提に開発するほど、実装の進め方だけでなく、その判断基準を全体で共有しておくことが重要になります。

今回の仕組みでは、PRレビューコメントを定期的に収集し、AIで整理し、人間が最終判断することで、コーディングガイドラインを継続更新しやすい形にしました。

この取り組みでやりたかったことは以下の3つです。

そうして整備した判断基準を、人間のレビューや実装の拠り所にしながら、新しく入ったメンバーにも共有し、AIにも同じ前提として渡せるようにしていきたいと考えています。

コーディングガイドラインは、作ることよりも、育て続けることのほうが難しいと思っています。 だからこそ、AIに任せる部分と人間が決める部分を分けながら、更新され続ける運用として設計することに意味があると考えています。