GitHub Actionsで仕様書の更新漏れを“仕組みで止める”——gh-awで自動PR/NoopするPoC

2026年2月11日 • ☕️☕️ 10 min read

GitHub Actions AI

gh-awで仕様書の更新漏れを“仕組みで止める”PoC（送料計算の事故から）

tl;dr

仕様書の更新漏れは注意力では止まらない
gh-awで「docs更新が必要ならPR / 不要ならnoop」を自動化すると、人間のレビューが“楽”になる
詰まったのは2つだけ：Safe Outputs と Actions の PR 作成権限
ついでにPR文面を日本語＆Draft解除まで整えると、運用のストレスが消える

背景：ドキュメントは「気をつける」だけだと必ずズレる

昔も今も、避けて通れない課題が 仕様書の管理。
コードだけ更新されて 仕様書や手順書が古いまま――これは日常的に起こります。

しかも AI時代はこれが悪化しやすい。
AIが素早くソースコードを生成・変更できるほど、更新の回数と速度が上がり、結果として ドキュメントが置いていかれる確率 も上がります。

ここで「気をつける」で勝つのは無理ゲー。
なので、差分を自動検知して、更新漏れが起きにくい導線を先に作る方が現実的です。

事故はいつも「コードは正しい」顔をしてやってくる（送料計算のやつ）

送料計算のロジックを変えた。

コードは動く
テストも通る
PRもマージされた

……のに、仕様書だけが古いまま残った。

別に珍しくない。むしろ“よくある”。
だから「ちゃんと書こう」ではなく、ズレると勝手に止まる方向に寄せたくなった。

今回はその緩和策として、GitHub Agentic Workflows（gh-aw） を使い、

src/ などの変更をトリガーにする
影響する docs を見直す
更新が必要なら PR を自動作成する
何も不要なら noop で「何もしなかった」を明示する

という流れをPoCとして組みます。

ここでやりたいのは「ドキュメントを完璧に自動生成」ではなく、
更新漏れを“見逃しにくくする仕組み” を作ることです。

gh-awでやりたかったこと（人間のレビュー観点をそのまま機械に渡す）

狙いはシンプル。

src/ の変更をトリガーにする
影響する docs を見直す
直す必要があれば PR を出す
直す必要がなければ noop で明示する

ここでポイントは、「AIが賢いから全部見つけてくれるはず」ではなく、

人間がレビューでやっている判断を、毎回同じ手順で再現させたい

という思想。

1回目：検知したのに成果物ゼロ（No Safe Outputs）

最初の実験、面白いことが起きた。

AIは「仕様書更新が必要」と判断した。
ログにもそれっぽい“完了サマリ”が出る。

……のに、ワークフローは失敗する。

理由はこう：

Safe Outputs が生成されていない
（No Safe Outputs Generated）

ここで一瞬「え、AIが作業したのに何がダメなの？」ってなるんだけど、gh-awの設計を理解すると納得する。

エージェント本体は基本 read-only
書き込み（PR作成など）は safe outputs 経由で“明示”しないと反映されない

つまり、AIがローカルで「コミットした気分」になっても、それは成果物としては無効。

そこで指示をこう変えた。

変更があるなら create-pull-request を必ず呼ぶ
変更がないなら noop を必ず呼ぶ
コミットは禁止（成果物は safe outputs で出す）

2回目：PRを作ろうとして権限で死ぬ

次は create-pull-request を呼ぶようになった。

今度こそ勝った……と思ったら、別の地雷。

GitHub Actions is not permitted to create or approve pull requests.

これ、コードじゃなくて GitHub 側の設定。

Actions の「Workflow permissions」が読み取りのみだと、PR作成が通らない。
つまり、

仕組みは合ってるのに、権限が足りなくて死ぬ

という、CIあるあるに着地する。

ここは UI で2つONにしたら終わりだった（後述）。

最終形：PR/Noopを強制し、日本語で、DraftじゃないPRを出す

ここまで来ると、「動く」だけじゃなくて「運用が気持ちいい」状態に寄せたくなる。

PRが Draft だと、地味にダルい
PRの説明が英語だと、地味に読み飛ばす
変更がないのに黙って終わると、「動いたのか？」が分からない

なので、最終形はこう。

docsを直したら PR（Ready for review） を出す
直すものがなければ noop を出す
PRタイトル＆本文は 日本語
変更対象は /docs と README のみ（ソースは絶対いじらない）

あなたの最新 docs-auto-fix.md はこの形になっていて、かなり“運用できる”と思う：

123456789101112131415161718192021222324252627282930313233343536373839---
on:
  push:
    branches:
      - main
    paths:
      - "src/**"
      - "test/**"
      - "package.json"
      - "tsconfig*.json"
      - "nest-cli.json"
permissions:
  contents: read
  issues: read
  pull-requests: read
safe-outputs:
  create-pull-request:
    draft: false
  noop:
    max: 1
tools:
  edit:
---
# Docs Auto-Fix

## Goal
Keep documentation in `/docs` and `README.md` consistent with recent source code changes.

## Instructions
1. Identify what changed in this push (check the git diff or review the modified files under `src/`, `test/`, and config files).
2. Determine which docs are impacted and update them for accuracy.
3. Only modify documentation files under `/docs` and `README.md`. Do not change source code.
4. Do NOT commit directly. If documentation updates are made, use the safe output tool `create-pull-request` to propose changes.
5. If no documentation updates are needed, use the safe output tool `noop` to explicitly report no action.
6. When creating a pull request, write the PR title and body in Japanese. Include a short summary and test status.
7. Keep updates minimal, precise, and aligned with existing formatting.

## Repo Notes
- If shipping fee rules or API behavior change, update `/docs/shipping-fee-spec.md`.