Claude Code Actionで設計書更新を楽にしたい PR作成時にレビュー + ドキュメント修正を任せる仕組みを構築

設計書の更新を効率化したい

現場で以下のようなご経験はありますか？

「設計書（※）と実装が一致していない」

大小は違えど、それぞれの現場だある話なのかな～と思っています。
私は現在も現場含めて、過去の参画現場でも何度か出会ったことがあります。

「実装が正しいので、設計書を修正します。」といった流れになりますが、こういうときの設計書修正は人によっては退屈でしょう。
こういうところも、生成AIを使って効率化できるのが今の時代だと思います。

※設計書：現場によって多様なものになるかと思いますが、ここでは、以下主に以下を指しています。

• 画面レイアウト
• 画面項目
• 処理仕様

現場の経験より

設計書を作る方法ですが、以下あたりになるでしょうか。

• コード内にコメントで記載
• リポジトリ内にドキュメント用のフォルダを用意
• GithubのWiki
• Excelファイル
• Notion

今回は、「リポジトリドキュメント用のフォルダがあり、そこに格納している」として話を進めます。（Notionと連携する話も面白そうなので、今後やってみたい）

セキュリティ的な観点から実現不可のケース

今回はプライベートな開発で、生成AIの利用は好き放題できますが、現場によってはセキュリティ的な理由からそうはいかないかもしれません。

今後活用OKの開発現場が増えることを願います。

読み進める前に

Claude（問わず生成AI）を用いた取り組み例が気になる方はぜひご覧ください。

実際に試される場合ですが、
何等かの成果物を格納したリポジトリと合わせて、Github ActionsやGithub Appsを用いた作業となるので、そのあたりの前提知識は必要です。

作業開始

実際に作業を進めていきます。

構築自体はすぐに終わります。
大がかりなフローを構築されている方々もたくさんいらっしゃる手前、基本寄りな内容となりますが、
PRがあった場合（OPENとなった場合）に、Claudeを用いて、コードレビューと同時に設計書を修正してもらうようにします。

Flutterプロジェクトを用意

個人開発ではありますが、最近はFlutterの開発機会が多いので、Flutterで話を進めます。
（読み進める上で、Flutter知っている必要は全く問題ないです。）

Flutterのプロジェクト内で、以下フォルダ構成としています。
ルートディレクトリ直下のフォルダ名以外を同じ名前にします。xxxは機能名（signinやsignup）です。

• 設計書のパス：docs/screens/xxx（docsフォルダは自分で用意します）
• ソースコードパス：lib/screens/xxx（libフォルダはプロジェクト作成時に自動で用意されます）

コードベースで設計書を作成

実際にワークフローを導入する前に、現在のコードからmarkdown形式の設計書を準備してもらうことにしました。（Claude Codeを利用）

Issueを作成し、コメントでclaudeメンションを設定して、コード作成を依頼するだけです。（オレンジ枠内）

以下の通り、4ファイル作成してくれました。
機能によって多少異なるかもしれませんが、概ねこの4ファイルになりそうです。

成果物に感動

作成してくれたファイルの中身を見てみましたが、こんな形で作成してくれるんだ～～と感動しながら作業していました。

今回のワークフローに用いる試験的な設計書が完成しました。

今回は、実験的な目的も含めて作成した設計書です。

プロンプトやワークフローの工夫でより良いものにできると思うので、そういったことを今後進められればと思います。

この後、実際にワークフロー作成を進めていきます。

ワークフロー作成

Github Appのインストール

対象のリポジトリにGithub Appインストールをします。

上記ドキュメントに沿って、/install-github-appを実行します。質問に対して適宜回答をします。私は以前このコマンドを実行しています。初回実行の方とは少し表示内容が異なるかもしれません。

Github Appsを用いた作業になります。

以下の順番で作業を進めます。

１./install-github-appを実行
２. Use current repository:を選択
３. ブラウザが起動し、Github Apps：Claudeを表示（Configureから対象リポジトリの選択）
４. ブラウザを閉じて、ターミナルでEnterを押す
５.ワークフローファイルをどうするか選択

ターミナルの状態

```
 Existing Workflow Found
 Repository: eno-conan/flutter-starbucks-clone
 
 A Claude workflow file already exists at .github/workflows/claude.yml
 What would you like to do?

 ❯ 1. Update workflow file with latest version                                                                                                                        
   2. Skip workflow update (configure secrets only)                                                                                                                   
   3. Exit without making changes                                   
```

６.トークン作成かAPIキーを選択

ターミナルの状態

Install GitHub App

Create a long-lived token with your Claude subscription

