目的
株式会社リンクアンドモチベーションでエンジニアリングマネージャーをしております、川津（@KawatsuYusuke）です。
この記事は主に社内で 「2025/12/01 時点では、こうやって AI Agent 駆動開発するのがいいかな？」 というのを展開する目的で書き始めました。
細かい詳細は省き、大方針としての考え方や開発における流れについて記述しております。
前提
本書は次に示す開発要件に適用するプロセスです。
- Web アプリケーション開発（SaaS）が対象
- Claude Code をコード生成 Agent として利用
本書は 特定の技術スタック等にはなるべく依存しない ように書いています。
一応書いておきますと、実際には以下の開発環境で採用しています。
主に新規プロダクト開発で採用しておりますので、既存プロダクトの開発におけるプラクティスには従えていない箇所があります🙏
概念と構造
AI Agent 駆動開発では様々な概念が登場しますが、重要な項目は主に下記の６項目になると考えています。（命名は私のオリジナルです😅）
| # | カテゴリ項目 | 説明 |
|---|---|---|
| 1 | ワークフロー | 一連の開発プロセス（要件定義 → 設計 → 実装 → テスト）を AI Agent に強制させる仕組み、ワークフロー。 |
| 2 | 手順 (プロシージャ) |
AI が実行する複雑な一連の手順 をパッケージ化して再利用できる様にしたもの。 |
| 3 | ツール | AI が状況に応じた判断で呼び出せる ルールベースで一貫した応答を返す (Blackbox) もの。 |
| 4 | ドキュメント (知識) |
開発するプロダクト・プロジェクトのルールやドメインについて記したドキュメント・知識。 |
| 5 | グルー (のり) |
AI が ワークフロー に従って開発を行う際に、適切な 手順（プロシージャ） や ツール、ドキュメント（知識） が 確実に利用・参照される仕組み。 |
| 6 | ガードレール | AI の挙動に依存せず自動的に実行 され、コードベースの品質を常に保証する仕組み。 |
図解
実際のツール・仕組みとの対応表
Claude Code や MCP など、実業務で利用する実際のツール類を下表に当てはめてみます。
| カテゴリ項目 | 小項目 | 説明 |
|---|---|---|
| 1. ワークフロー | spec-kit | 独自運用をやめ、2025年11月のデファクトに準拠。 |
| 2. 手順 | Slash commands | 人間が指示する、特定の手順パッケージ。 |
| Agent Skills | AI Agent が自律的に実行する特定の手順パッケージ。 | |
| Subagents | Agent Skills に似ているが、結果だけを返しコンテキスト節約になる。 | |
| 3. ツール | Bash script | プロジェクトに特化したツールは Bash や Python などのスクリプトで実装するのが軽量。 |
| MCP | 上記 Bash script でダメな場合に、MCP を採用。 | |
| 4. ドキュメント | 要件定義書 | プロダクトの要件について詳細に・漏れなく記述し、SSOT であること。 |
| 基本設計書 | アーキテクチャなど、特定の機能開発に依らず通年で参照されるもの。 | |
| コーディング規約 | 基本はリンター（6. ガードレール）で強制したいが、推奨されるコード規約について明記する。 | |
| 5. グルー | CLAUDE.md |
CLAUDE.md はできるだけ記述量を最小に抑え、グルーとしての役割に徹する。 |
| 実装計画書 | spec-kit が生成する実装計画書には、前述した（2.手順）、（3.ツール）、（4.ドキュメント）が直接参照指示されている状態が望ましい。 | |
| 6. ガードレール | Hooks | 正確には、後述するガードレールを Hooks で実行しよう！という意味。 |
| コンパイラ | コンパイルを伴う言語（e.g., TypeScript) では、SyntaxError 等のミスは静的に検知できる。 | |
| リンター | コーディングルール違反や、アンチパターンなどの検知。 | |
| その他 (静的解析系) |
... |
Directory Layout.
一例として、プロジェクトは下記の様なディレクトリ構造となる。
.
├── .claude
| | ### Subagents ###
│ ├── agents
│ │ ├── build.md # `npm run lint` を subagent で.
│ │ ├── lint.md # `npm run build` を subagent で.
│ │ └── test.md # `npm run test` を subagent で.
│ | ### Slash commands ###
│ ├── commands
│ │ └── {コマンド名}.md
| | ### Event handlers ###
│ ├── hooks
│ │ └── hooks.json
| | ### Agent Skills ###
│ └── skills
│ ├── run_dev # `npm run dev` をする.
│ │ └── SKILL.md
│ └── run_db_migration # DBマイグレーション実行.
│ └── SKILL.md
│
├── docs
│ ├── adr # Architecture Decision Records.
│ │ ├── adr_01.md
│ │ └── adr_02.md
│ └── requirements # 要件定義書.
│ ├── index.md
│ ├── uc_01.md
│ └── uc_02.md
|
├── tools
| | ### Tools ###
│ └── {tool_name}.sh
|
├── src
| | ### ソースコード ###
│ └── {*.ts, etc...}
│
└── package.json
カテゴリ項目の解説
1. ワークフロー
標準的な使い方は spec-kit の公式ドキュメントに従って下さい。独自の運用については以下の通りです。
- 要件定義書は
/docs/*配下 (4. ドキュメント) に生成させ、git管理対象として永続化する - その他の生成物に関しては、feature の実装が 完了 = PR merge した時点で破棄する
2. 手順
Slash commands vs Agent Skills
- Slash commands は 人間が指示 して実行したい手順に適用します
- Agent Skills は AI Agent が自律的に判断して自動的に実行 させたい手順に適用します
また、Agent Skills として実装し、Slash commands 内でそれを呼ぶ、という風にすると、人間が指示したとき＆AI Agent が自動で実行したとき、の双方で挙動がずれなくて済みます。
---
description: データベースのマイグレーションを実行します.
allowed-tools: Bash, Read, Write, Edit, Grep, Glob
---
`run_db_migration` Agent Skill を実行してください。
Subagents
Subagents は Agent Skills と似ていますが、その利点は 実行結果のみを返すので、コンテキストを消費しない 点にあります。従って、使い分けは以下の通りです。
- 実行結果だけ分かればよい → Subagents を使う
- 処理の経過を Agent に把握させたい → Agent Skills を使う
一般的に、build、lint、test などの単純な処理を Subagents で行い、
より複雑で失敗した際に原因究明が難しい処理を Agent Skills で行うことが多くなります。
また、Agent Skills から Subagents を呼び出すことも出来るので、それが最も処理の成功率とコンテキスト節約のバランスに貢献します。
Agent Skill
├── Subagent A
├── Subagent B
└── Subagent C
3. ツール
ツールの実装には「Bash script」をオススメします。
というのも、ツールで行いたい処理はプロジェクトに特化することが多く、自前で実装・カスタマイズすることが多いからです。
無理に MCP を利用する必要はありません。Figma へのアクセスなど MCP でないと難しい・手間がかかる場合に限って利用したいですね。
4. ドキュメント
ベクトルストア等を使う手もありますが、初手は以下の様にプロジェクトルートに /docs ディレクトリを作成してマークダウン形式で各種ドキュメントを拡充することが、最も安価で効果的です。
.
└── docs
├── adr # Architecture Decision Records.
│ ├── adr_01.md
│ └── adr_02.md
└── requirements # 要件定義書.
├── index.md
├── uc_01.md
└── uc_02.md
ドキュメントはコードの修正よりも先に行います。
詳細に・漏れなく記述し SSOT であることを保証しましょう。
5. グルー
折角用意した（2.手順）、（3.ツール）、（4.ドキュメント）も、AI Agent が使ってくれなければ意味がありません。
最も標準的な手法は CLAUDE.md で上記の利用を指示することです。
しかし、仕様駆動開発（spec-kit）においては、Claude Code への指示の大半は「実装計画書」になります。実装計画書にこれらの使用が直接指示として書かれていれば、最も利用率が高まります。
以下、「実装計画書」に記述する指示の悪い例と良い例です。
実装が完了したら、ビルドを行ってください。
上記の様に記述すると Claude Code は直接ビルドコマンド (e.g., npm run build) を行うことが多いです。
実装が完了したら、`build` Agent Skill を実行してください。
この場合は Claude Code は期待通りに build Agent Skill を実行してくれます。
6. ガードレール
まずは昨今一般的に行われるガードレール類は最低限用意しましょう。
- ビルド (
e.g., npm run build) - リンター (
e.g., npm run lint) - ユニットテスト (
e.g., npm run test)
これらを自動的に実行する導線は、主に次の２つがあります。
-
Hooks で実行
→ 現状は Event type が「ファイル修正後」等しかなく、実行頻度が高くなり使いづらいです - 「実装計画書」に記述 → AI Agent が実行
→ こちらのケースでは、前述したように Subagents 化するのが望ましいです
その他にも AI Agent 開発以前から行われている、様々な従来のフック手法が有効です。AI の意思とは独立して確実に実行されるようになっていると良いですね👌