2
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

設計はADR、実装はテストとレビュー ― スキルで試したAI駆動開発

2
Last updated at Posted at 2026-11-18

はじめに

この記事について

GitHub Copilotと、Matt Pocock氏が公開している「skills」(以降、スキルと表記します)を使って、Webアプリケーション開発のプロジェクトでAI駆動開発を試した記録です。

開発を「設計」「Issue化」「実装」「PR・レビュー」の4つのフェーズに分け、各フェーズでどのスキルを、どの場面で、どのように使ったかを紹介します。あわせて、設計判断をADR(Architecture Decision Record)として残す運用や、使ってみた感想・課題も書きます。プロジェクト自体は概要の紹介にとどめ、詳細な設計・実装の内容は扱いません。

AI駆動開発は、私たちもまだ模索中です。この記事は最適解やベストプラクティスを示すものではありません。一事例としてお読みください。

対象読者

  • AI駆動開発に興味がある方
  • スキル(SKILL.md)を使ったAI活用に興味がある方

前提知識

スキルとは

スキルは、AIエージェントに「ある作業のやり方」を教えるための指示書です。SKILL.md というMarkdownファイルに、作業の手順や守るべき方針を書いておきます。

スキルは、次のように使います。

  • リポジトリ内(このプロジェクトでは .agents/skills/)に置いて、チームで共有できる
  • チャットで /skill-name と入力して呼び出せる
  • 呼び出し方は2種類ある
    • 手動のみ: 誤って自動実行されないよう、人が明示的に呼ぶ
    • 自動検知あり: 会話の文脈から、AIが必要に応じて読み込む

スキルは、毎回プロンプトに手順を書く代わりに、「手順を部品として保存しておく」仕組みとして考えると分かりやすいです。

標準仕様「Agent Skills」

スキルの形式は「Agent Skills」というオープン標準として、仕様が公開されています。

もともとAnthropicで仕様が作られて、Linux Foundation傘下のAgentic AI Foundation(AAIF)に寄贈されました。

仕様では、スキルは SKILL.md を含むディレクトリで、SKILL.md には名前(name)と説明(description)が必須とされています。ライセンスなどの任意の項目や、スクリプトや参考資料を同梱するディレクトリも定められており、GitHub Copilotを含む、多くのエージェントが対応しています。

Matt Pocock氏のスキルとは

Matt Pocock氏が GitHub で公開しているスキル集です。設計の詰め、チケット分割、TDD、コードレビューなど、開発の各場面向けのスキルが複数公開されています。

このプロジェクトでは、その一部を使いました。ここでは、実際に使った次のスキルに絞って紹介します。

スキル 種別 役割 使ったフェーズ
/grill-with-docs 手動のみ 設計をインタビュー形式で詰め、ADRと用語集を記録する(内部で /grilling と /domain-modeling を使う) 設計
/to-issues 手動のみ 計画やADRを、独立して着手できるIssueに分解して起票する Issue化
/implement 手動のみ Issueをもとに実装する(内部で /tdd と /code-review を使う) 実装
/tdd 自動検知あり テスト駆動開発、「失敗するテストを書く(red)→ テストを通す最小限の実装をする(green)→ コードを整える(refactor)」を小さく繰り返す 実装
/code-review 自動検知あり 差分を「標準準拠」と「仕様適合」の2軸でレビューする 実装・レビュー

ADRとは

ADR(Architecture Decision Record)は、設計判断を1件ずつ記録する短い文書です。「何を決めたか」だけでなく、「なぜそう決めたか」「他にどんな案があって、なぜ採らなかったか」を残します。

このプロジェクトでは docs/adr/ に連番(0001-...md)で置き、ステータス(Accepted など)を持たせています。決定を覆すときは、元のADRを書き換えずに Status を Superseded にして、新しいADRから参照します。履歴が残るので、後から「なぜこうなっているのか」を辿れます。

