3行まとめ
- Agentic Coding - 複数の専門AIエージェントが協調して設計->実装->品質保証まで自律的に実行する
- Context Engineering - ルール・設計パターンを体系化してAIの判断精度を向上させる
- 理論ではなく実践済みの方法 - ボイラープレートで試すことができます！
はじめに
Claude Codeを使い始めて、思ったような実装にならなかった経験は皆さん少なからずあると思います。
私は職能（EM）柄、仕組み化言や語化を半分趣味としているので、「Agentic Coding」という手法をClaude CodeのSub agentsを用いて徹底的に実践しました（あえて人間として介入せず、失敗させて仕組みにフィードバックしていく）。失敗する実装を見守るのには最初は違和感がありましたが、今では慣れ、生暖かく見守れています。
その成果物をボイラープレートプロジェクトとして先日公開しました！
この記事は、このボイラープレートを通して、実際のプロジェクトで使える具体的な手法を紹介できることを目指しています。
Agentic Codingとは？
従来の「1つのAIエージェントと対話」から「専門AIエージェントチームとの協働」への変遷。端的にいうとそれがAgentic Codingです。
各AIエージェントは独立したコンテキストを持つため、文脈を保ちながら、精度を極力維持しながら1つのタスク（責務）を完了させることができます。
Context Engineering - LLMに「判断の根拠」を与える技術
2024年辺りから注目されている「Context Engineering」ですが、単にファイルを整理するとか、必要な情報を常に全部与えるといった話とは少し違います。LLMが適切な判断を下すために必要な文脈を、適切なタイミングで提供する仕組みを構築することが重要です。
私は、背景情報の欠落であったり、作業には不要であるコンテキストも提供してしまい必要なコンテキストがぼやけることを防ぐように特に気をつけました。人間のエンジニアでも、背景や理由が分からないまま実装に入ってしまったり、認知負荷が高いと、クオリティの高いものづくりはできないですよね？LLMにも同じことが言えます。
具体的には、以下の3つの観点について気をつけて、仕組みを整備しました。
単一責務の徹底
各ルール・サブエージェントは1つの明確な責務だけを持つように注意しています。例えばtask-executorはTDD（Red-Green-Refactorプロセス）による実装のみ、quality-fixerはlintなどの品質チェックとテスト実行・修正、code-reviewerはコードレビューのみを責務にしています。これで、各サブエージェントが必要なコンテキストを最小限にし、コンテキストが枯渇する前にタスクを完了させられる粒度でのタスク分解が可能になります。
必要な全情報を適切なタイミングで提供
自律的な開発フローの中では、各責務を担当するサブエージェントが責務定義と必要なルールを全て読み込んだ上で、作業を行います。
必要に応じてWebから最新情報を取得し、前提をアップデートするようにもしています。
- 要件分析時 ->
requirement-analyzer定義とビジネスルール - 設計時 ->
prd-creator/technical-designer定義とアーキテクチャ原則 - 実装時 ->
task-executor定義とコーディング規約
対話的な作業をメインとなるLLMと行う場合は、rule-advisorというサブエージェントが活躍します。更新を伴う作業をする際にはClaude Codeが持っているTodoWriteツールを使うことを徹底してもらっています。このTodoWriteを呼び出す際に、rule-advisorが呼び出されるようにし、その作業に必要なルールを解釈し、必要なルールだけをメインLLMに返します。メインLLMはルールを受け取ったら作業の背景と照らし合わせTodoWriteを更新し、作業に入るという振る舞いをします。
これで、更新を伴う作業に必要なルールをもって適切な作業計画を考え実行を進めてもらえるようになります。
これらの工夫により、コンテキストの過不足を防ぎ、各エージェントが最適な判断を下しやすくなります。
この仕組みになるまでにはそれなりに紆余曲折がありました。意図した挙動にならずルールを増やす -> ルール過多になり守ってほしいことを守ってくれなくなる -> ルールを削ったら意図せぬところで挙動が不安定になる...
一番ひどい時はルールからルールへの参照が乱立し、メンテナンスが大変な状態になっていました。そこからrule-advisorの整備、それに合わせたルールの整理が進み、最近は定期的にルールのリファクタリングもできるようになりました。がんばった。
背景情報の明文化（設計ドキュメントの整備）
- PRD（Product Requirements Doc）-> 何を作るか、なぜ必要か
- ADR（Architecture Decision Record）-> なぜその技術を選んだか
- Design Doc -> どう実装するか、なぜその設計か
ボイラープレートでは、設計書駆動での開発を基本的な開発フローとして設計しています。
これらのドキュメントはフローに乗れば必ず作成されるので、実装の背景が失われることを防ぐことができます。
設計書駆動開発の実践
ここからは、ボイラープレートを適用した開発プロジェクトでの、実際の開発イメージを共有します。
実際に手元で動かしてみる場合は、/implementコマンドを用いてください。
/implementコマンドでは、メインLLMにオーケストレーターとしての振る舞いを強制します。各サブエージェントを適切なタイミングで呼び出し、適切なインプット（プロンプト）を与えることで作業完了までを自律的に進めることにフォーカスします。
ステップ1 - 要件の明確化
実現したい内容を伝えることで、requirement-analyzerが要件を整理し、実装規模のアタリをつけます。これによって、以降の設計プロセスが決定されます。
規模に応じたパターン
- 小規模（1-2ファイル）: 簡易計画 → 実装 → 品質保証
- 中規模（3-5ファイル）: 要件分析 → 設計 → 実装 → 品質保証
- 大規模（6ファイル以上）: PRD → ADR → 設計 → 実装 → 品質保証
ステップ2 - 設計書の作成とレビュー・承認
規模に応じて必要なドキュメントが変わりますが、ドキュメントごとのフローは変わりません。
- ドキュメント作成
- 既存の実装の調査
- Webから最新の情報などLLMが持っていない情報を補完
- 関連する設計書の収集（Design DocならPRDとADR、など）
- テンプレートとルールに基づきドキュメントを生成
- ドキュメントレビュー
- 必要に応じて、既存実装の調査
- 必要に応じて、Webから最新の情報などLLMが持っていない情報を補完
- 観点に基づくドキュメントレビュー（責務外の記載、例えばPRDに実装に関する記述があるなどや、達成条件の曖昧さなど）
- ドキュメントレビュー結果を提示し、ユーザー承認を得る。必要に応じてドキュメントを再生成（修正）する
具体的な対話サンプル
●prd-creator（ヘルプ機能PRD作成）
L Done （15 tool uses・34.7k tokens・1n 55.6s）
●PRDを作成しました。
ドキュメントの整合性を確認します。
● docunent-reviewer（PRDレビュー】
L Done （13 tool uses・39.6k tokens・2n 15.65）
●PRDレビュー結果-修正が必要です
PRDを作成しましたが、レビューで以下の重要な修正点が見つかりました：
●重要な修正点
1.実装詳細の除去：PRDから技術的な実装アプローチを開除（Design Docへ移）
成功指標の追加：最新のチャットボットUXベストプラクティスに基づく指準を追加
流定方法の明確化：レスポンス時間等の定方法と機を具体化
対応方針
A）PRDを修正してから進める - 推奨
B）現状のPRDで進めて後で修正
C）修正内容を確認してから判断
どのように進めましょうか？
> Aでお願いします
●PRDを修正します。
●prd-creator（PRD修正）
L Done11 tool uses・ 48.5k tokens・2m 56.75）
●PRDを修正しました。再限レビューを実行します。
● docunent-reviewer（修正後PRDレビュー〕
L Done （6 toolluses・30.0k tokens・1n 48.65）
●PRD承認推奨 - 設計フェーズへ進めます
PRDレビューで承認推奨料定（スコア：92/10g）を受けました。
改善結果
- 実装詳細を削除（PRDスコープ適正化）
- 2025年最新のチャットホットUX指標を追加
- 選定方法と根拠を具体化
- 失敗パターンとリスク管理を追加
次は技術設計フェーズ（ADR/Design Doc作成）に進みます。よろしいでしょうか？
ステップ3 - 実装計画立案・実装
実装計画
設計書が作成できたら、work-plannerが作業計画書を作成します。作業計画書を作成するときに重要なのは、適切な実装フェーズの設計です。
Red-Green-RefactorのTDDアプローチ、価値のある単位での結合テストなど、実装品質を保証するためのガードレールを設けることが、自律的な実装を行ううえで重要になってきます。
そして、結合テストをするとなったときに、レイヤーごとに実装を進めてしまうと結合時の確認がフェーズの後に回ってしまいます。
結合テスト時に問題が見つかると大きな手戻りですし、サブエージェントが不適切な実装をした時の悪影響が波及してしまいます。
どういう単位で分割することで最小限の単位で受け入れ条件（AC: Acceptance Criteria）を確認できるのかを踏まえた、フェーズ分けとタスク分解を行う必要があるということです。
そして作られた計画書を元に、task-decomposerがタスクファイルを生成します。
実装はこのタスクファイルの単位で行われます。つまり、task-decomposerはタスクを1コミットの粒度（論理的に意味のある最小限の変更）に適切に分解することが必要となります。
作業計画がファイル化されているため、実装者（サブエージェント）はコンテキストが増えた状態でタスクの計画を立てなくてよくなります。そうすることで作業に集中してしまいルールを守れなくなるという事態を抑止できます。
ここも試行錯誤があったポイントです。結合したら動かない、mockになっていて確かにテストは通っているが、、、などなど、実装完了と言われた後動作確認から手直しをそこそこやらないといけない事態が発生していました。計画や設計の生成に手を入れたことで意図しない実装になる確率は減りました。
実装
ここまで来れば、あとはタスクファイルを順に取り込み実装していくだけです。
実装はtask-executorが担います。タスクファイルに書かれたTDDアプローチでの実装計画に沿って、実装を進めていきます。
作業進捗をタスクファイルに残すことも責務として定義しているので、不測の中断にも対処できるようになっています。
task-executorは追加したテストの通過までを責務として持っています。Lint/Formatや型チェック（TypeScriptなので）、全テストのパスなど包括的な品質チェックと、問題の修正はquality-fixerが担っています。
実装と包括的な品質チェックまでを1タスクとしてしまうと、品質チェック時にはコンテキストが枯渇気味になっており、意図していなかったり短絡的な修正を行なってしまいがちです。そうならないよう、サブエージェントを分けてコンテキストを分離しています。
品質が保証されたら、メインLLMがコミットを行います。これで1タスクの完了です。
以降はこの実装ループをタスクがなくなるまで続けていきます。
補足 - メタ認知アプローチ
途中で紹介したrule-advisorサブエージェントは、メタ認知アプローチを採用しています。メタ認知とは、自分の思考プロセスを客観的に観察し、調整する能力のことです。LLMにも自問の概念を導入し、タスクの実行前に立ち止まり、必要な情報を集めて調整してもらうようにしました。
LLMには「ユーザーを待たせたくない」という特性（ヘルプフルネス）があります。質問されたら即座に答え、エラーを見たら即座に修正する。この「早く対応し切ろう」とする特性は良し悪しがあり、重要なルールを見落としたり背景理解を飛ばしたりし、結果的に手戻りを生む原因となります。
rule-advisorは、メインLLMがTodoWriteツールで作業計画を立てる際に必ず起動するよう最重要原則として設定しており、意図的に「立ち止まる」タイミングを作ります。
この仕組みにより、まず、タスクの本質を分析し根本目的を理解しようとします。
そのうえで、すべてのルールから必要なルールだけを抽出します。ルールには推奨することや失敗事例などが入っているため、タスクを実行するうえでどういった作業をすべきかを整理できるようになります。
数十ページに及ぶルールファイル全体を読み込むとコンテキストを圧迫しますが、rule-advisorは現在のタスクに必要なセクション（見出し2）を選別して提供します。これにより、コンテキストの枯渇と作業品質向上のバランスを維持した実行が可能になるということです。
オーケストレーションフローの外で対話的に作業をすることはそれなりにあります。
バグを見つけた時やそれこそ自律実装が終わった後の手直しフェーズなどです。この時に意見を求めただけなのに修正を始めたり、ルールを読み込んでもらうのを忘れて変な実装をしたりと、定期的なストレスイベントがありました。この仕組みを組み込んでからはそれなりの確率でrule-advisorは起動してくれるので、だいぶ気持ちが楽になりました。それでも動いてくれない時用に/taskというカスタムスラッシュコマンドを作っていて、タスク実行時のメタ認知を強制させられます。
具体的な対話サンプル
実際に使ってみよう！
文章で説明しても実感が持てないかもしれないので、よければ実際に試してみてほしいです！
npxコマンド一発でプロジェクトを作れます。
# プロジェクト作成（30秒で完了）
npx github:shinpr/ai-coding-project-boilerplate my-project
cd my-project && npm install
# Claude Codeを起動
claude
試してみるのではなく実際のプロジェクトに組み込んでいきたい場合は、docs/rules/project-context.mdやdocs/rules/architectureおよびdocs/rules/rules-index.yamlの修正を行うことを推奨します。
-
docs/rules/project-context.md- このプロジェクトがどういうプロジェクトなのか、どういうユーザー向けなのかや、どういう実装特性があるのか？などを記載します
-
docs/rules/architecture/*.md- このプロジェクトが採用するアーキテクチャを記載します。レイヤードなのか、垂直スライスアーキテクチャ（
docs/rules/architecture/vertical-slice/rules.md参照）なのかといった方法論を記載してください
- このプロジェクトが採用するアーキテクチャを記載します。レイヤードなのか、垂直スライスアーキテクチャ（
-
docs/rules/rules-index.yaml- ルールファイルのメタデータファイルです。
rule-advisorはこのメタデータを元に参照するルールを決定するため、上記2つの内容変更に追従させる必要があります
- ルールファイルのメタデータファイルです。
プロジェクト固有の制約やルールで全ての作業に関わるものはCLAUDE.mdに記述します。
まとめ
対話的に実装するのではないLLMとの向き合い方をお伝えしました。
設計書を先に作り、責務を絞ったAIエージェントが協調して、メタ認知などで適切なコンテキストを適切なタイミングで提供し品質を保つ。こういった要素を組み合わせると、AIコーディングの精度もある程度許容できる水準まで高めることができるんじゃないかと感じています。
実際に何度も実装で使っていますが、まだまだ改善の余地はあります。ですが、徐々に精度が向上していく過程は個人的にとても楽しいです。エンジニアは仕組みが適切に動くことに楽しみを感じる人がそれなりにいる気がするので、一度実装改善のループを回してみると楽しさを感じてもらえるのではないか？と考えています。
理論ではなく実際に動くものとして公開しているので、もし興味があれば触ってみてもらえると嬉しいです！