インモビインモビ

AIコーディングを効果的に実行できるボイラープレートを作りました。

https://github.com/shinpr/ai-coding-project-boilerplate

作成しようと考えたきっかけは、最近数名のエンジニアと話す中で、AIコーディングの領域でも人によってそれなりに活用状況の差があるのを実感したことです。
さらに、よくよく話を聞くと、思ったとおりの結果が生成されなかったことで、そこから先の活用が推進されていかないということが分かりました。

そのため、要件の整理などは人と協働しながらも実装はAIが自律的に行える一式のルールとSub agentsをボイラープレートとして公開することで、AIコーディングへの関心や活用イメージを深められないかと考えました。

私が現在社内向けのチャットボットで活用しているルールから、プロジェクト固有のコンテキストを除去し、チューニングしたものをまるっと公開しています。

なぜルールとSub agentsが必要なのか

AIコーディングで起きる「品質のバラつき」問題

AIとペアプロしていて、
最初は調子よく実装が進んでいたのに、気づいたらanyだらけになっていたり、同じような処理が複数箇所に散らばっていたり、テストケースが重複していたり、モックの使い方がバラバラだったり、、、
といった経験はないでしょうか？

私が作業をしている際も、このような問題に定期的に遭遇します。私は、その度に修正指示を出すのではなく、なぜそのような生成に至ったのかをAIとともに紐解き、ルールにフィードバックをするという活動を行い、品質の軌道修正を行なっていきます。つまり、指示の体系化を行うことが重要だと感じています。

ルールファイルの設計思想

人間のエンジニアには「経験による暗黙知」があります。「このケースではこう書くよね」「この規模ならテストのこの実装をutilsに切り出すよね」といった判断を、経験から自然に行います。

ですが、AIにこの暗黙知は通じません。だからこそ、明示的なルールが必要になります。

# 悪いルール例
any型は使用禁止

# 良いルール例（このボイラープレートの実例）
## 型安全性の確保
- ✅ 推奨: unknown型 + 型ガード
  - メリット: 実行時エラーを防ぎ、型の整合性を保証
  - デメリット: 初期実装コストがやや高い
- ❌ 避けるべき: any型の使用
  - 型チェックが無効化され、実行時エラーの温床になる

推奨される行動をベースに、避けるべき事柄の背景情報を明記することで、AIは「なぜ」そのルールが存在するのかを理解し、適切な判断ができるようになります。

Sub agentsが解決するコンテキスト枯渇問題

Claude Codeで複雑な実装をしていると、必ず直面するのがコンテキストウィンドウの枯渇です。

https://zenn.dev/tacoms/articles/552140c84aaefa

こちらの記事でも触れていますが、auto-compact後は、プロジェクトのルールや先ほどまでの作業内容の多くが失われ、生成品質がガクッと落ちます。

Sub agentsはこの問題を根本的に解決します。うれしいですね。
メインとなるClaude Codeから、Taskなどを用い、用途にあったSub agentsが選択され、実行されます。
（ちなみに、 PROACTIVELY や MUST BE USED といった記載を、サブエージェント定義ファイルのフロントマターに追記してあげると、選択されやすくなるらしいです。明示的に指定するのが煩わしい方はぜひ試してみてください）

メインのClaude Code
  ├── task-executor（実装担当）
  ├── quality-checker（品質チェック担当）
  └── technical-designer（設計担当）

各Sub agentが独立したコンテキストウィンドウを持つため、役割を分離することで枯渇を防げるということです。

また、メインとなるClaude Codeはコードを実装するための複雑な作業を精度高く行うために、多くの前提情報が与えられます。私も、Sub agentsが使えるようになるまでは、最初に分解したルールファイルを全部読み込んでもらっていました。
Sub agentsは責務が絞られるため、必要なコンテキストだけを与えることができます。これにより、不要な情報に惑わされず、コンテキストウィンドウにも相対的に余裕がある状態で作業ができます。

実際に使ってみよう！Agenticな開発のイメージ

1. 機能追加の要件整理