ADRを採用する理由(メリット)

  • 経緯を辿れる: 後から参加した人や、数か月後の自分が、「なぜこの設計なのか」を調べられる
  • 同じ議論を繰り返さない: 検討して採らなかった案とその理由が残るので、蒸し返しを防げる
  • 判断のタイミングで残せる: 決めたその場で1件ずつ書くため、後でまとめて書くより正確に残る
  • 変更の影響が見える: 決定を覆した履歴が残り、どの決定がどう変わったかを追える
  • AIとの共有に使える: AIは会話やセッションが変わると前提を忘れる。ADRは、AIと人が同じ前提で作業するための共有メモリとして役に立つ

プロジェクトの概要

BIPROGYグループでは、Lazarus社のAI「RikAI2」(文書処理に特化したマルチモーダルLLM)を取り扱っています。

RikAI2を複数の企業に安全・公平に提供することを想定して、制御基盤「ハーネス」を開発しました。ハーネスが唯一の入口として、認証・利用量・負荷を一元的に制御します。Webアプリケーション(APIと管理画面)として開発しています。

このハーネスは、社外にはリリースしておらず、サービスとして提供していません。

環境・バージョン

区分 項目 バージョン
開発環境 Visual Studio Code 1.145.0
AI GitHub Copilot Chat(Visual Studio Code拡張機能) 0.41
スキル mattpocock/skills v1.0.1 と v1.1.0 の間の時点(※1)

※1 公式のタグでいう v1.0.1 と v1.1.0 の間の時点の版です。
最新版とは一部名称などが異なります。例えば、用語集のファイル名は CONTEXT.md ですが、最新版では GLOSSARY.md です。また、/to-issues は、最新版では /to-tickets です。
執筆時点(2026年11月17日)の最新のタグは v1.3.2(2026年10月29日公開)です。最新版の情報は、公式のリポジトリをご確認ください。

開発の進め方(基本の流れ)

4つのフェーズ

開発を次の4つのフェーズに分けて進めました。どのフェーズでも、AI(GitHub Copilot)が作業し、人が判断・承認することを原則にしています。

これはあくまで基本の流れです。実際は一直線には進みませんでした。例えば、

  • 設計とIssue化の順序が前後する(先にIssueを起票して、設計の中身を詰める)
  • 実装の途中で設計の疑問が出て、/grill-with-docs に戻る
  • /implement は完了時に自動で /code-review(自己レビュー)を呼ぶが、PRの前などに、人が手動で /code-review を改めて実行する

また、どのフェーズでも、後述の「ナレッジ文書」(copilot-instructions.md、ADR など)を参照させています。

各フェーズでのAIと人の役割

フェーズ AI(GitHub Copilot)が作業 人が判断・承認
① 設計 論点を1問ずつ推奨案つきで質問し、ADRに反映する 質問に答え、設計判断を下す
② Issue化 依存関係を整理して、Issue案を提示する 分割の粒度を承認し、Issueをアサインする
③ 実装 テストと最小実装を小さく繰り返し、自己レビューする 実装方針を確認し、結果を見て指示する
④ PR・レビュー PRをレビューして指摘する 指摘を採否判断し、最終マージする

共通の土台:ナレッジ文書

AIと人が同じ前提で進めるため、次の文書を各フェーズで参照させました。

文書 役割
.github/copilot-instructions.md Copilotに常に読ませる指示(プロジェクトの概要、技術スタック、守るべき原則。例:未決事項をAIに勝手に確定させない)
CONTEXT.md 用語集。用語の定義と、使わない言葉(Avoid)を記録する
docs/adr/ 設計判断の記録(このプロジェクトでは28本)
docs/requirements.md 要件の正本。「確定事項」と「未決事項」を分けて書く

フェーズ別:どのスキルを、どう使ったか

① 設計:/grill-with-docs

