はじめに
AIを使ってプログラム開発を行う際、要件がシンプルで規模の小さいソフトウェアを作る場合は、設計や実装方針を細かく指示しなくとも、要件さえうまく伝えることができれば満足いくソフトウェアを作ることができるでしょう。
一方、規模が大きな開発や、要件が複雑で長期にわたって運用されることが想定されるソフトウェアの場合、要件と合わせて設計や実装の方針も決めておくことが大事です。あらかじめ設計や実装の方針を決めておくことで、コードが崩れにくくなり、長期的なメンテナンスがしやすくなります。
ソフトウェア開発の世界では、名前がつけられた設計思想や実装方針が多くあるので、それらの用語をうまく組み合わせてAIに伝えておくことで、ソフトウェアを理想的な状態に保ちやすくなります。AIを使ったソフトウェア開発でコードや構造を理想の状態に保つには、エンジニアが体系化された設計・実装方針に関する知識をどれだけ持っているかが鍵になると思っています。
私が現場で取り入れている設計指針
私は今現在、ASP.NET Core(C#)を用いたWebアプリ開発の案件に関わっています。
その中で、現在採用している設計指針の一部を紹介します。
- フロントエンドのスタイリングはEvery Layout + ITCSS
- バックエンドはクリーンアーキテクチャ + DDD + CQRSパターン
- 単体テストは古典学派
実際には他にもありますし、それぞれもう少し詳細にドキュメント化してまとめています。
これらの方針はプロンプトで毎回入力するのではなく、ドキュメント化されたファイルを設定ファイルから参照する形にして、AIが作業する際にはその方針を守りやすくなるようにしています。
プロジェクトが始まった時点である程度は設計の方針を固めておき、あとは開発を進めながら細かな方針を調整し、都度ドキュメントを更新します。このような設計方針や実装方針をAIと共有しておくことで、プログラムの構造やコードの書き方を理想の状態に保ちやすく、機能追加やリファクタリングがしやすくなったと感じています。
このように設計方針や実装方針をAIと共有する場合、「Every Layout」「ITCSS」「クリーンアーキテクチャ」「DDD」「CQRSパターン」「古典学派」などの用語をあらかじめ認知している必要があります。さらにそれらの用語がどのような概念を指しているのかを理解しておく必要があります。
簡単な解説
上記の用語について、簡単に解説しておきます。
Every Layoutは、別の記事でも紹介していますが、CSSスタイリングに関する設計思想です。公式サイトや同名の書籍があり、その中で詳細な解説があります。私はこの書籍を読んで、Every Layoutの設計思想がとても良いと思うようになり、以後Webアプリケーションを開発する際にはできるだけこの設計思想を取り入れるようにしています。
ITCSSもCSSの設計思想の1つですが、上記のEvery Layoutとは基本的に競合せず、むしろ相性が良いです。この2つの思想を取り入れることで、HTMLとCSSの両方のコードを整理された形に保ちやすくなると考え、フロントエンドを実装する際に好んで採用しています。興味がある方は是非調べてみてください。
クリーンアーキテクチャは、Robert C. Martinによって提唱されたアーキテクチャで、同名の書籍でも詳しく解説されています。特に重要なのが、依存関係を内側のビジネスルールへ向けるという原則です。これにより、ビジネスロジックがデータベースやUIなどの技術的な詳細に依存しにくくなり、変更に強いソフトウェアを目指します。比較的抽象度の高い概念であり、具体的なフォルダ構成やコードの書き方については触れられていないことも多いです。そのため、実際のプロジェクトではフォルダ構成やパッケージ構成は自分たちで事前に決めておき、その上で、AIにはクリーンアーキテクチャの原則に沿うように指示しています。
DDDはドメイン駆動設計（Domain-Driven Design）のことで、原点となっている有名な書籍があります。ドメイン（業務領域）を中心に設計を進めていく設計思想ですが、コーディングにおいてはクリーンアーキテクチャと相性が良く、2つを組み合わせることで、テストがしやすく保守しやすいコードを作りやすくなります。
CQRSパターンは、システムの状態を変更するCommandと、状態を参照するQueryの責務を分離する設計パターンです。RDBを利用するアプリケーションの場合、データの登録・更新・削除などを行う処理と、データの参照を行う処理について、クラスやモデルなどを分離する形で実装できます。特に、書き込みと読み取りで必要なデータ構造が異なる場合などに有効で、それぞれの処理を独立して最適化しやすくなります。
古典学派は、単体テストにおける流派の1つです。他にはロンドン学派と呼ばれる流派があります。私は単体テストの考え方/使い方という書籍でそれぞれの流派の存在を知りました。この書籍はどちらかというと古典学派推しですが、私も書籍を読む中で古典学派のスタイルの方が良いなと思っていたので、AIに単体テストを作成させる場合は、この方針を伝えるようにしています。それぞれの学派の違いについて気になる方は書籍や他のサイトなどで調べていただければと思います。
コミュニケーションをショートカットするための知識
「Every Layout」「ITCSS」「クリーンアーキテクチャ」「CQRSパターン」などの用語を知っておくメリットは、コミュニケーションや説明をショートカットできることです。
「Every Layout」や「ITCSS」などの設計指針を知らなかったとしても、自分なりにCSSの理想の設計を考えることはできます。しかし、自分で一から構築した設計指針をチームメンバーやAIに説明するのは手間も時間もかかります。チームメンバーに説明する際には、メリットを理解してもらう必要性も出てきます。
一方、「Every Layout」や「ITCSS」のように名前がつけられている設計指針であれば、その用語だけで設計指針を共有することができます（もちろん、設計指針の名前を伝えるだけで、必ずしも理想通りの実装になるわけではありませんが）。
チームメンバー間においても、その用語を知っている相手であれば、その用語だけで設計指針や実装方針に関する意思疎通ができるようになるので、設計や実装について議論する時間が大幅にショートカットできます。
多くの開発者がAIを使って開発をするようになり、人間がコードを書く機会は大幅に減りました（全く書かなくなった、という人も少なくないでしょう）。しかし、要件が複雑で規模の大きなソフトウェアの秩序を保つには、エンジニアが設計方針をAIに伝えておくことは大事です。その際、理想とする設計を効率よく伝えるには、「Every Layout」や「ITCSS」のような、体系化された設計指針を表す用語をどれだけ知っているかが鍵になりそうです。
では、Webアプリ開発でAIとのコミュニケーションに役立つ、体系化された設計指針には、他にどのようなものがあるのでしょうか。
私がまだ知らないだけで、「この思想をAIに伝えておくだけでメンテナンス性やプロダクトの価値を高めることができる」ような概念も多くあると思いますし、用語は知っているけれどうまく活用できていない設計指針や実装方針もあるかもしれないと思うようになりました。
そこで、AIと一緒に開発する際、役立ちそうな設計指針を調べ、その中で私が個人的に今後役に立ちそうだと思った内容を、カテゴリごとに整理してまとめました。
HTML
WCAG / WAI-ARIA APG
WCAGとWAI-ARIA APGはどちらもWebアクセシビリティに関するガイドです。WCAGはWebコンテンツのアクセシビリティに関する国際的なガイドラインで、WAI-ARIA APGはARIAを用いたUIパターンについて、キーボード操作やロール、状態などの実装方法を示す実践的なガイドです。
私が現在関わっている案件は、社内システムでユーザーがかなり限定的ということもあり、アクセシビリティの優先度はそれほど高くはありませんでした。しかし、ユーザーを限定しない、一般に公開するサービスやWebサイトでは、アクセシビリティを考慮する必要があります。アクセシビリティが必要なWebサイトやWebアプリを作る際は、HTMLを実装する際のルールとしてWCAGやWAI-ARIA APGに沿うように指示したり、実装後のレビュー時の観点としてこれらのガイドを活用すると良さそうです。
CSS
BEM / CUBE CSS
BEM（Block Element Modifier）は、CSSクラス名の命名規則を体系化する方法論です。存在は知っていましたが、BEMを意識したCSS設計はしていませんでした。AIがHTML・CSSをコーディングする際に、クラス属性の命名に揺れがあると感じる場合は、BEMに従うようにAIに伝えておくことで、クラス属性の命名の揺れを減らすことができそうです。
CUBE CSSは、今回調査して初めてその存在を知りました。Every Layoutとの親和性が高いCSS設計思想でもあるようです。ここは深掘りして取り入れられるようにしたいと思います。
Design Tokens / Design Systems
デザイントークン、デザインシステムについての概念は知っていましたが、AIを使って開発をする際に意識したことはありませんでした。確かに、AIでCSSを実装すると、余白や色を画面ごとに実装してしまうことがあり、その点は課題に感じることがありました。共通で使用できる値は変数化して再利用するように指示することである程度解消されましたが、「デザイントークン」や「デザインシステム」という用語をうまく活用できれば、よりすっきりとした説明でより安定したCSSを出力できるようになりそうです。
フロントエンド
Feature-Sliced Design（FSD）
Feature-Sliced Design（FSD）は、フロントエンドのコードを、機能や責務を中心に整理するためのアーキテクチャです。FSDは私自身開発での経験はありませんが、案件で取り入れていたメンバーが紹介している記事があるので、興味がある方は参照してみてください。
Atomic Design
Atomic Designは、UIをAtoms、Molecules、Organisms、Templates、Pagesという階層で整理する設計手法です。こちらについても私自身は開発で取り入れた経験はありませんが、フロントエンドに詳しいエンジニアと話している際に概要を教えてもらったことがあります。
私が現在開発しているWebアプリはSPAではないこともあり、フロントエンドのディレクトリ構造について明確なルールを設けていませんでしたが、やはり機能の数が増えてくるとファイル数が増えてくるため、ディレクトリ構造を整理したくなってきます。FSDやAtomic Designから参考になる要素は取り入れていきたいと思いました。
Testing Library Guiding Principles
Testing Library Guiding Principlesはフロントエンドのコンポーネントテストに関する設計思想だそうです。
先にも書いた通り、現在開発に関わっているWebアプリはSPAではないため、フロントエンドのコンポーネントテストを実装する機会はあまりなく、そもそもフロントエンドに閉じたテストを実装する発想がありませんでした。とはいえ、入力項目が多い複雑なUIを作ることもあるので、必要に応じてフロントエンドのテストも検討していきたいと思いました。
Testing Library Guiding Principlesは単体テストの古典学派と共通する考え方（内部構造に過度に依存せず、振る舞いを検証する考え方）もあるようで、複雑なUIを持つ画面のテストでも取り入れていきたい考え方です。
API
現在開発しているWebアプリはSPAではないこともあり、バックエンドはAPI化していません（外部のツールと連携するために一部の機能をAPIにはしていますが、ごく少数です）。そのため、APIの設計・実装方針はドキュメント化していませんでしたが、バックエンドをAPIとして作成する場合は、エンドポイント（URL）の命名やリクエストとレスポンスの構造など、プロジェクト全体で統一しておきたいものが多く出てきそうです。
APIについては「REST」という設計思想が広く知られていますが、RESTは解釈の幅が広く、案件によっても、人によっても考え方がバラバラな印象があります。そのため、AIに対しても「REST APIの方針に従って実装してください」と伝えたとしても、意図しない実装になってしまう可能性は高そうです。
JSON:API
JSONベースのAPIであれば、JSON:API Specificationのサイトにてリソースの表現、関連、エラー、ページネーションなどの形式を統一する仕様がまとめられています。
リクエストとレスポンスがJSON形式のAPIをAIで実装する場合は、APIの実装に統一感を出すための方針としてJSON:APIは参考になりそうです。
E2Eテスト
Playwright Best Practices
Playwright Best Practicesは、PlaywrightでE2Eテストを作る場合の、公式が提供する設計・実装のベストプラクティスだそうです。「CSSクラスなどの内部実装への依存を減らす」「自動待機や再試行可能なアサーションを活用する」などの方針があるそうです。
現在関わっている案件では、Gauge + Playwrightを用いてE2Eテストを作成しています。
（Gaugeについては別の記事でまとめているので、興味があれば参照ください）
E2Eテスト全体の方針（例えば、シナリオの作成パターンやテストデータのセットアップ方法など）はドキュメント化していたのですが、Playwrightの実装方針については特に意識していませんでした。
Playwrightに関する実装ではPlaywright Best Practicesを守るように明記しておくことで、E2Eの実装をより洗練されたものに保つことができそうです。これはPlaywrightを導入している案件では是非取り入れたい実装ガイドです。
セキュリティ
OWASP
OWASPは、ソフトウェアのセキュリティ向上を目的としているコミュニティです。
OWASPによって提供されているWebアプリケーションの規格としてOWASP ASVS(OWASP Application Security Verification Standard)があります。これは、Webアプリケーションのセキュリティ要件や、検証項目を網羅的に体系化した標準規格（チェックリスト集）です。AIにコードレビューをしてもらう際に、OWASP ASVSを基準にしたセキュリティ観点のレビューをしてもらうことで、レビューの精度を上げることが期待できます。
また、OWASP Top 10（リンクは2025年版）と呼ばれる、Webアプリケーションにおける特に重要なセキュリティリスクをまとめた文書も公開されています。OWASP Top 10は定期的に更新されており、代表的なセキュリティリスクを把握するための資料として活用できます。
IPA 安全なウェブサイトの作り方
Webアプリ開発のセキュリティにおけるガイドとして有名なのは、IPAが作成している安全なウェブサイトの作り方です。この内容を実装時のルールとして定めておくと良さそうです。
また、この「安全なウェブサイトの作り方」を配布しているページでは「セキュリティ実装 チェックリスト」というファイルもダウンロードできます。コードレビューをしてもらう際、このチェックリストの内容に沿ってレビューしてもらうのも良さそうです。
余談ですが、最近Webアプリケーションに対して脆弱性診断を行うセキュリティベンダ企業についての話を聞きました。私が聞いた話では、そのセキュリティベンダの脆弱性診断は、OWASP Top 10とIPAの資料をベースとした診断を行っているとのことでした。そういう意味でも、OWASPとIPAの2つをセキュリティの軸とした実装方針やレビュー観点は、セキュリティに対する効果が高そうです。
インフラ・クラウド
The Twelve-Factor App
The Twelve-Factor Appは、クラウド上で動くWebアプリケーションに対する設計指針だそうです。この設計指針の存在は今回調査するまで知りませんでした。
私は現在インフラ構築には直接関与していませんが、アプリケーションの設定や認証情報の扱い、ログの出力やビルド・デプロイの方法など、アプリ開発者とインフラ構築者が連携して共通認識を持たなければいけない部分は多々あります。The Twelve-Factor Appは、そのような、アプリケーションとインフラの境界にある設計指針として、特におすすめとのことです。
AIでの実装やレビューでも使用できそうですし、アプリ開発者とインフラ構築者が、設定管理やデプロイ、ログの扱いなどについて共通認識を持つための設計指針としても有効そうです。
開発プロセス
Trunk-Based Development
これは主にGitのブランチ運用に関する開発手法で、長期間存続するブランチを極力減らし、mainブランチなどのメインラインに小さな変更を頻繁に統合していく手法です。以前関わっていた案件で、この開発手法を採用していたことがあります。
私はGitの操作は（面倒な作業が発生しない限りは）自分で行うことが多いため、Gitの運用を含めた開発手法についてAIに伝えたことはありませんでした。ですが、とある開発でAIにいろいろな作業を丸投げしていた時に、意図せずにブランチが増やされていたことがあります。開発プロセスとしてTrunk-Based Developmentを採用することを明記しておけば、Git操作をAIに任せても意図せずブランチが増える事態も防げそうです。
Architecture Decision Records（ADR）
ADRは設計上の重要な意思決定を、簡潔な文書として記録する方法です。ADRの存在は知っていましたが、取り入れた経験はありません。
AIに多くの作業を任せるようになってからというもの、開発のスピードは格段に速くなりました。その分、人間が意思決定する頻度も多くなり、なぜその判断をしたのか、後々になっても思い出せない、というケースも増えてきました。ADRを採用して意思決定の記録を残しておけば、後々になってその記録が役に立ったり、AIが過去の意思決定と矛盾した判断をするリスクも減らせそうです。
ADRは設計思想や実装方針とは方向性が異なるものですが、本格的にAI駆動開発をするにあたっては是非とも採用したいところです。
デザインパターンの活用
ソフトウェア開発には、特定の問題に対する再利用可能な設計上の解決策をまとめた「デザインパターン」があります。代表的なものとしてGoFのデザインパターンがありますが、ほかにもアーキテクチャパターンやクラウドデザインパターンなど、さまざまな領域で設計パターンが体系化されています。
先に紹介した「CQRSパターン」もデザインパターンの1つですし、現在関わっている案件では他にもトランザクション制御で「Unit of Workパターン」という実装のパターンを採用しています。デザインパターンなどの設計パターンを多く知っていれば、AIに実装を依頼する際に「○○パターンで実装して！」と伝えるだけで、設計の方針をある程度固めることができます。
さまざまな設計パターンを知っておくだけでも、設計の質を上げるのに役立つかもしれません。
またデザインパターンはコーディングに関するものだけではなく、ネットワークやクラウドなどの分野にもあります。現在インフラ構築には関わっていないため、クラウドのデザインパターンについては詳しくないのですが、インフラ構築に関わる際にはこれらのデザインパターンを事前に知っておくと役に立ちそうです。
アンチパターンの活用
デザインパターンは、特定の状況下においてうまく機能するパターンですが、逆に「これはやめた方がいい」という設計や実装のパターンはアンチパターンと呼ばれます。
小さな機能実装であれば、AIが積極的にアンチパターンを選択して実装することは少ないかもしれませんが、エンジニアがアンチパターンとは知らずに良くない設計を指示してしまう可能性もありますし、修正や機能追加が増えてくると、コード全体で見た時に知らず知らずのうちにアンチパターンが増えてしまうこともあるかと思います。
そのため、レビュー時に、アンチパターンに該当するような箇所がないかという観点は大事です。
SQLアンチパターン
ソフトウェア設計はどの案件にも確実に使える明確な正解というものはありませんが、中でもDB設計は正解を見つけるのが難しい分野であるように思います。DB設計にもさまざまな設計手法はありますが、一般的な業務システムのRDB設計に幅広く適用できる、名前のついた設計思想はパッと思いつきません。
どの案件でも明確にやっておいた方が良い方法論としては「正規化」が挙げられますが、それ以外の設計方針としては「要件による」となってしまうケースが多いように思います。それでいて、DBはアプリケーションを一度リリースしてしまうと後から設計変更が難しいため、最初に理想的な設計を考えておかないと、後から後悔してしまうことになります。
DB設計に関してはSQLアンチパターンという有名な書籍があります（厳密にはDB設計だけでなく、RDBに関するプログラミング全般が含まれますが）。DB設計がベストなのかどうかの判断は難しいかもしれませんが、SQLアンチパターンの中のアンチパターンに該当する箇所がないかをレビューしてもらうことで、悪いDB設計になってしまうリスクは下げられそうです。
良い設計方針を知るのと同じくらい、悪い設計方針を知ることも大事です。
まとめ
今回、AIを活用した開発で役に立ちそうな設計指針を調べる中で、初めて知ったものも多くありました。また、以前から存在は知っていたものの、AIとの開発にうまく取り入れられていない知識が多々あることにも気づけました。
AIによってソフトウェア開発のハードルは下がり、エンジニア不要論が囁かれることもあります。確かに、AIによって人間がコードを書く機会は大きく減りました。しかし、たとえ開発のほとんどをAIに任せたとしても、最終的に責任を取るのは人間です。
AIの成果物に対して人間が責任を取れる状態を保つためには、人間とAIが密にコミュニケーションを取る必要があるでしょう。そして、精度の高いコミュニケーションを取るには、人間側が設計に関して多くの知識を持っていることが必要になると思っています。
人間は、1から10まで全てを説明しなくても、空気を読んで状況を察し、よしなに動いてくれたりもします。一方でAIは空気を読んでよしなに動いてくれることはあまりありません。人間と違って丁寧な説明をしなければいけない場面もあります。しかし、デザインパターンや、設計思想など、体系的なノウハウが凝縮されている用語をうまく活用することができれば、むしろ人間を相手にするよりも短い文章で質の高いコミュニケーションが実現できるかもしれません。
また、設計に関する知識を豊富に持っていれば、AIが作成した成果物に対する評価の精度も上がります。
AIがコードを書くようになった今、エンジニアの学ぶべきことがなくなったと感じる人もいるかもしれません。しかし私はむしろ、AIがコードを書くようになったからこそ、エンジニアは設計についてより多くを学ぶ必要があると感じています。AIに適切な指示を出すためにも、AIが作成した成果物を適切に評価するためにも、設計に関する知識が欠かせないからです。
