@shimori(shi mori)AI時代の設計ガードレール～崩れないSpring Boot設計ルール実践～JavaAIjjugArchUnitClaudeCode0Posted at 2026-04-09 本記事は、2026/5/30開催の「JJUG CCC 2026 Spring」の登壇内容に関連した技術記事シリーズです。 AIエージェント（Copilot / Claude Code / Cursor）の普及により、Java開発の前提は大きく変わりました。本シリーズでは「AI時代における設計の変化」をテーマに、実務視点で整理していきます。【シリーズ一覧】 AI時代にJava設計はどう変わったのかカッペリーニコードとは何か Java17/21は設計をどう変えたか AIは設計できるのか AI時代の設計ガードレールはじめに AIエージェントがコードを書く時代になった。 GitHub Copilot、Claude Code、Cursorを使えば、DTOやRepositoryといった定型コードは驚くほど高速に生成できる。しかし現場では、こんな問題が静かに進行している。・Service層が消えてControllerがRepositoryを直接呼ぶ・API単位でDTOが爆発的に増殖する・モジュール境界を無視したimportが広がる・Utilityクラスがドメインロジックを吸収し始めるコードはきれいなのに、構造が壊れていく。これはAIの問題ではなく、ガードレールがない開発環境の問題だ。本記事では、AI時代のSpring Boot開発に必要な設計ガードレールを、実務で使える具体策として整理する。なぜガードレールが必要か AIは「局所最適」が得意で「全体設計」が苦手 AIエージェントは目の前のタスクを解くことに長けている。「このエンドポイントを実装して」と指示すれば、動くコードを返す。問題は、AIが既存の設計文脈を理解しないまま実装することだ。次のコードを見てほしい。 @RestController @RequiredArgsConstructor public class OrderController { private final UserRepository userRepository; // ← Controller が Repository を直接参照 private final OrderRepository orderRepository; @PostMapping("/orders") public OrderResponse create(@RequestBody CreateOrderRequest request) { User user = userRepository.findById(request.userId()) .orElseThrow(() -> new NotFoundException("User not found")); Order order = new Order(user, request.items()); orderRepository.save(order); return new OrderResponse(order.getId()); } } AIが生成したこのコードは動く。しかし設計は壊れている。 Controller → Repository の直接依存（レイヤ違反）トランザクション境界がController側に滲み出るビジネスロジックがControllerに混入しているこれが1ファイルなら修正できる。しかしAI生成を繰り返すと、この「パターン」がコードベース全体に広がる。ガードレールがない開発で起きること症状原因 Service層の消失 ControllerがRepositoryを直接呼ぶ DTO爆発 AI がAPI単位でRecordを生成し続ける Utilityの増殖共通処理をUtilに逃がすAIの癖モジュール境界崩壊他featureのRepositoryを直接importするトランザクション散在 @Transactional をController/Repositoryに書くこれらはいずれもAIがコードを書くと発生しやすいパターンだ。防ぐには、構造を事前に固定するしかない。設計ルールパッケージ構造ルールレイヤー型ではなくfeature型を採用する。レイヤー型は一見整理されているが、機能が増えるとfeature間の依存が制御しにくくなる。 # NG: レイヤー型（機能が増えると依存が複雑化する） com.example ├── controller │ ├── UserController.java │ └── OrderController.java ├── service │ ├── UserService.java │ └── OrderService.java └── repository ├── UserRepository.java └── OrderRepository.java # OK: feature型（モジュール境界が明確） com.example ├── user │ ├── controller │ │ └── UserController.java │ ├── service │ │ └── UserService.java │ ├── domain │ │ └── User.java │ ├── repository │ │ └── UserRepository.java │ └── dto │ ├── CreateUserRequest.java │ └── UserResponse.java └── order ├── controller │ └── OrderController.java ├── service │ └── OrderService.java ├── domain │ └── Order.java ├── repository │ └── OrderRepository.java └── dto ├── CreateOrderRequest.java └── OrderResponse.java この構造のポイントはfeature間のRepository直接参照を禁止できることだ。 # OK: featureをまたぐ場合はServiceを経由する orderService → userService.findById() # NG: featureをまたいでRepositoryを直接参照する orderService → userRepository.findById() レイヤー責務ルール各レイヤーの責務を明文化し、チーム全員が参照できる場所に置く。 Controller @RestController @RequiredArgsConstructor @RequestMapping("/users") public class UserController { private final UserService userService; @PostMapping public UserResponse create(@RequestBody @Validated CreateUserRequest request) { return userService.create(request); } } 依存を許可するのはServiceのみ DTOのみ扱い、Entityを返さないビジネスロジックは一切書かない @Transactional は書かない Service @Service @Transactional @RequiredArgsConstructor public class UserService { private final UserRepository userRepository; public UserResponse create(CreateUserRequest request) { if (userRepository.existsByEmail(request.email())) { throw new DuplicateEmailException(request.email()); } User user = User.create(request.name(), request.email()); userRepository.save(user); return UserResponse.from(user); } } トランザクション境界はServiceが持つ（クラスレベルに @Transactional）ビジネスロジック・不変条件チェックはServiceに集約する依存を許可するのは同一feature内のRepositoryまたは他featureのService Repository @Repository public interface UserRepository extends JpaRepository { Optional findByEmail(String email); boolean existsByEmail(String email); } DBアクセスのみビジネスロジックを書かないクエリが複雑な場合は@Queryを使い、ロジックは書かない Domain（Entity） @Entity @Table(name = "users") @Getter @NoArgsConstructor(access = AccessLevel.PROTECTED) public class User { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private Long id; private String name; private String email; // ファクトリメソッドで生成制約を表現 public static User create(String name, String email) { User user = new User(); user.name = Objects.requireNonNull(name, "name must not be null"); user.email = Objects.requireNonNull(email, "email must not be null"); return user; } } 不変条件はEntityに閉じ込める Controller層への依存は絶対に持たない @Setter は原則使わない（状態変更はメソッドで表現する）命名規約命名が曖昧だとAIが誤ったパターンで補完する。明文化することでAIへのヒントにもなる。種別命名パターン例 Controller {Feature}Controller UserController Service {Feature}Service UserService Repository {Feature}Repository UserRepository Entity {FeatureName} User, Order リクエストDTO {動詞}{Feature}Request CreateUserRequest, UpdateUserRequest レスポンスDTO {Feature}Response UserResponse 詳細レスポンス {Feature}DetailResponse UserDetailResponse 例外 {原因}Exception DuplicateEmailException 禁止命名 XxxUtil / XxxUtils → ドメインに寄せる XxxHelper → 責務が不明確 XxxManager → Serviceに統合する XxxCommon → featureごとに分ける実装例：ArchUnitで自動検証する設計ルールは文書化するだけでは守られない。ArchUnitでテストとして実装する。依存関係 com.tngtech.archunit archunit-junit5 1.3.0 test レイヤー違反の検出 @AnalyzeClasses(packages = "com.example") public class LayerArchitectureTest { @ArchTest static final ArchRule controller_should_not_depend_on_repository = noClasses() .that().resideInAPackage("..controller..") .should().dependOnClassesThat() .resideInAPackage("..repository..") .because("ControllerはRepositoryを直接参照してはいけません。Serviceを経由してください。"); @ArchTest static final ArchRule controller_should_not_depend_on_domain = noClasses() .that().resideInAPackage("..controller..") .should().dependOnClassesThat() .resideInAPackage("..domain..") .because("ControllerはEntityを直接扱ってはいけません。DTOを使用してください。"); @ArchTest static final ArchRule repository_should_not_depend_on_service = noClasses() .that().resideInAPackage("..repository..") .should().dependOnClassesThat() .resideInAPackage("..service..") .because("Repositoryは上位レイヤーに依存してはいけません。"); } Transactionalの配置検証 @AnalyzeClasses(packages = "com.example") public class TransactionalArchitectureTest { @ArchTest static final ArchRule transactional_should_be_on_service_only = noClasses() .that().resideOutsideOfPackage("..service..") .should().beAnnotatedWith(Transactional.class) .because("@TransactionalはService層にのみ使用してください。"); } モジュール境界（feature間のRepository直接参照禁止） @AnalyzeClasses(packages = "com.example") public class ModuleBoundaryTest { @ArchTest static final ArchRule order_should_not_access_user_repository = noClasses() .that().resideInAPackage("com.example.order..") .should().dependOnClassesThat() .resideInAPackage("com.example.user.repository..") .because("featureをまたぐRepository参照は禁止です。Serviceを経由してください。"); } Utilityクラスの禁止 @AnalyzeClasses(packages = "com.example") public class NamingArchitectureTest { @ArchTest static final ArchRule no_utility_classes = noClasses() .should().haveSimpleNameEndingWith("Utils") .orShould().haveSimpleNameEndingWith("Util") .orShould().haveSimpleNameEndingWith("Helper") .because("Utilityクラスは禁止です。ロジックはドメインまたはServiceに配置してください。"); } 運用方法 AIへのプロンプト制御 AIエージェントに対して、プロジェクトのルールを明示的に伝えることで生成品質を上げられる。 CLAUDE.md / .cursorrules / Copilot Instructions に記述する # Architecture Rules ## Package Structure - Use feature-based package structure: `com.example.{feature}.{layer}` - Layers: controller / service / domain / repository / dto ## Layer Dependencies - Controller → Service only (never Repository or domain directly) - Service → Repository (same feature only) - Cross-feature access: always via Service, never via Repository ## Naming Conventions - Request DTO: `{Verb}{Feature}Request` (e.g. CreateUserRequest) - Response DTO: `{Feature}Response` (e.g. UserResponse) - Never create Util / Helper / Manager / Common classes ## Transaction - @Transactional is allowed only in Service layer (class level) - Never put @Transactional in Controller or Repository ## Entity Rules - Always use factory methods instead of public constructors - Never use @Setter on Entity fields - Never return Entity from Controller (always convert to DTO) このファイルを置くことで、AIエージェントがプロジェクトの設計ルールを文脈として参照しながらコードを生成するようになる。 CIパイプラインへの組み込み ArchUnitテストはユニットテストとして実行できるため、CIに組み込むだけで設計違反を自動検出できる。 # GitHub Actions の例 - name: Run Architecture Tests run: ./mvnw test -Dtest=*ArchitectureTest,*ModuleBoundaryTest,*NamingArchitectureTest CIが落ちたら設計違反、というルールにすることで、レビュー前に機械的に検出できる。 PRレビューの観点シフト AIがコードを書く時代のPRレビューは、構文ではなく構造を見ることに集中すべきだ。従来のレビュー観点 AI時代のレビュー観点変数名が適切かレイヤー依存が正しいかロジックのバグがないかモジュール境界を越えていないかコードが読みやすいか @Transactional の位置が正しいかテストが書かれているか EntityがControllerに漏れていないか AIが書いたコードのバグはAIが直せる。しかし構造の問題はレビュアーが指摘しなければ残り続ける。 AIに任せる領域・任せない領域 AI生成に向いている領域と、人間が設計すべき領域を明確にしておく。 AIに任せる（構造が決まっていれば高品質に生成できる） DTOのRecord定義 JPA Repositoryのクエリメソッド ControllerのCRUD実装 @ControllerAdvice の例外ハンドラー JUnit / Mockitoを使ったテストコード人間が設計する（AIには任せない） feature分割の境界設計 Aggregate境界とEntityの不変条件トランザクション境界の設計例外設計とエラーレスポンスの体系パッケージ構造とモジュール依存の方針まとめ AIはコードを書く能力において、定型的な実装では人間を大きく上回り始めている。しかし構造を設計する主体は人間だ、という事実は変わっていない。本記事で紹介した設計ガードレールを整理すると次のようになる。ガードレール手段パッケージ構造の固定 feature型構造を標準化するレイヤー依存の制約 ArchUnitでテスト化してCIに組み込む命名規約の明文化チームドキュメント + CLAUDE.mdに記述 AIプロンプトの制御 .cursorrules / CLAUDE.md にルールを書くレビュー観点のシフト構文ではなく構造を見るレビューへ AIと共存する開発において、アーキテクトに求められるのはコードを書く力ではなく構造を守る力だ。 AIは実装を担当する。人間は構造を設計する。この役割分担を仕組みとして整備することが、AI時代の設計ガードレールの本質だ。シリーズ一覧 AI時代にJava設計はどう変わったのかカッペリーニコードとは何か Java17/21は設計をどう変えたか AIは設計できるのか AI時代の設計ガードレール 0Go to list of users who liked0comment0Go to list of commentsRegister as a new user and use Qiita more convenientlyYou get articles that match your needsYou can efficiently read back useful informationYou can use dark themeWhat you can do with signing upSign upLogin

guardrails

📬 Get AI News Delivered

Browse by Category

Trending Topics

Empowering AI Safety: A Deep Dive into OCI Generative AI Guardrails

Analysis

Empowering the AI Era: The Crucial Rise of Harness Engineering

Analysis

Exploring the Boundaries of ChatGPT Pro: A Testament to Extensive AI Usage

Analysis

Fortifying AI Agents: How Pre-Tool Hooks Finally Stop LLMs from Breaking the Rules

Analysis

Landmark Legal Case Puts AI Safety and Accountability in the Spotlight

Analysis

Gartner Forecasts Innovative Security Strategies for 生成AI Applications by 2028

Analysis

Establishing Architectural Guardrails in the AI Era: Spring Boot Best Practices

Analysis

Designing Essential Guardrails to Teach Claude Code What Not to Touch

Analysis

Ensuring Safe AI Deployment: The Crucial Role of Azure Guardrails and Evaluation

Analysis

OpenClaw Soars: Nvidia Unveils Guardrails for Agentic AI

Analysis

Shielding AI Agents: A New Framework for Safe Autonomous Operation

Analysis

Claude Code's Multi-Layered Security: A New Era of AI Safety

Analysis

OpenAI Agents SDK: Building Multi-Agent Systems Made Easy

Analysis

Boosting AI Code Security: A 5-Layer Shield for Production Environments

Analysis

AI Security's Next Frontier: Balancing Defense and Restriction

Analysis

Decoding AI: Unveiling the Layers Behind the Assistant

Analysis

Boosting AI Safety: Creating Guardrails for Autonomous Agents

Analysis

Agentic AI's Quiet Revolution: Building Trust in the Invisible

Analysis

Amazon Bedrock Enhances Generative AI Safety with Advanced Guardrails

Analysis

OpenAI Robotics Leader's Departure Highlights Ethical Considerations in AI Collaboration

Analysis

Mastering Multimodal AI: A Practical Guide to Design and Implementation

Analysis

Amazon Bedrock Guardrails: Your Secret Weapon for Safe Generative AI Applications!

Analysis

Claude Code's Advanced Security: Shielding Your AI Agent with Robust Guardrails

Analysis

OpenAI's Sam Altman Shares Insights on DOD Agreement and AI Guardrails

Analysis

OpenAI's DOD Deal: Setting New AI Safety Standards

Analysis

Anthropic's Bold Stand: Prioritizing AI Safety

Analysis

Pentagon's AI Strategy: A New Framework for Guardrail Design

Analysis

Researchers Call for Safeguards on Infectious Disease Datasets for AI Development

Analysis

User Praises Enhanced Safety Features of New Generative AI

Analysis

Oracle's New AI Guardrails: Ensuring Safe Generative AI Applications

Analysis

📬 Get AI News Delivered

Browse by Category

Trending Topics