入力 要件、課題
AIの動き 論点を1問ずつ、推奨案つきで質問する。コードや既存ドキュメントから分かることは、質問せず自分で調べる。決まった内容をADRや用語集に反映する
人の動き 質問に答え、設計判断を下す。未決事項を、AIに勝手に確定させない
出力 ADRなどのドキュメント

/grill-with-docs は、/grilling(徹底的にインタビューするスキル)と /domain-modeling(用語集とADRを記録するスキル)を組み合わせたスキルです。

やり取りのイメージ(説明用に作成した例であり、実際のやり取りではありません。人がスキルとあわせて相談を投げかけるところから始まります)

人 : /grill-with-docs
     推論APIは、今はmultipart/form-dataで画像と設定を受け付ける設計になっています。
     ただ、さまざまな企業のシステムから呼ばれることを考えると、
     汎用的なJSONのほうがよいのではと思っています。見直したいです。

AI : ご提案ありがとうございます。現状のADRとコードを確認しました。
     現在のADR-0001では、multipartを維持し、サーバー側で転送先が求めるJSONに
     変換する方針になっています。
     JSONに変更する場合、次の点を決める必要があります。
     1. 画像はBase64文字列で受け取る形でよいか(データサイズは増えます)
     2. multipartのサイズ設定が効かなくなるため、ボディサイズの上限を明示するか
     3. 切替方法を、既存の形式との併存にするか、JSONへの一斉切替にするか
     まず1問目です。推奨は「Base64文字列で受け取る」です。よろしいですか?

人 : はい、それでお願いします。

AI : ありがとうございます。2問目です。……(以降、1問ずつ続く)
     3問目の切替方法については、既存のクライアントへの影響を考慮して、
     併存を推奨します。いかがでしょうか。

人 : まだリリース前の、最初の開発段階です。切替を考慮する必要はないため、
     JSONへの一斉切替でお願いします。

AI : 承知しました。後方互換は持たない前提で、ADRを作成します。
     あわせて、元のADR-0001を更新します。

できあがったADR(実際のADRをもとに簡略化したものです)

# ADR-0002: 推論APIをapplication/jsonのみに移行する

- Status: Accepted
- Supersedes: ADR-0001(「公開APIはmultipartを維持する」という決定のみ)

## Context
ADR-0001では、公開APIはmultipartのまま維持し、サーバー側で転送先のJSON形式に変換する、
と決めた。しかし、複数の企業のさまざまなアプリから受け付ける想定のAPIとしては、
より汎用的なJSONのほうが適切と判断した。

## Decision
- 公開APIはapplication/jsonのみを受け付ける(一斉切替。後方互換は持たない)。
- 画像はBase64文字列で受け取る。
- リクエストボディ全体に、サイズの上限を明示する。
- multipartで受けた場合は、415で拒否する。

## Consequences
- リリース前の開発段階のため、既存クライアントへの影響は考慮しない。
- multipartのサイズ設定への暗黙の依存を解消できる。
- サイズ上限の値は暫定であり、実データが得られたら見直す。

## Alternatives considered
- multipartのまま維持し、サーバー側でJSONに変換する(ADR-0001の案): 汎用性で劣るため採らない。
- multipartとJSONを併存させる: 実装とテストが二重になる。リリース前で後方互換が不要なため採らない。

この例のように、「何を変えるか」だけでなく、「何が変わるか(影響)」「暫定である点」「採らなかった案とその理由」を残せるのが、ADRのよいところだと感じました。

決定を覆すとき

設計は後から変わります。上の例では、一度決めた「multipartを維持する」という決定(ADR-0001)を覆しています。このときは、

  1. 元のADR-0001の Status を「Superseded by ADR-0002」にする。ただし、覆すのは「multipartを維持する」という決定だけで、アダプタとして変換する基本方針は有効なまま、と明記する
  2. 新しいADR-0002で、何を変えるか、何は変えないかを書き、元のADRを参照する

という形で更新しました。/grill-with-docs で「既存ADRとの整合性」を確認させると、こうした更新漏れにも気づけます。