以下のようにAgentic Coding（AIエージェントが、人間の介入を最小限に抑えながら、計画、実行、検証、コミットといった開発プロセスを自律的に行う）を行います。
docs/sub-agents-guide.mdに、メインのClaude Codeが適切にオーケストレーターとして振る舞うためのガイドラインを定義しているので、コンテキストとして渡してあげる（読み込むよう指示をする）か、IDEを使っているならファイルを開いた状態で指示を出してもらえれば、期待した挙動をします。

> ルールを読んで、ルールを厳守してください。

⏺ ルールファイルを読み込みます。

⏺ Read(docs/rules/technical-spec.md)
  ⎿  Read 108 lines (ctrl+r to expand)

⏺ Read(docs/rules/typescript.md)
  ⎿  Read 164 lines (ctrl+r to expand)

⏺ Read(docs/rules/typescript-testing.md)
  ⎿  Read 319 lines (ctrl+r to expand)

⏺ Read(docs/rules/project-context.md)
  ⎿  Read 228 lines (ctrl+r to expand)

⏺ Read(docs/rules/ai-development-guide.md)
  ⎿  Read 165 lines (ctrl+r to expand)

⏺ Read(docs/rules/architecture-decision-process.md)
  ⎿  Read 221 lines (ctrl+r to expand)

⏺ Read(docs/sub-agents-guide.md)
  ⎿  Read 203 lines (ctrl+r to expand)

⏺ 6つのルールファイルとsub-agents-guide.mdを読み込みました。ルールを厳守し、サブエージェントシステムを活用してタスクを進めます。

  現在、sub-agents-guide.mdが開かれているため、オーケストレーターとして行動します。

> オーケストレーターとして適切に振る舞ってください。

  チャットボットの使い方を回答してくれるヘルプ機能を作りたいです。

⏺ 新機能の追加依頼ですね。オーケストレーターとして、まずrequirement-analyzerに要件分析を依頼します。

⏺ requirement-analyzer(ヘルプ機能の要件分析)
  ⎿  Done (13 tool uses · 43.7k tokens · 1m 35.4s)                  

⏺ 要件分析が完了しました。中規模（4-5ファイル）の機能追加と判定されました。

  🎯 私の理解

  ヘルプ機能は、非技術職の社員がAI Slack Botの使い方を簡単に確認できる機能です。ユーザーが「使い方」「ヘルプ」などと質問した時に、分かりやすく機能を説明します。

  ❓ 確認させてください

  requirement-analyzerから以下の質問事項が挙げられています：

  1. ヘルプ機能のスコープ

  どこまでカバーすべきでしょうか？
  - A) 基本的な使い方のみ（質問の仕方、基本コマンド）
  - B) 利用可能な全機能の詳細説明
  - C) トラブルシューティングも含む包括的なヘルプ

  2. 優先表示する情報

  最初に見せるべき情報は？
  - A) よく使う機能Top5の使い方
  - B) 基本的な質問の仕方とサンプル
  - C) 利用可能な機能の完全なリスト

  3. ヘルプの表示形式

  - A) 1つのメッセージ内にコンパクトにまとめる
  - B) カテゴリ別に複数メッセージで分割表示
  - C) 概要 + 詳細は外部ドキュメントへのリンク

  4. ヘルプのトリガー方法

  - A) 「ヘルプ」「使い方」などのキーワードで自動検知
  - B) 専用コマンド（例: /help）を作成
  - C) 両方に対応（キーワード検知 + コマンド）

  5. コンテンツ更新の運用

  - A) 機能追加時のみ開発者が更新
  - B) 管理者が編集できる仕組みを用意
  - C) ユーザーのよくある質問を自動収集して改善

  これらの方針を決めていただければ、次のステップ（Design Doc作成）に進めます。

> 1. B
  2. B
  3. A
  4. A
  5. A
  でお願いします

