「ヒトが思い出しやすい」アーキテクチャの極意
こんにちは！Accel-Hack（アクセルハック） 開発チームです。
私たちは社内アシスタント「Airi」の開発において、AIエージェント（Antigravity等）とペアプログラミングを進めています。
簡単な日本語でプロンプトを投げるだけで、AIが瞬時に何百行ものコードを書き上げてくれる体験は、まさに魔法のようです。
しかし、AI駆動の開発が進むにつれて、私たちは「ある全く新しい課題」に直面しました。
それは、AIにとっては簡単なことでも、ヒト側の認知負荷が限界を突破してしまうという問題です。
本記事では、AIが大量のコードを生成する時代だからこそ重要になる「ヒトが思い出しやすいアーキテクチャ設計」についてご紹介します！
1. 導入：コードの「産みの苦しみ」が消えた時代の新たな罠
かつて、エンジニアにとってコードを書くこと（産み出すこと）は、多大な時間と労力を要する「苦しみ」を伴う作業でした。
しかしAIの登場により、その苦しみは過去のものになりつつあります。
今や、自然言語で指示を出すだけで大量のコードが生成される時代です。
しかし、ここに大きな罠が潜んでいました。
それは、「書くのは一瞬でも、後で読んで理解し、メンテナンスするのはヒトの仕事」だということです。
将来すべてをAIに任せられる時代が来るかもしれませんが、現状では「AIはまだ完全に信用できない」のが実情です。
もしAIが権限周りの実装でミスを犯せば、システムにとって致命的な問題になりかねません。
そのため、AIが生成した大量のコードであっても、結局はヒトが自分で見て安心できるまでダブルチェックする必要があります。
AIが生み出した膨大なコードベースに対して、従来の「レイヤードアーキテクチャ（MVCなど）」を適用しているとどうなるでしょうか。
例えば「勤怠（attendance）機能」のバグを直そうとしたとき、ヒトは `controllers/` の中から `attendance.ts` を探し出し、次に `models/` を探し、さらに `views/` を探して…と、あちこちに散らばったファイルを自力でかき集めて脳内で結合しなければなりません。
ヒトはAIのように巨大なコンテキストウィンドウ（メモリ）を持っていません。
昔と違って「自分が苦労して書いたコード」ではないため、「あれ、このコードどこに書いたっけ？ どういう繋がりだっけ？」と思い出すための負荷が、とてつもなく跳ね上がってしまったのです。
2. 解決策：ヒトが直感的に思い出せる「機能駆動（Feature-First）アーキテクチャ」
この「ヒトの認知負荷の爆発」を防ぐために私たちが採用したのが、機能駆動（Feature-First）アーキテクチャです。
これは、技術的な関心事（Controller, Modelなど）でファイルを分けるのではなく、「機能（ドメイン）」単位で垂直スライス（Vertical Slice）してディレクトリを分割するアプローチです。
Airiの開発では、`src/features/` 配下にすべての機能を集約しています。
例えば `src/features/attendance/` のディレクトリを開けば、UIコンポーネントからビジネスロジック、データアクセス層、さらにはその機能専用のプロンプト指示書に至るまで、勤怠機能に関するすべてがその一箇所に収まっています。
3. 実践：AIにどう「ヒト向けの配置」を徹底させるか？
「機能ごとにコードを一箇所にまとめる」というアーキテクチャを採用した上で、最も重要なのは「AIにそのルールを徹底させること」です。
AIは放っておくと、一般的なベストプラクティス（レイヤードアーキテクチャ）に従って、勝手にファイルを散らかして生成してしまう傾向があります。
そこで私たちは、Vol.3で紹介した「`.agent/rules`」ディレクトリを活用し、AIに対して「責務分離と配置のルール」を徹底させています。
「1機能1ディレクトリ」の絶対ルール
AIに対するプロンプトやルールとして、「勤怠に関するコードは、絶対に `src/features/attendance/` の中にカプセル化すること。他の機能ディレクトリに依存させないこと」を遵守させます。
これにより、ヒトが後からコードの修正やレビューを行う際、「とりあえず `features/attendance/` フォルダだけ見れば、すべてが理解できるし思い出せる」という状態が担保されます。
ヒトのための防御的設計
機能間の依存を極力減らしカプセル化することは、AIが「予期せぬ破壊的変更」を起こすのを防ぐだけでなく、ヒトの心理的安全性にも直結します。
「ここを変更しても、他の機能（フォルダ）には影響しない」と確信できるため、ヒトがコードを読む際のストレスが激減するのです。
4. 学びと成果：ヒトが「楽をする」ためのアーキテクチャ
「AIにたくさんコードを書かせるなら、ヒトが簡単に思い出せる（理解できる）構造にしなければならない」という設計思想に切り替えた結果、プロジェクトのメンテナンス性は驚くほど向上しました。
新機能を追加するなら `features/` に新しいフォルダを作らせるだけ。
不要になった機能を削除するならフォルダごと消すだけ。
影響範囲が明確なため、新しく参画したメンバーでも、「どこに何があるか」を瞬時に把握できるようになりました。
AIがどれだけ賢くなっても、最終的にシステムの責任を持ち、運用していくのはヒトです。
だからこそ、コードベースは「ヒトの認知負荷が最小になる形」を保つ必要があります。
5. まとめ
AIペアプログラミング時代において、真に求められるアーキテクチャとは「機械にとって効率が良いもの」でも「記述量が減るもの」でもありません。
「ヒトがいかに楽にコンテキストを思い出し、全体像を把握できるか」に最適化されたアーキテクチャです。
機能駆動（Feature-First）アーキテクチャは、まさにこの「ヒトのためのDX（Developer Experience）」を極限まで高めてくれる最高のアプローチだと実感しています。
次回は、Airiの爆速開発を基盤から支える 「Vol. 5: Bun Workspace によるモノレポ構成」 についてお届けします！お楽しみに。
この記事は以下の体制で作成されました。
ドラフト作成・執筆: Airi (社内AIアシスタント)
アイデア出し・レビュー: CTO
デザイン: 事務スタッフ
Accel-Hackでは、テクノロジーを駆使して世の中の課題を解決していく仲間を募集しています。
私たちの取り組みに少しでも興味を持っていただけたら、ぜひ採用ページや会社サイトも覗いてみてくださいね。