用語集(CONTEXT.md)

用語の揺れも、AIとの対話では問題になります。用語集には、定義に加えて「使わない言葉」を書きます。

**利用者 (User)**:
1契約に所属する個人またはシステムアカウント。
_Avoid_: ユーザー(カタカナ)、エンドユーザー

AIが話題にする言葉と、Issueやコードの用語を揃える効果がありました。

② Issue化:/to-issues

入力 ADRなどのドキュメント
AIの動き 計画を、単独で動作確認できる単位に分解する。依存関係を整理して、Issue案を番号つきで提示する。承認を得てから起票する
人の動き 分割の粒度と依存関係を確認して承認する。起票されたIssueを確認し、アサインする
出力 独立して着手できる実装Issue群

/to-issues は、分解の方針として 縦切り(tracer bullet) を採用しています。「データベース層だけ」「画面だけ」と層で分けるのではなく、全層を貫く薄い一本の経路を1つのIssueにします。完成した時点で動作確認でき、早い段階で全体がつながることを確認できます。

AIが提示する案には、次の項目が含まれます。

  • タイトル
  • Blocked by(先に終わらせるべきIssue)
  • 対応するユーザーストーリー

人は、この案に対して「粗すぎる/細かすぎる」「依存関係が違う」などを指摘します。承認してからIssueが起票されるので、勝手にIssueが増える心配はありません。

テンプレートの活用

Issueの種類ごとに、GitHubのIssueテンプレートを用意しています(機能追加、バグ報告、設計、ドキュメント、環境整備、リファクタリング、調査、テストの8種類)。

/to-issues による起票では、このテンプレートをベースにIssueを作成してもらいました。記載項目が揃うため、実装時にAIが読む情報の品質が安定します。

このプロジェクトのIssueは、全部で43件です。/to-issues で起票したもののほか、手動で起票したものも含みます。

③ 実装:/implement(/tdd + /code-review)

入力 1件のIssue
AIの動き テストと最小限の実装を、小さく繰り返す。単体テストはこまめに、全テストは最後に1回実行する。完了後に自己レビューして、コミットする
人の動き 実装方針を確認し、結果を見て指示する
出力 コード、テスト、ドキュメント、コミット

/implement は、内部で /tdd と /code-review を組み合わせて動く、短いスキルです。大まかには、次の流れで進みます。

  1. 可能な範囲で /tdd を使い、事前に合意した単位でテストを書いて実装する
  2. 型チェックと単体テストはこまめに、全テストは最後に1回実行する
  3. 完了したら /code-review でレビューする
  4. 現在のブランチにコミットする

実装を指示するときは、対象のIssueを指定して /implement を呼びます。

/tdd は、「テストを1つ書く → 最小限の実装で通す」を繰り返すスキルです。AIにまとめて実装させると、テストが後付けになりがちですが、/tdd を使うことで、テストを先に書く進め方を取り入れやすくなると感じています。

また、完了時に /code-review が自己レビューをしてくれるので、人がレビューする前に、規約違反や取りこぼしをある程度減らせます。

④ PR・レビュー:Copilot + /code-review

入力 実装コード、PR
AIの動き GitHub上でCopilotがPRをレビューして指摘する。/code-review が差分を2軸で確認する
人の動き 指摘を採用するか判断し、修正する。レビュアーは問題があれば修正を依頼し、問題がなければマージする
出力 レビュー、マージ

PRは、GitHubのPRテンプレートをベースに、AIに作成してもらいました。

運用は次の通りです。

  1. Issueの担当者がPRを作成し、GitHub上でCopilotをレビュアーにアサインする
  2. Copilotの指摘のうち、採用するものを修正する
  3. 人のレビュアーが /code-review を使って差分を確認する
  4. レビュアーは、問題があれば指摘して修正を依頼する。担当者が修正し、再度レビューを受ける(問題がなくなるまで繰り返す)
  5. 問題がなければ、レビュアーがマージする