⏺ 方針が決まりましたね。確認します：

  - スコープ: 利用可能な全機能の詳細説明
  - 優先表示: 基本的な質問の仕方とサンプル
  - 表示形式: 1つのメッセージ内にコンパクトにまとめる
  - トリガー: 「ヘルプ」「使い方」などのキーワードで自動検知
  - 更新運用: 機能追加時のみ開発者が更新

  中規模の機能追加なので、Design
  Docを作成して実装方針を明確にします。

⏺ technical-designer(ヘルプ機能のDesign Doc作成)
  ⎿  Done (12 tool uses · 55.7k tokens · 2m 50.4s)                  

⏺ Design Docの作成が完了しました。次は作業計画書を作成して、具体的な
  実装手順を明確にします。

⏺ work-planner(ヘルプ機能の作業計画書作成)
  ⎿  Done (14 tool uses · 53.1k tokens · 2m 16.0s)                  

⏺ 作業計画書が作成されました。内容を要約します：

  📋 作業計画サマリー

  実装概要

  - showHelp functionをFunction Callingに追加
  - 既存のFunction定義から動的にヘルプコンテンツを生成
  - Slack mrkdwn形式で見やすく1メッセージにまとめて表示

  作業フェーズ（全4フェーズ）

  1. 基盤実装（2時間）
    - showHelp functionの定義
    - HelpContentGeneratorの実装
  2. サービス層実装（2時間）
    - HelpServiceの実装
    - Function executorの実装
  3. プレゼンテーション層実装（1.5時間）
    - SlackHelpFormatterの実装
    - 既存Function定義の説明追加
  4. 統合テストと最終確認（0.5時間）
    - 全体の動作確認
    - Slack表示の確認

  影響ファイル

  - 既存: 1ファイル（Function定義）
  - 新規: 4ファイル（各層の実装）
  - テスト: 4ファイル（すべて新規）

  タイムライン

  推定作業時間: 約6時間（1日以内で完了可能）

  実装を開始してよろしいでしょうか？承認いただければ、task-decomposerでタスクを分解し、実装を進めます。

2. タスクの分解

作業計画ができたら、task-decomposerが登場します。このサブエージェントは1コミット = 1タスクを意識して、タスクの分解を行います。

1コミット1タスクを意識しているのは、アトミックなコミットになることに加え、コンテキストウィンドウの制約範囲内でタスクを完結させること、認知負荷を下げ生成精度をあげることを期待しているためです。
ここら辺は人間と変わりませんね。

> おねがい

⏺ 承認いただきましたので、task-decomposerで作業計画書をタスクに分解します。

⏺ task-decomposer(ヘルプ機能のタスク分解)
  ⎿  Done (11 tool uses · 49.3k tokens · 4m 6.7s)                   

⏺ タスクの分解が完了しました。5つの独立したタスクに分解されました。

3. 実装時の品質保証フロー

実装時は、以下の原則が働きます。

テストファースト
task-executorは、Red-Green-Refactorプロセスを意識して作業を実施します。

段階的品質チェック
実装が完了したら、quality-checkerが6段階のチェックと、修正を実行します。

Phase 1: Biome（Lint/Format）
Phase 2: TypeScriptビルド
Phase 3: 循環依存チェック
Phase 4: 未使用エクスポート検出
Phase 5: テスト実行
Phase 6: 最終チェック

各フェーズでエラーを完全に解消してから次へ進むことで、後戻りを防ぎます。

⏺ Update Todos
  ⎿  ☐ showHelp function定義と基本型の追加                 
     ☐ HelpContentGeneratorクラスの実装
     ☐ HelpServiceとhelp executorの実装
     ☐ SlackHelpFormatterの実装とFunction descriptionの改善
     ☐ 統合テストと最終調整

⏺ それでは、最初のタスクから実装を開始します。

⏺ Update Todos
  ⎿  ☐ showHelp function定義と基本型の追加                 
     ☐ HelpContentGeneratorクラスの実装
     ☐ HelpServiceとhelp executorの実装
     ☐ SlackHelpFormatterの実装とFunction descriptionの改善
     ☐ 統合テストと最終調整

⏺ task-executor(タスク01: showHelp function定義)
  ⎿  Done (17 tool uses · 44.4k tokens · 2m 38.4s)                  

