サイオステクノロジー（Tech.Lab）の技術ブログ

全739件

2025/10/15

はじめにども！今月はがっつりと開発期間をいただいて、社内で活用できるサービスを作成しつつ、AIとの開発検証を進めている龍ちゃんです。作るものが多くてあっちにフラフラこっちにフラフラって感じです。今回は、「 Claude Code革命！3フェーズ開発で効率的な開発：計画→実装→検証術」で提唱した「計画ドキュメント」を用いての開発を3カ月ほど続けたので、そこに対する知見を書いていこうと思います。結論は「計画ドキュメント」ってめちゃくちゃ大事じゃね？ってお話です。問題：AIに丸投げすると何が起きるか技術選定を任せる危険性開発を進めていく中で、最も課題となったのが「AIに技術選定を委ねてしまう」という問題でした。具体的な例として、私はSWRで全ての処理を自動生成しようと試みていました。SWRは本来データフェッチングに特化したライブラリですが、CRUD操作の全てをSWRで解決しようとしていたのです。これは設計思想から考えると適切ではありませんでした。 CRUDの4つの要素のうち、SWRが最適化されているのは主にRead（データ取得）の部分です。Create、Update、Deleteの3/4については本来の用途から外れているにも関わらず、統一性を重視して全てSWRで実装しようとしていました。人間の開発者であれば「SWRの実装が複雑になるようであれば、素直にAxiosを使用した方が良い」という判断ができます。しかし、AIにはこうした経験に基づく技術的判断や、ライブラリの適切な使い分けに関する感覚が不足しているようです。龍ちゃんシステムプロンプトで「SWRを絶対使うように」って書いていたので、技術選定をしたのは人間なのですがそれに対する課題などの指摘は特にないってのが問題ですね。 AIの限界：誤字脱字と文脈の理解プロンプトを通じたやり取りで発生する問題も重要な課題でした。入力に誤字脱字が含まれている場合、AIはそれを修正することなく処理を継続してしまいます。技術用語の誤入力などがあっても、人間であれば文脈から推測して修正できるような内容でも、AIは字面通りに解釈して間違った方向に進んでしまうことがあります。この結果、想定していたアーキテクチャから逸脱した実装が生成されたり、設計方針に一貫性がなくなったりする問題が発生しました。具体例として、README.mdに「SWRを必ず使用すること」という記述があったのですが、これが問題の原因となりました。Orvalの設定を適切に調整すれば回避できた問題でしたが、全てのエンドポイントに対してAxiosとSWRの両方のクライアントが生成される状況で、AIは一貫してSWRを選択し続けていました。根本原因：意思決定の不在これらの問題の本質は、人間が行うべき意思決定をAIに委ねてしまっている点にあります。人間の開発者は、明文化されていない暗黙知に基づいて技術的判断を行うことがあります。「この技術領域では一般的にこのようなアプローチを取る」といった、体系化されていない経験則や業界標準に関する知識です。こうした暗黙知は、各開発者の経験や学習によって蓄積されたものですが、現在のAIには十分に備わっていないと感じています。もちろん、私の技術力が不足しているため、AIの能力を十分に引き出せていない可能性もありますが、この差を埋める仕組みが必要です。その仕組みこそが、計画ドキュメントによる意思決定の明文化なのです。解決策：計画ドキュメント = 意思決定の場人間同士の協働 vs AI協働の違い人間同士での開発とAI協働での開発では、「暗黙知の共有レベル」に大きな差があります。人間同士での協働の場合：共通の技術的背景知識を前提とした議論が可能「一般的にはこのようなアプローチを取る」という共通認識文脈を理解した柔軟な修正と提案暗黙の了解による効率的なコミュニケーション AI協働の場合：明示的に指示された内容のみに基づく判断技術的なベストプラクティスの理解が限定的プロンプトの内容に対する忠実な実行全ての判断基準の明文化が必要つまり、AI協働においては全ての意思決定プロセスを文書化することが不可欠となります。計画ドキュメントで決めること計画ドキュメントで明文化すべき要素は、主に以下の4つです：技術選定：選定理由とともに、採用しない選択肢（禁則事項）についても記載ライブラリ間の使い分け基準の明確化例：SWRはデータフェッチ（Read）操作のみに使用し、CUD操作にはAxiosを使用するアーキテクチャ方針：フロントエンド・バックエンド間の責任境界エラーハンドリングの統一方針状態管理の方法と各層の責務 API設計：エンドポイントの命名規則と構造レスポンス形式の統一ルールエラーレスポンスの標準フォーマット実装方針：ディレクトリ構成とファイル配置のルールコンポーネント設計のガイドラインテスト方針とカバレッジ基準意思決定と実行の分離効果的なAI協働を実現するには、意思決定フェーズと実行フェーズを明確に分離することが重要です。人間の役割：何を作るか、どのような方針で開発するかを決定する AIの役割：決定された方針に従って、実際のコードを生成・組み立てるこの役割分担により、AIの長所である「高速で大量のコード生成」を活かしながら、人間の「経験に基づく技術判断」を適切に反映できるようになります。計画の品質が成果物の品質を決定するのは開発の基本原則ですが、特にAI協働においては「計画ドキュメントがプロジェクトの成否を左右する」と言えるでしょう。実行の標準化：パーツと自動生成品質保証としてのパーツ化実際の開発では、意思決定した内容を「パーツ」として標準化することで品質を保証できます。これはソフトウェア工学における品質管理の考え方と共通しています。システム開発において、個々のコンポーネントの品質がシステム全体に与える影響は重大です。一つのコンポーネントに不具合があると、それがシステム全体の信頼性を損なう可能性があります。プログラムにおいては多少の技術的負債を抱えても稼働し続けることは可能ですが、基盤となるパーツがすべて品質に問題を抱えている場合は、深刻な影響が生じます。特にフロントエンドを開発する際は、外部のAPIや自作のAPIをパーツとしてとらえることで、作業領域が明確化されます。人間の役割：作成すべき機能と要件を明確に定義する使用するパーツの選択と品質基準の設定パーツの妥当性と整合性を検証するパーツ/自動生成の役割：実装方法を標準化し、一貫性を保つコードの品質を一定レベルに維持する再利用性を高め、開発効率を向上させる AIの役割：定義されたパーツを適切に組み合わせて実装するボイラープレートコードの大量生成を効率化人間が決定した設計方針に従ってコードを構築する実例：自動生成パイプライン具体例として、OpenAPIスペックから型定義を自動同期するパイプラインを構築した際の事例をご紹介します。 // DTO定義（人間による意思決定） interface UserCreateRequest { name: string; email: string; role: 'admin' | 'user'; } // 型定義とAPI関数は自動生成 const createUser = async (data: UserCreateRequest) => { return axios.post<UserResponse>('/api/users', data); }; この実装において重要なポイントは、 DTO定義という設計判断は人間が行い、実行部分（型定義生成、API関数生成）は自動化している点です。これにより、設計の一貫性を保ちながら実装効率を大幅に向上させることができました。参考事例：Shadcn/uiのアプローチ Shadcn/uiは、UIコンポーネント開発において「パーツ化」の優れた事例を提供しています。このライブラリが革新的な点は、UIコンポーネントを標準化された「パーツ」として提供し、開発者が「どのコンポーネントを使用するか」という意思決定に集中できる環境を作り出していることです。AIは「パーツを選択して適切に組み合わせる」という作業に集中でき、結果として開発効率と品質の両立を実現しています。この考え方は、API接続層やビジネスロジック層にも応用可能であり、AI協働開発における有効なパターンとなり得ると考えています。実践：意思決定を握る3原則原則1：計画ドキュメントでの明文化実施内容：技術選定の理由を具体的かつ詳細に文書化実装方針を明確で実行可能なレベルまで記述暗黙知となっている判断基準の言語化明文化の範囲について：理論的にはどこまで詳細化しても構いませんが、コンテキスト量の制約があることを考慮する必要があります。特にClaude等のLLMを使用する場合、トークン制限により詳細すぎる文書は処理できなくなる可能性があります。このバランス調整は現在の技術的制約として受け入れる必要があります。実践的な運用方法：バックエンドとフロントエンドを並行開発する場合、計画ドキュメントに加えて具体的な実装手順をToDo形式で管理することを推奨します。進捗を可視化することで、AIツールが予期せず停止した場合でも、明確な再開ポイントを確保できます。原則2：パーツによる実行の標準化実施内容：再利用可能なコンポーネント・関数の設計と整備 API接続の標準化（型定義、エラーハンドリング含む）開発ツール（Linter、Formatter等）の統一と自動化品質保証の重要性：個々のパーツの品質は、システム全体の安定性に直結します。不適切な設計のパーツを多数組み合わせると、保守性や拡張性に深刻な問題が生じる可能性があります。そのため、パーツ設計段階での品質基準の設定と検証が不可欠です。原則3：検証による継続的改善実施内容：計画と実装結果の差分分析と記録発見された問題点や改善点の体系的な蓄積得られた知見の次回プロジェクトへの適用現実的な視点の重要性：完璧な計画ドキュメントや仕様書を最初から作成することは現実的ではありません。開発過程で「より良いアプローチが明確になる」ことは自然な現象です。そのような状況では、変更の必要性を適切に判断し、修正された方針で実装を完了させることが重要です。完了後には計画と実装の差分を分析し、その経験を将来のプロジェクトに活かすことで、継続的な改善を図ることができます。まとめ：意思決定は人間、実行はAI 本記事では、3ヶ月間のAI協働開発を通じて得られた実践的な知見をもとに、効果的な協働体制の構築について詳しく解説してきました。重要ポイントの整理：技術選定の主導権確保 – AIに技術的判断を委ねることのリスクと、経験に基づく適切な技術選択の重要性計画ドキュメントによる意思決定の明文化 – 暗黙知の言語化と、全ての判断基準の明確化の必要性意思決定と実行の明確な分離 – 人間とAIの適切な役割分担による効率化の実現パーツ化による実行の標準化 – 品質保証と再利用性向上のための設計アプローチ継続的改善による知見の蓄積 – 完璧性よりも学習と改善を重視したアプローチ結論として、現在のAI協働開発においては、人間が意思決定を行い、AIが実行を担当するという役割分担が最も効果的であると考えられます。 AI技術は急速に進歩していますが、現時点では経験に基づく技術的判断や、コンテキストを考慮した柔軟な意思決定において、人間の能力に及ばない側面があります。一方で、大量のコード生成や、定められたパターンに従った実装作業においては、AIの方が高速かつ正確に処理できます。この技術特性を理解し、適切な役割分担を実装することで、AI協働開発の真価を発揮することが可能になります。実践への提案 AI協働開発を検討されている方は、まず「計画ドキュメント」の作成から始めることをお勧めします。初期段階では作成コストが高く感じられるかもしれませんが、中長期的には開発効率と成果物の品質において大幅な改善効果が期待できます。この記事で紹介した3原則と実践的アプローチが、皆さんのAI協働開発プロジェクトの成功に寄与できれば幸いです。ご覧いただきありがとうございます！この投稿はお役に立ちましたか？役に立った役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post AI協働開発の落とし穴回避！3ヶ月で実証した計画ドキュメントの価値 first appeared on SIOS Tech. Lab .

人工知能, フロントエンド, テスト, API, アーキテクチャ, 品質管理, 設計, 大規模言語モデル（LLM）

サイオステクノロジー（Tech.Lab） の技術ブログ

コンテンツ

サイオステクノロジー（Tech.Lab）の技術ブログ