/code-review は、次の2つの軸を並列のサブエージェントでレビューし、結果を並べて報告します。

  • Standards(標準準拠): リポジトリに書かれたコーディング規約に従っているか
  • Spec(仕様適合): 元になったIssueや仕様の要望を満たしているか

「規約は守っているが、Issueの要件を満たしていない」といった見落としに気づきやすくなります。最終的な判断とマージは人が行う点は、他のフェーズと同じです。

使ってみた感想

約3か月(2026年7月〜10月)の開発で、コミットは317件、Issueは43件、PRは36件、ADRは28本になりました。

少人数でも効率的に開発できた

2、3人の開発チームで進めましたが、AIに作業を任せ、人は判断と確認に集中するという分担ができたので、少人数でも効率的に開発できたと感じています。

ADRと用語集で、開発のブレが減った

ADRと用語集を、AIと人が参照する共通の土台にしたことで、AIエージェントや開発者ごとの判断のブレ、用語の表記揺れが減ったと感じています。設計判断がADRとして積み上がり、後から経緯を辿れる点も助かりました。

最低限のスキルに絞ったのはよかったかもしれない

公開されているスキルは多数ありますが、使ったのは4つのフェーズに対応する最低限のものだけです。たくさんあると、使いこなせなかった可能性があります。フェーズごとに使うスキルが決まっていたので、迷わず進められました。

一方で、使っていない他のスキルについては、今後試していきたいと思います。

課題・つまずき

並行して開発すると、ADRがぶつかる可能性がある

ADRは、既存の最大番号に1を足して採番する方式です。そのため、別々のブランチで並行して開発し、それぞれがADRを追加すると、番号が重なる可能性があります。同じテーマについて、内容が食い違うADRができる可能性もあります。Gitのコンフリクトのように、どこかで調整が必要になります。

全自動ではない

AIが作業し、人が成果物を確認する。この繰り返しで進めるため、開発は完全な自動化ではありません。これが良いか悪いかは、議論の余地があると考えています。人が確認するからこそ品質を保てる一方、確認のたびに作業が止まります。

人のレビューがボトルネックになる

Copilotや /code-review でレビューをしていますが、最終的には人の確認が必要です。AIで実装が速くなる分、判断やレビューが人に集まり、ボトルネックになりえます。前述の全自動ではないことが、このボトルネックにつながっていると感じています。

料金・ライセンスの問題

GitHub Copilotの料金体系は、今後も変更されうるものです。変更があると、AI駆動開発にかかる費用の見通しが変わり、導入や活用の効果をどう評価するかにも影響します。会社や組織でライセンスを使う場合は、特に費用面の影響を受けやすいと考えています。最新の料金体系は、公式の情報をご確認ください。

教育・人材育成の面

AIに多くを任せられる分、特に若手が設計・実装・レビューの経験をどう積むか、キャリアにどう影響するかが気になります。AI駆動開発は私たちも模索中で、ベストプラクティスが分かっておらず、運用ルールや教育の整備もこれからです。私たちのチームでは、今回の進め方を、他のプロジェクトにも適用していきたいと考えています。

まとめ

  • 4つのフェーズを基本に、各フェーズで必要なスキルを使い分けた
  • 設計はADRで、実装はテストとレビューで確かめる。AIに作業を任せ、判断は人が持つ
  • ただし、この進め方は試行の途中である。フェーズは一直線ではなく、行き来しながら進めた

AI駆動開発において、スキルはどれほど重要なのでしょうか。私たちの感覚では、フェーズごとにAIの動きを揃えてくれる、大切な土台になりました。一方で、並行開発やレビュー、コスト、人材育成など、まだ模索すべき課題も多くあります。

この記事が、AI駆動開発を進める方の参考になれば幸いです。私たちも、今後も試行錯誤しながら模索していきます。

参考

We Are Hiring!

2
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
2
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?