> Enter a new API key
sk-ant… (Create a new key at https://console.anthropic.com/settings/keys)   

７.既存APIキーか新規作成を選択

ターミナルの状態

Install GitHub App                                                             
Setup API key secret

ANTHROPIC_API_KEY already exists in repository secrets!

Would you like to:

> Use the existing API key

  Create a new secret with a different name

８.インストール成功、ブラウザでPR作成画面が起動

ターミナルの状態

```
Install GitHub App
Success

✓ GitHub Actions workflow created!

✓ Using existing ANTHROPIC_API_KEY secret

Next steps:
1. A pre-filled PR page has been created
2. Install the Claude GitHub App if you haven't already
3. Merge the PR to enable Claude PR assistance 
```

９．PRを作成

これでマージまで実施すればワークフローは完成ですが、この後少しだけ内容を追加します。

プロンプト内容を追加

以前実行した際にclaude-code-review.ymlまで生成してくれていたか覚えていないのですが、このファイルにやってほしいことを追加します。
コードベースで設計書を作成の成果物を受けて、ベースプロンプト作成します。

• コードレビュー実施（既にyamlファイルに定義済）

• 修正資材に対する設計書修正を依頼するプロンプトを追加

  今回の修正について、docsフォルダ以下の同階層に設計書を作成、既にファイルがある場合は更新してください。作成する場合は「概要」「UI設計」「認証による表示制御」「エラー制御」の4つを作成します。変更履歴用のファイルは不要です。

  英語にしてから、プロンプトを設定

  Please continue by creating design documents in the same hierarchy under the docs folder for the current modifications in the lib folder, or updating them if files already exist. When creating new documents, please create four sections "Overview", "UI Design", "Authentication-based Display Control", and "Error Control". Change history files are not required.

動作確認

コードがほぼ完成している「仮会員登録」に関してコード修正を行いました。
PRを作成し、コードレビュー + 設計書作成をやってくれることを確認しました。

内容を確認して、必要があれば手直しをします。

Claudeによる設計書作成時のコミットメッセージ

Claudeによって生成されたファイル

今回は、緑枠部分だけが必要でした。
取り消し線を記載したファイルは、PRマージ時には削除しています。

プロンプト通りの作成はできていない

私は以下のプロンプトを英語にして設定しました。

「概要」「UI設計」「認証による表示制御」「エラー制御」の4つを作成します。

しかし、実際作成された設計書は２つだけでした。
認証無しで表示可能な画面のため、「認証による表示制御」はないですが、「エラー制御」はあります。

こういった「XXXしてほしいけど、期待通りにならない。」
そういった部分の解決策を考えるのが、生成AIを用いた効率化を実現する過程の醍醐味の１つだと思います。

AIと共に開発を進めるためのキャッチアップ

今回は設計書を作成してもらう部分だけを試しました。

FlutterやGoogleのドキュメントでも、AIを用いた開発に関する情報が色々載っています。こういった情報なども活用しながら、より現代的な開発ができるようにキャッチアップをする必要があります。

まとめ

今回は、設計書の更新作業を生成AIに任せることを試してみました。
まだ２，３回だけですが、実際に生成される設計書にばらつきがあるのは、上述した通りです。

ワークフローの作成前に記載した通り、プロンプトやワークフローの工夫次第で、より安定した形で設計作成や修正を行ってくれそうです。

最後に、claude-code-actionリポジトリの ROADMAP.md について取り上げて締めようと思います。

今後のアップデートに関する話が記載されていますが、気になった内容を取り上げます。

botによるコメントでワークフローを動かす（導入済）

元々は以下の通り、「人間による操作でなければClaude Codeは起動しない」といった話だったようですが、botでもワークフローが動くようになりました。

Currently, the Claude Code GitHub Action blocks all bot users from triggering Claude through the checkHumanActor validation function. This limitation prevents useful automation scenarios where bot accounts (like dependabot, renovate, or github-actions) could benefit from Claude's assistance.

checkHumanActorというワードが使われていました。

dependabot.ymlによるPR作成時に、Claudeによる検証などが行えそうですね。
以下botを許可する場合の実装例です。allowed_botsに許可するbotをカンマ区切りで列挙します。

  - name: Run Claude Code Review
    id: claude-review
    uses: anthropics/claude-code-action@v1
    with:
      anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
      additional_permissions: |
        actions: read
      # Optional: allow bot users to trigger the action
      allowed_bots: "dependabot[bot],renovate[bot]"
      prompt: |
        Please check if this PR is allowed to merge into the main branch.
        Use `gh pr comment` with your Bash tool to leave your review as a comment on the PR.
      # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
      # or https://docs.claude.com/en/docs/claude-code/sdk#command-line for available options
      claude_args: '--allowed-tools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"'

別のリポジトリも参照可能に（今後導入予定）

以下内容は特に興味があります。
別のリポジトリの参照ができれば、よりできることが広がりそうです。

Cross-repo support - Enable Claude to work across multiple repositories in a single session

参考資料