この記事は、チームがすでに生み出しているプルリクエストのレビューコメントから、コーディングガイドラインを継続的に更新し続ける仕組みを説明している。著者はサイバーエージェントの AmebaLIFE 事業部に所属する Web フロントエンドエンジニアであり、開発が AI に頼るほど問題が鋭くなると捉えている。チームの判断基準やレビュー観点が整理されていなければ、出力の品質は安定しない。そしてそれとは別に、人間も AI も同じ前提に立って作業することが難しくなる、というのである。
具体的には 2 つの問題が挙げられている。1 つは、レビューの知見がプルリクエストの中に埋もれたままで、チームの資産になりにくいことである。その場では役に立つが、レビューする側とされる側の間で閉じてしまい、時間とともに失われやすい。もう 1 つは、ガイドラインのドキュメントは一度書かれると更新されにくく、実際のレビュー観点から乖離していき、やがて誰も読まなくなることである。著者は問題を、ガイドラインが存在しないことではなく、暗黙知が言語化されていないこと、そして書かれたものが維持されていないことだと言い換えている。
これに対する答えが GitHub Actions のワークフローである。一定期間のレビューコメントを収集し、AI がそれを分析してガイドラインの候補をプルリクエストとして提示し、何を採用するかを人間が決め、その決定をドキュメントに同期してマージする。記事は、決定のステップを意図的に人間に委ねていることを明言しており、効果については、導入して間もない仕組みにおける初期の観察として報告しており、測定された結果としては示していない。
要点
- ワークフローは 2 つのフェーズで動作する。レビューコメントからガイドライン候補のプルリクエストを作成する
extractと、採用された決定をドキュメントに書き戻すsyncである。 extractはscheduleとworkflow_dispatchで実行され（通常はスケジュール実行、導入期間中は手動実行）、期間が指定されない場合はデフォルトで直近 7 日間を対象とする。期間を区切る理由として記事が挙げるのは、AI に与える情報量を制限して抽出の精度を保つためである。- 候補のプルリクエストには、各ガイドラインが優先度、背景、引用とともに一覧され、「除外」チェックボックスが付く。記事の実例ではカテゴリ欄も示されている。チェックされた項目は除外として扱われ、すべての項目が除外された場合、そのプルリクエストは自動的にクローズされる。
syncはpull_request: editedをトリガーとするが、専用のラベルが付いたプルリクエストに限定されている。記事はこれを GitHub Actions の実行コストを抑える方法として挙げている。syncはプルリクエスト本文全体ではなく、本文に埋め込まれた機械可読なメタデータブロックだけを読む。記事によれば、これにより見出しや説明文が変わっても同期が壊れず、2 つ目の保存場所を持ち込むことも避けられる。- コメントの収集、AI の実行、プルリクエストの作成、決定の同期、コミットとプッシュという一連の処理全体が GitHub の再利用可能ワークフローとしてパッケージ化されており、導入するリポジトリはトリガーと
uses:の行を定義するだけでよい。 - ヒューマン・イン・ザ・ループ とする理由として述べられているのは、ガイドラインが要約ではなくチームの規範になるという点である。レビューコメントは、リポジトリ固有の事情、その時点のリリースの優先度、意図的に許容された例外、承知の上で選んだトレードオフに依存していることがある。そうした文脈なしに AI に候補を確定させると、誤ったガイドラインが残るリスクがある。AI には候補を提案する役割が、人間には何を規範として残すかを決める役割が与えられている。
- 初期の観察として 3 つの効果が報告されている。ガイドラインに追加した観点が、チームが導入していた Claude Code の Code Review で指摘として現れるようになったこと（例として Storybook の状態網羅の不足が挙げられている）。基本的な観点が自動で拾われるようになったことで、人間のレビューが仕様の妥当性やビジネスロジックに集中しやすくなったこと。そして、一度書き留めた観点は、以後のレビューで一から再発見する必要がなくなったことである。
- 著者自身による目的のまとめは 3 つである。暗黙知の言語化、レビュー知見の資産化、そして暗黙知の組織知への転換である。
- 報告された効果のいずれについても測定は示されていない。記事は、この仕組みが導入されて間もないと述べている。
背景
記事は、一般的なベストプラクティスはすでに豊富に存在すると明言しており、目指しているのはそれらがカバーしない部分、すなわち各チームがそれぞれ少しずつ異なる重み付けをする観点やトレードオフである。これらは一般的な指針では補えず、そうでなければ実装やレビューのたびに合意し直さなければならない。
記事が挙げる未解決の問いは、仕組みそのものではなく、規模と転用に関するものである。精度と運用負荷のバランスが最もよい期間の粒度はどれか、複数のリポジトリにまたがってガイドラインをどう維持するか、この形を他のチームや職種に転用できるか、プルリクエストのレビューだけでなくローカルの AI チャットセッションから判断や試行錯誤をどう抽出するか、そして蓄積されたガイドラインがさらにどのような AI の作業を支えうるか、である。
結びの主張は、コーディングガイドラインは作ることよりも育て続けることのほうが難しいというものであり、著者は、AI に委ねることと人間が決めることの分担を、一度きりのドキュメントとしてではなく運用上の実践として設計した理由をそこに置いている。