⏺ タスク01が完了しました。次にquality-fixerで品質チェックを実施します。

⏺ quality-fixer(タスク01の品質チェック)
  ⎿  Done (16 tool uses · 64.2k tokens · 4m 12.8s)                  

⏺ 品質チェックが完了し、すべてパスしました。タスク01を完了としてマークします。

⏺ Update Todos
  ⎿  ☒ showHelp function定義と基本型の追加                 
     ☐ HelpContentGeneratorクラスの実装
     ☐ HelpServiceとhelp executorの実装
     ☐ SlackHelpFormatterの実装とFunction descriptionの改善
     ☐ 統合テストと最終調整

⏺ タスク02を実行します。
...

品質チェックの今後の拡張構想

現在のquality-fixerは機械的なチェック（Lint、型、テスト等）に特化していますが、将来的には設計思想が遵守されているかのチェックも組み込むことを検討しています。

• アーキテクチャルなルールが守られているか（レイヤー間の依存関係等）
• プロジェクト固有の設計パターンが的確に反映されているか
• コードの意図と実装の整合性が取れているか

ただ、タスクが肥大化すると当然コンテキストウィンドウ枯渇問題に向き合わなくてはいけなくなります。別のサブエージェントとして切り出すことも含め、実際に動かしてみながら最適な実装を探っていく予定です。

より対話的な利用も可能

人間がAIと対話しながらタスクを進めていき、要所要所で発生する定型的な作業をSub agentsに任せるだけでも、コンテキストウィンドウを節約でき作業全体の安定性が向上します。
7/29から、@ の形式でSub agentsを呼び出せるようになり、より少ない手間で活用できます。

本ボイラープレートでは以下の定型テスクをSub agentsとして定義していますので、まずはこれらを日々の自身の開発タスクの中に一部取り入れてみるところから始めてみてもいいかもしれません。

• @quality-fixer : 品質チェックとエラー修正
• @task-executor : 個別タスクの実行
• @requirement-analyzer : 要件分析
• @work-planner : 作業計画書作成
• @technical-designer : 技術設計ドキュメント作成
• @document-reviewer : ドキュメントレビュー
• @task-decomposer : タスク分解
• @prd-creator : PRD作成

得られる効果と今後の展望

私は社内のチャットボット開発プロジェクトで、このボイラープレートにチャットボットプロジェクト固有のコンテキストを加えたものを使っています。

• 品質の安定化: 特にテスト結果の修正や複雑な実装の実行時に発生する、冗長な記載やルールの逸脱が少なくなった
• 開発速度の向上: auto-compactによる手戻りが激減
• コードの一貫性: 主導によるタスク

AIコーディングの未来

Sub agentsの登場で、AIとの協働開発がまた一歩前進したと私は考えています。
AIに指示を出して、結果を人間がチェックしていたものが、複数の専門AIが協調して、品質保証から自己改善まで自律的に実行できる未来が近づいてきたように感じます。

余談ですが、チャットボット開発プロジェクトで更新したルールやSub agentsの差分をボイラープレートに移植するサブエージェントを作ったので、Claude Codeがコード開発におけるベストプラクティスである限りは、定期的にルール群のアップデートをかけていこうと考えています。

まとめ

AIコーディングで重要なのは、AIの能力を最大限引き出すための環境整備です。ここら辺はマネジメントと考え方が似ていますね。

• 明示的なルールで暗黙知を形式知に
• Sub agentsでコンテキスト枯渇を防ぐ
• 適切な粒度でタスクを分解
• 段階的な品質チェックで手戻りを防ぐ

これらの仕組みを体系化したのが、このボイラープレートです。まだ挙動が安定しない部分もありますが、参考にはなる程度の仕上がりになっていると思います。
思った通りの結果にならずAIコーディングに及び腰な方にこそ、ぜひ一度このボイラープレートを使ってみてほしいです。AIコーディング、楽しいですよ。

詳細なセットアップ方法はREADMEを参照してください。