はじめに
AmebaLIFE事業本部でWebフロントエンドエンジニアをしている湯本航基（@yu_3in）です。
本記事では、PRレビューコメントをもとにコーディングガイドラインを継続的に更新する仕組みについて紹介します。
最近は、AIの支援を受けながら実装を進めることが当たり前になってきました。 その一方で、チームの中にある判断基準やレビュー観点が整理されていないと、成果物の品質は安定しません。
今回取り組んだのは、その判断基準をレビューの中から継続的に回収し、ガイドラインとして育てていく仕組みです。 やりたかったのは、PRレビューの中にある判断基準を、継続的に再利用できる形にすることでした。
課題
背景にあった課題は、大きく2つありました。
- レビュー知見がPRの中に埋もれて、チームの資産になりにくい
- ガイドラインを作っても、更新されずに形骸化しやすい
もちろん、一般的なベストプラクティスはすでにたくさんあります。 ただ、実際の開発ではチームごとに重視する観点や許容するトレードオフが少しずつ違います。
そうしたチーム固有の判断基準がまとまっていないと、人間もAIも同じ前提を参照しづらくなります。 一般論だけではこのチームの判断基準としては足りず、実装やレビューのたびに都度すり合わせが必要になります。
レビュー知見が蓄積されにくい
レビューの中には、ガイドラインとして残す価値のある観点が日々蓄積されています。たとえば次のようなものです。
- こういう実装は避けたほうがよい
- この実装だとアクセシビリティが担保されない
- このロジックは再利用性よりも可読性を重視したい
- その実装は今は動くが、将来的に保守しづらくなる
こうした知見は、PRレビューを通じて日常的に共有されています。 ただ、その場では役に立っても、時間が経つと流れていきやすく、レビューした人とされた人の間で閉じてしまいがちです。結果として、チーム全体の資産にはなりにくい状態でした。
ドキュメントが更新されにくい
一度ガイドラインを整備しても、それだけでは十分ではありません。 最初はきれいに作れても、更新が止まると実際のレビュー観点とずれていき、やがて誰も見なくなります。
つまり課題は、単にガイドラインがないことではなく、暗黙知の言語化が進まないことと、作っても更新され続けないことでした。
そこで、PRレビューコメントを定期的に集めてガイドライン候補のPRを作り、その採否をドキュメントへ反映する GitHub Actions のワークフローを作りました。 狙いは、レビュー知見を資産化し、暗黙知を組織知に変えることです。
ワークフローの仕組み
全体の流れは、次の5ステップです。
- 一定期間のPRレビューコメントを収集する
- AIで分析し、ガイドライン案をまとめたPRを作る
- 人間がPR上で採用する内容を決める
- 判断結果をドキュメントに同期する
- PRをマージする
3 と 4 は、必要に応じて繰り返せるようにしています。
2つのフェーズで動く
この reusable workflow は、extract と sync の2フェーズで動きます。
on:
schedule:
workflow_dispatch:
pull_request:
types: [edited]extract は PRレビューコメントからガイドライン候補を抽出し、ガイドライン案をまとめたPRを作るフェーズです。schedule と workflow_dispatch で動かしていて、普段は定期実行、導入フェーズなどでは手動実行もできます。
sync はそのPRで決まった採否をドキュメントへ反映するフェーズです。PR上の判断内容が更新されたタイミングで動かします。実装上は pull_request: edited を使いますが、対象は専用ラベルが付いたPRだけに絞っています。通常のPR編集には反応させないことで、GitHub Actions の実行コストを抑えています。
Extract: ガイドライン案をPRにまとめる
extract フェーズでは、since と until を受け取って対象期間を決めます。未指定なら直近7日間を対象にします。期間を区切るのは、AIに渡す情報量を絞って抽出精度を保つためです。
そのうえで、GitHub Actions 内で PRレビューコメントを AI に渡して分析し、ガイドライン案をまとめたPRの本文を組み立てます。 PR本文にはガイドライン候補の一覧が並び、それぞれに優先度、背景、出典、「除外する」チェックボックスを付けています。
### 1. ボタンにはアクセシブルな名前をつける
**カテゴリー**: Accessibility
**優先度**: High
**出典**: ...
- [ ] 除外するAIの抽出結果はそのまま確定せず、いったん提案PRにして人がレビューできる形にしています。
Sync: 採否をドキュメントに反映する
sync フェーズでは、PR本文でどの項目を採用し、どの項目を除外するかの判断結果を読み取り、その内容でドキュメントを更新します。 チェックが入った項目は除外として扱い、すべての項目が除外された場合はそのPR自体を自動でクローズします。 PR上で採否を見直した場合も、その内容に合わせてドキュメントを再同期できます。
PR本文にメタデータを埋め込む
このワークフローのポイントの1つは、PR本文に同期処理で使うメタデータも埋め込んでいることです。
<!-- coding-guidelines-metadata
{"since":"2026-02-01","until":"2026-02-07","guidelines":[...]}
-->sync が読むのは、PR本文全体ではなくこのメタデータだけです。 そのため、見出しや説明文などPRの表現が変わっても同期処理は壊れにくくなります。別の保存先を増やさずに済むのも利点です。
reusable workflow として切り出した
ここまでの仕組みは、レビューコメントの収集、AI実行、PR作成、採否反映の同期、commit/push まで含めて、1つの job としてまとまっています。 この処理全体を、reusable workflow として切り出しました。
reusable workflow 側は、たとえば次のように workflow_call で入力や secrets を受け取ります。
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に任せる部分と人間が決める部分を分けながら、更新され続ける運用として設計することに意味があると考えています。