はじめに
以前「AIにコードを書いてもらうコツ：人間の様に接してみよう」という記事で、生成AIとの効果的な協働について考察しました。
記事で述べたかったこと
- AIが人間と共存するように進化するとしたら、人間のための環境やリソースを活用するために「人間のように振る舞う」ことが最も効率的である
- したがって、AIに開発を依頼する際も、人間の新人エンジニアに接するのと同じように、プロジェクトの背景、設計思想、判断基準を体系的に伝えるべき
- 開発者の暗黙知を明文化した、包括的な「プロジェクトオンボーディング文書」が必要
この考え方を具体的なiOSアプリ開発プロジェクトで実践してみました。人間の開発者が持つ判断基準や開発プロセスを文書化し、AIが文書を元に行動できる環境構築を目指しています。
本記事では、まだ試行錯誤中ですが、生成AIによる、iOSアプリ自動開発のアプローチの一端をご紹介します。
なお、生成AIの環境は、Claude Code を想定しています。
文書体系
文書体系の5つの分類
| 分類 | 説明 | 内容 |
|---|---|---|
| ルール | 開発の基本的な考え方とルール | エンジニアにとって重要な「開発の基本的な考え方とルール」を記述します。SOLID原則やClean Architectureなどの設計思想から、具体的なコーディング規約まで、開発者が持つ判断基準と実装ルールを明文化しています。なぜその技術を選択したのか、どのような場面でパフォーマンスより可読性を優先するのかといった思考プロセスも含まれています。 |
| ワークフロー | 開発手順とプロセス | 要件定義から実装まで、段階的に品質を確保しながら進める具体的な作業手順を定義しています。 |
| プロジェクト固有文書 | このプロジェクトの仕様と設計 | 要件定義、設計書、実装計画など、このプロジェクト固有の情報を格納しています。 |
| エージェント | 専門分野を担当するAIチーム | ドメイン層実装、UI実装、インフラ実装など、各分野に特化したAIエージェントを定義しています。 |
| コマンド | 作業を自動化する指示書 | 開発開始、レビュー実行、修正適用など、頻繁に行う作業を標準化しています。 |
ルール
概要
ルールは開発におけるAIに対する制約を明文化した判断基準集です。単純なコーディング規約にとどまらず、アーキテクチャや具体的な実装パターンまでを記載します。
基本文書
基本思想（例）
- 基本原則 - SOLID原則、DRY、KISS、YAGNIなどの普遍的な開発指針
- アーキテクチャルール - Clean Architectureの層構造と依存関係
実装規約（例）
- 全般コーディングルール - Actor、Observation、DI実装パターン
- UI層コーディングルール - SwiftUI特有の実装パターンとViewModel設計原則
- Domain層コーディングルール - ドメイン層のService、Entity実装の詳細ルール
- バッドプラクティス - 各層での「やってはいけない」実装とその理由
注目ポイント：特徴的なルール
開発文化の明文化（例）
- 「生成AIとの対話は日本語で実施」
- 「ソースコードのコメントは必ず日本語で記述」
- 「以前読んだとしても、必ず再読して内容を確認すること」
技術選択の強制（例）
- 「すべてのServiceはpublic actorとして実装」
- 「全てのViewModelは@MainActorを必須とする」
- 「ViewModelは対応するViewと同じディレクトリに配置する」
品質管理の徹底（例）
- 「init内でのTask使用禁止」（テストでのデータ競合防止）
- 「MockAssertionで本番環境での誤使用を防ぐ」
- 「Xcode プロジェクトファイル変更禁止」（XCConfigで設定管理）
これらの詳細で厳格なルールにより、AIは人間の開発者と同じ品質基準と技術選択で開発を進めることができます。
ワークフロー
概要
ワークフローは「どの順序で、どのように作業を進めるか」を定義した開発手順書です。要件定義から実装完了まで、品質を確保しながら段階的に進める具体的なプロセスを明文化しています。
基本ワークフロー
注目ポイント：開発の原則を明文化
実装の進め方
- 「依存関係の少ないものから開始」
- 「一度に1つの機能のみ実装」
- 「ビルドができる状態になり次第、ビルドして確認すること」
- 「Phaseの最後は、必ずビルドが通る状態にして終わること」
品質管理
- 「1ファイル作成毎に人間のレビューが必須」
- 「以前読んだとしても、必ず再読して内容を確認すること」
- Domain層では「Unit Testの作成と実行」が必須
これらの原則により、AIは段階的なアプローチで開発を進めることができます。
プロジェクト固有文書
概要
プロジェクト固有文書は「このプロジェクトで何を、どのように作るか」を記録したドキュメント群です。ルールとワークフローという基盤の上で、AIが実際にプロジェクトの仕様を理解し、設計・計画を立てるための情報源となります。
文書の構成
要件定義書
- 画面仕様、UIコンポーネント仕様、ビジネスロジック仕様など
- 要件ID（SCR-xxx、CMP-xxx、BL-xxx等）による体系的な管理
設計書
- モジュール構成、クラス図、シーケンス図などのアーキテクチャ設計
実装計画書
- 要件トレーサビリティマトリクスによる進捗管理
- フェーズ別の実装順序と依存関係
特徴：AIによる自動生成
これらの文書は、ルールとワークフローに従ってAIが自動生成します。人間は要件や方針を決定し、AIがそれを文書として整理・構造化する役割分担により、ドキュメントが効率的に作成されます。
エージェント
概要
エージェントは特定の専門分野を担当するAIチームです。重要なのは、エージェント自体に大量の情報を持たせるのではなく、必要最小限のコンテキストのみを与え、詳細なルールやワークフローは共通の文書から参照する設計になっていることです。
設計思想：コンテキスト最小化
各エージェントは「自分の専門分野」のみに集中し、必要に応じて共通のルール文書やワークフロー文書を参照します。これにより：
- コンテキストの重複を排除し、メンテナンス性を向上
- 一貫性を保証（同じルールを全エージェントが共有）
- エージェントがなくても開発可能（文書が整備されていれば手動でも実行可能）
専門エージェント一覧
実装系エージェント
- ドメイン層インプリメンター - Entity、Service、Repository Protocol等のDomain層実装
- UI層インプリメンター - SwiftUI View、ViewModel等のUI層実装（単一のView+ViewModelペアに特化）
- インフラ層インプリメンター - Repository実装、DataStore実装、DI層統合
支援系エージェント
- ツールライブラリアドバイザー - 既存のTools/Library/から再利用可能なコードを提案
- UIテーマアドバイザー - デザインシステム、テーマリソースの活用ガイダンス
上流工程エージェント
- 設計書クリエータ - 要件定義書から設計書を作成
- プロジェクトプランナー - 設計書から実装計画書を作成
- Figma仕様クリエータ - Figmaデザインから要件定義書を作成
保守系エージェント
- ライブラリクリエータ - 重複コードを検出してライブラリ化
フォールバック設計
エージェントは効率化のための仕組みであり、エージェントが利用できない環境でも、ルールとワークフロー文書があれば手動で同じ作業を実行できます。これにより、特定のAIツールに依存しない持続可能な開発環境を実現しています。
コマンド
概要
コマンドは頻繁に行う作業を標準化した「作業指示書」です。開発、レビュー、修正、管理など、日常的な開発作業をワンコマンドで実行できるよう自動化しています。
開発系コマンド
start-development
本開発を開始する基本のコマンドです。要件定義書の確認から始まり、設計書作成、実装計画策定、そしてPhase 1（Domain層）→ Phase 2（UI層）→ Phase 3（Infrastructure層）の段階的実装まで、開発の全フローを自動実行します。
start_generic_task
コンテキストがクリアされたAIに、プロジェクトの前提となる重要文書（ルール、ワークフロー、仕様書等）を読み込ませるコマンドです。長時間作業後にAIの記憶がリセットされても、このコマンドで「そこそこ前提が分かるAI」を素早く再生できます。
update-readme
テンプレートプロジェクトのREADME.mdを、実際のアプリ情報に更新するコマンドです。XCConfigファイルからアプリ名やバージョン情報を自動取得し、要件定義書から機能概要を抽出してREADMEを書き換えます。
create-library
各案件のプロジェクトで開発したコードの中から、他のプロジェクトでも再利用できそうなコードを検出し、テンプレートプロジェクトのTools/やLibrary/に抽出・格納するコマンドです。重複コードの削減とテンプレートの機能拡張を同時に実現します。
品質管理系コマンド
review
コードの問題点を抽出する汎用クリティカルレビューコマンドです。セキュリティ、設計品質、パフォーマンス等の観点から、優先度付きで改善点を指摘します。
参照：なぜ大規模言語モデルは 「批判」 を得意とし、どう活用すれば設計・実装品質を高められるのか
review-rules
iOS Clean Architectureに特化したプロジェクト固有レビューコマンドです。層間依存関係、Actor実装、SwiftUI慣用法など、このプロジェクトの技術選択に特化した品質チェックを実行します。
review-spec
実装が要件定義書通りになっているかをチェックするコマンドです。仕様と実装の乖離を検出し、未実装機能や仕様違反を指摘します。
fix-review / fix-review-rules
各レビューコマンドで検出された問題を、優先度に基づいて自動修正するコマンドです。ユーザーの確認を経て、段階的に問題を解決していきます。
Git管理系コマンド
create-pr
現在のブランチから、適切なベースブランチ（develop、main等）へのPull Requestを自動作成するコマンドです。コミット履歴から適切なタイトルと説明文を生成し、レビュアーの自動設定も行います。
make-reflection
作業中に発生した問題、学んだこと、改善点などを振り返って文書化するコマンドです。これらの振り返りから、ルールやワークフローの改善ネタを抽出し、プロジェクトの文書体系を継続的に向上させます。
最後に
ざっと項目を上げて見ました。
若干断定的な表現もあるのですが、まだ試行錯誤を行っている段階ではあります。
一部でも役立ちそうな項目があれば、幸いです。