エンジニアの「設計」を全部並べたら40種類あった｜6層マップで完全整理
動画テキストおよび一般的なWeb開発・システム設計のベストプラクティスに基づき、RUNTEQ公式動画で紹介されている「エンジニアの設計40種類（6つのカテゴリー/6層マップ）」について、現場の裏話や開発コンサルの雑学を交えながら分かりやすく整理・解説します。
🏗️ 設計の6層マップ（全6カテゴリー・40種類）
システム開発における「設計」は、事業立ち上げ（上流）から、コードレベルの実装（内部設計）、そして最新のAI活用（AI時代）まで6つのレイヤーに分類されます。
【層1】事業・要件定義（上流）
↓
【層2】全体の構造（アーキテクチャ）
↓
【層3】ユーザー・外部連携（外部設計）
↓
【層4】実装・データ構造（内部設計）
↓
【層5】全体に及ぶ品質（横断設計）
↓
【層6】AI駆動開発（AI時代の設計）
カテゴリー①：上流（事業・要件レベルの設計）
プロダクトを「なぜ作るのか」「何を作るのか」を決める最上流のステップです。
-
ビジネス要件設計：マネタイズ設計やビジネスモデルの落とし込み。
-
システム化構想設計：ITで何を解決し、何を人間がやるか（運用）の切り分け。
-
業務フロー設計（As-Is / To-Be）：現状の業務フローと、システム導入後の理想のフロー設計。
-
要件定義（機能要件）：画面や機能として「何を実装するか」の定義。
-
要件定義（非機能要件）：性能、可用性、セキュリティなどの基準値設定。
-
制約条件・前提条件設計：予算、納期、既存システム連携などの縛りの整理。
💡 業界雑学・裏話
多くのプロダクトが失敗する理由は「コードの書き方」ではなく、この上流の要件定義のズレです。特に非機能要件（「同時に何人使っても耐えられるか」など）を初期に放置すると、後からインフラを全面作り直す大事故（炎上案件）に発展します。
カテゴリー②：アーキテクチャ（全体構造の設計）
システムの骨組みや基盤を決める技術選定と構造の設計です。
-
システムアーキテクチャ設計：モノリスにするかマイクロサービスにするか等の全体方針。
-
クラウド/インフラアーキテクチャ設計：AWS/GCP/Azure上の構成（VPC、サブネットなど）。
-
ネットワーク設計：ルーティング、DNS、CDN（Cloudflare等）配置。
-
コンテナ/オーケストレーション設計：Docker、Kubernetes（k8s）のクラスタ構造。
-
サーバーレス/エッジアーキテクチャ設計：AWS LambdaやCloudflare Workers等の活用。
-
データアーキテクチャ設計：RDB、NoSQL、キャッシュ（Redis）の使い分けやデータパイプライン。
-
マルチテナントアーキテクチャ設計：B2B SaaSで企業ごとのデータをどう分離するか。
-
イベント駆動アーキテクチャ（EDA）設計：KafkaやRabbitMQを使った非同期処理。
💡 業界雑学・裏話
昔は「とりあえずモノリス＋RDB」が標準でしたが、現代のWebスタートアップでは「クラウドサービスをどう組み合わせるか（サーバーレス/SaaS結合）」がアーキテクチャ設計の主流です。ここを失敗すると、月のAWS利用料が数百万円に跳ね上がることも……。
カテゴリー③：外部設計（ユーザー・他システムとの接続）
システムの「外側」と接するインターフェースの設計です。
-
UI/UX設計：画面遷移、レイアウト、ワイヤフレーム。
-
デザインシステム設計：Figma等でのコンポーネント共通化・カラーパレット定義。
-
画面遷移設計：ユーザーが目的を達成するまでのステップ（ステート遷移）。
-
API設計（REST / GraphQL / gRPC）：エンドポイント名、リクエスト/レスポンスの型定義。
-
外部システム連携設計：Stripe（決済）、SendGrid（メール）等の外部SaaS連携。
-
バッチ処理設計：夜間データ集計や定期実行タスクのタイミングとリトライ処理。
-
帳票・レポート出力設計：PDF生成やCSVエクスポートのフォーマット設計。
💡 業界雑学・裏話
フロントエンドとバックエンドを別々のエンジニアが開発する場合、**「18. API設計」**を一番最初に合意（API Mockを作成）しておかないと、開発終盤で「データ型が違って繋がらない！」という地獄を見ることになります。
カテゴリー④：内部設計（実装・コードレベルの設計）
プログラマーが実際にコードを書く前の「詳細な仕組み」の設計です。
-
データベース設計（ER図・正規化）：テーブル構造、リレーションシップ、インデックス。
-
ドメインモデル設計（DDD）：ビジネスロジックをオブジェクト指向/関数型でどう表現するか。
-
アプリケーションアーキテクチャ設計：クリーンアーキテクチャ、MVC、Layered Architecture等。
-
クラス・モジュール設計：Solid原則に基づいたコンポーネント分離。
-
状態管理設計：フロントエンドのState（Redux, Zustandなど）やサーバー側のセッション状態。
-
アルゴリズム・ロジック設計：複雑な計算やデータ処理の手順。
-
エラーハンドリング・例外設計：落ちた時にどうスタックトレースを取り、ユーザーにどう伝えるか。
💡 業界雑学・裏話
初心者エンジニアが最初に直面する壁が**「データベース設計（ER図）」**です。ここが崩れると、後からテーブルを追加するたびにクエリが複雑化し、N+1問題や深刻なパフォーマンス低下を招きます。
カテゴリー⑤：横断（全体を支える共通基盤・品質設計）
特定の機能ではなく、システム全体に関わるセキュリティや運用の設計です。
-
認証・認可設計：OAuth2.0、OIDC、JWT、ロールベースアクセス制御（RBAC）。
-
セキュリティ設計：OWASP Top10対策（XSS, CSRF, SQLインジェクションなど）。
-
ログ・オブザーバビリティ（可観測性）設計：DatadogやSentryを使ったログ、メトリクス、トレース。
-
CI/CD・デプロイパイプライン設計：GitHub Actionsを使った自動テスト＆自動リリース。
-
テスト設計：単体テスト、結合テスト、E2Eテストのテストピラミッド設計。
-
バックアップ・DR（災害復旧）設計：RPO（復旧ポイント目標）やRTO（復旧時間目標）の策定。
-
パフォーマンス/キャッシュ設計：CDN、Redis、DBインデックスによる高速化。
💡 業界雑学・裏話
昔のSIerでは「テスト仕様書」をExcelで何百枚も書く文化がありましたが、今のWeb系では**「テストコード（Jest, RSpec）そのものを設計とする」**のが主流です。また、認証・認可（Auth0など）を自作するのはセキュリティリスクが高いため「外部SaaSに任せる」のが現代のセオリーです。
カテゴリー⑥：AI時代に増えた設計（AI駆動開発・LLM活用）
近年（2024〜2026年）のAIブームによって新たに必須となった現代特有の設計分野です。
-
RAG（検索拡張生成）設計：社内ドキュメントをベクターDB（Pineconeなど）に入れてAIに答えてもらう構成。
-
プロンプトエンジニアリング/チェーン設計：LangChainやLlamaIndex等を使ったAIの思考フロー設計。
-
AIエージェント設計：AutogenやClaude Code等を使い、AIに自律的にツールを使わせる設計。
-
ガードレール・安全設計：AIのハルシネーション（嘘）や不適切発言を防ぐフィルター・検証設計。
-
AIコード生成・開発フロー設計：Claude CodeやGitHub Copilotを活用した、人間のレビュー前提のAI駆動開発モデル。
💡 業界雑学・裏話
Claude Codeなどの登場により、「人間がゼロからコードを書く」場面は急激に減り、「AIに適切なコンテキストと設計図を与えてコードを吐き出させ、人間がレビューする」スタイルが爆発的に普及しています。これにより、40種類の中でも上流・アーキテクチャ・DB設計の価値が相対的に上がっています。
🎯 初心者・未経験者はどこから学ぶべきか？
動画内でも触れられている、初心者がキャッチアップすべきおすすめのロードマップです。
-
DB設計（内部設計）：まずはER図が描けるようになる（必須）。
-
UI/UX・画面遷移設計（外部設計）：ユーザーに見える画面とデータ伝播のイメージを持つ。
-
API設計（外部設計）：JSONのやり取り、REST APIの概念を理解する。
-
アプリケーションアーキテクチャ（内部設計）：MVCやレイヤードアーキテクチャを体験する。
-
AI駆動開発の設計（AI時代）：Claude CodeやCopilotを使って、設計図からコードを高速生成する訓練をする。
最初から40種類すべてを極める必要はありません。開発の全体像（マップ）を持っておくことで、「今自分がどの部分を設計しているのか」を俯瞰できるようになります。
Claude Codeに代表される自律型AIエージェントの登場により、エンジニアの役割は「自らコードを書く実装者（コーダー）」から、「AIエージェントチームを指揮するオーケストレーター（指揮者・テックリード）」へと根本的にシフトしました。
コーディングのボトルネックが消滅した結果、要件定義とアーキテクチャ設計の重要性は下がったのではなく、むしろプロダクトの成否を分ける最重要プロセスへと価値が跳ね上がっています。
💡 1. 要件定義の役割の変化
従来：ドキュメント化と仕様固定
-
「画面遷移図」や「機能一覧Excel」を時間をかけて作成。
-
仕様漏れや曖昧さがあっても、実装しながら人間同士の口頭コミュニケーションで補完。
AI時代：AIに対する「制約条件の定義」と「コンテキスト注入」
-
曖昧さの徹底排除（明確なプロンプト／仕様化） AIは「行間を読む」ことができないため、曖昧な指示を出すとハルシネーション（嘘の生成）や的外れな実装が発生します。「何を実装するか」以上に「何をやってはいけないか（制約条件）」を言語化・文脈化する能力が求められます。
-
コンテキスト（文脈）の事前設計 Claude Codeなどのツールにプロジェクトの背景、ビジネスゴール、ドメイン知識を「いかに短く・過不足なくロードさせるか（
CLAUDE.mdなどのルールファイル設計）」が、要件定義の実質的な作業になります。 -
「プロトタイプ即作成」による要件の高速検証 要件定義書を何週間もかけて書く代わりに、要件のラフ案を投げてAIに10分でプロトタイプを作らせ、ユーザーに見せて要件を詰めるという「アジャイル要件定義」が主流になりました。
🏗️ 2. アーキテクチャ設計の役割の変化
従来：コンポーネントの構築と手作業による結合
-
クラス設計、ディレクトリ構成、ライブラリの選定、ボイラープレート（定型コード）の記述を手作業で実施。
AI時代：「ガードレール設置」と「長期的な保守性・セキュリティの担保」
-
AIが誤脱しないための「フレームワーク（境界線）」設計 AIはコードを爆速で生成しますが、放置すると「統一感のない密結合なコード」や「セキュリティホールの山」を作り出します。クリーンアーキテクチャやドメイン駆動設計（DDD）を用いて、「AIがコードを追加しても破綻しない明確な責務分離」を人間が事前に設計しておく必要があります。
-
非機能要件とコストの最適化 セキュリティ、スケーラビリティ、インフラコスト、レスポンス速度などの「非機能要件」は、AIが自動判断しにくい領域です。マルチクラウドの比較やデータ構造の最適化など、巨視的なシステムトレードオフの決断は人間のアーキテクトが責任を負います。
-
レビューアー（検証者）としてのアーキテクト 自分でコードを書く時間よりも、「AIが書いたコードのアーキテクチャ違反・脆弱性を検知・修正するレビュー作業」にシフトしました。
⚖️ 変化の対比まとめ
| 観点 | 従来のエンジニア | AI時代のエンジニア |
|---|---|---|
| 主業務 | 手作業でのコード記述、テスト作成 | AIへの指示設計、生成コードのレビュー・統合 |
| 要件定義 | 画面・機能の仕様書作成 | ビジネス文脈の言語化、AI用コンテキスト整備、制約定義 |
| アーキテクチャ | パターンに基づくモジュール構築 | AIが踏み外さないためのガードレール設計、非機能要件の決断 |
| 価値の源泉 | 実装スピード、言語・フレームワークの習熟 | ドメイン理解、システム俯瞰力、問題定義力 |
🎯 結論：求められるのは「1人のテックリード」としての視点
AI時代において、エンジニアは「ジュニアエンジニア（AI）を複数人束ねるチーフエンジニア／テックリード」としての振る舞いが求められます。
「どう書くか（How）」はAIが肩代わりしてくれるため、人間は「なぜ作るのか（Why）」「何を作るのか（What）」「どう全体を統合・評価するか（Evaluation）」という抽象度の高い上流・横断スキルを磨くことが、最も強い武器になります。
CLAUDE.md は、Claude Code などの AI エージェントに対して「このプロジェクトのコンテキスト、制約、開発手順」を一度にロードさせるためのシステム命令書です。
AI エージェントはリポジトリ配下に CLAUDE.md が存在すると自動的に読み込み、その記載に従ってコード変更やテストの実行を行ないます。
📌 CLAUDE.md に書くべき 5 大要素
-
プロジェクト概要 & 技術スタック（全体像の把握）
-
日常的に使うコマンド（ビルド、テスト、リンター、起動手順）
-
コーディング規約 & アーキテクチャ規則（ガードレールの設定）
-
Git・コミットルール（レビューや履歴の品質維持）
-
やってはいけないこと（禁止事項）（ハルシネーションや破壊的変更の防止）
📄 『CLAUDE.md』の具体例（テンプレート）
Web アプリケーション（Next.js + TypeScript + Prisma）を想定した実用的な構成例です。プロジェクトのルートディレクトリ（./CLAUDE.md）に配置します。
# CLAUDE.md - Project Context & Rules
## 1. Executive Summary & Tech Stack
This project is a SaaS web application for user management and task tracking.
- **Frontend**: Next.js (App Router), React, TypeScript, Tailwind CSS
- **Backend/ORM**: Next.js Server Actions, Prisma ORM
- **Database**: PostgreSQL
- **Testing**: Vitest (Unit), Playwright (E2E)
## 2. Essential Commands
When building, testing, or linting, always use the following commands:
- **Development**: `npm run dev`
- **Build**: `npm run build`
- **Lint**: `npm run lint` / Fix: `npx eslint --fix .`
- **Type Check**: `npx tsc --noEmit`
- **Run Single Test**: `npx vitest run path/to/file.test.ts`
- **Run All Tests**: `npm run test`
- **DB Migration**: `npx prisma migrate dev`
## 3. Architecture & Code Style Rules
- **Directory Boundaries**:
- `src/app/`: Presentation layer (App Router pages & Server Actions).
- `src/domain/`: Pure business logic. NO imports from `src/app` or Prisma allowed here.
- `src/infrastructure/`: Prisma client and external service integrations.
- **TypeScript Rules**:
- Strict mode enabled. Never use `any`. Use `unknown` with type guards if needed.
- Always export explicit interfaces/types for Server Action parameters and returns.
- **UI/Components**:
- Use Tailwind CSS. Avoid inline styles.
- Keep components modular. If a component exceeds 150 lines, split it into smaller sub-components.
## 4. Testing Requirements
- Every new feature must include corresponding unit tests in `src/__tests__/`.
- Before reporting task completion, you MUST run:
1. `npx tsc --noEmit`
2. `npm run lint`
3. `npx vitest run <changed_files>`
## 5. Strict Prohibitions (Do NOT Do)
- **NO Direct DB Access in UI Components**: Always go through Server Actions or Repository layer.
- **NO Breaking Changes to DB Schema**: Never edit existing Prisma migration files directly; create a new migration.
- **NO Secrets in Code**: Never hardcode API keys or credentials. Use `.env.local` references.
- **NO Force Push**: Never run `git push --force`.
🎯 効果的に機能させるための 4 つの書き方ノウハウ
-
簡潔かつ直接的に書く（トークン節約） 冗長な文章ではなく、箇条書きやコードブロックを使って簡潔に記述します。
-
「コマンド実行」を明示する AI は「テストを書いて」と命じるとコードだけ書いて終わることがあります。「変更後は必ず
npx tscとnpm run testを実行してエラーが出ないか確認すること」と書いておくことで、自律的に自己修正ループを回すようになります。 -
アーキテクチャの境界線（関心事の分離）を厳格にする 「
src/domainからPrismaを呼ぶな」といったレイヤー違反の禁止ルールを明記することで、コードのスパゲティ化を防げます。 -
リポジトリの成長に合わせて更新する 新しいライブラリ（例: Zod, Shadcn UI）を導入した場合や、AI が同じ間違いを繰り返した時は、随時
CLAUDE.mdにルールを追加・修正します。
Python/FastAPI や Go、Ruby on Rails などのバックエンド開発向け CLAUDE.md の具体的な設定例を教えてください。
代表的な 3 つのスタック（Python/FastAPI、Go、Ruby on Rails）のテンプレート例です。
🐍 1. Python / FastAPI（Clean Architecture / Pydantic）
Python では、型ヒントの徹底や Async/Sync の混同防止、Pydantic / ORM (SQLAlchemy 等) のディレクトリ境界を明記するのがポイントです。
# CLAUDE.md - FastAPI Project Rules
## 1. Tech Stack & Architecture
- **Language**: Python 3.12+ (Strict typing required)
- **Framework**: FastAPI + Uvicorn
- **ORM / DB**: SQLAlchemy 2.0 (Async) + Alembic + PostgreSQL
- **Package Manager**: `uv` (or `poetry`)
## 2. Essential Commands
- **Dev Server**: `uv run uvicorn app.main:app --reload`
- **Lint / Format**: `uv run ruff check .` / `uv run ruff format .`
- **Type Check**: `uv run mypy app`
- **Run Tests**: `uv run pytest`
- **Single Test**: `uv run pytest tests/test_user.py`
- **DB Migration**: `uv run alembic revision --autogenerate -m "description"` -> `uv run alembic upgrade head`
## 3. Coding Standards & Layers
- **Architecture**:
- `app/api/`: Routers & Request/Response schemas (Pydantic). NO direct DB queries.
- `app/services/`: Core business logic.
- `app/crud/` or `repositories/`: Database queries via SQLAlchemy AsyncSession.
- **Async Rules**:
- Always use `async def` for endpoints and I/O-bound CRUD operations.
- Do NOT block the event loop with synchronous I/O or heavy computation.
- **Type Hints**:
- All functions must have input argument and return type annotations.
## 4. Strict Prohibitions
- **NO `Any` Type**: Avoid `typing.Any`. Use `Pydantic` models or `Generics`.
- **NO Raw SQL in Routers**: All queries must pass through the repository/CRUD layer.
- **NO Unhandled Exceptions**: Return standard HTTP exceptions via `fastapi.HTTPException`.
🐹 2. Go（Standard Layout / DDD-like）
Go では、エラーハンドリング（if err != nil）の徹底、インターフェースによる抽象化、Go の標準的なディレクトリ構造を指示します。
# CLAUDE.md - Go Project Rules
## 1. Tech Stack
- **Language**: Go 1.22+
- **HTTP Framework**: `chi` (or `gin`)
- **Database**: PostgreSQL + `sqlc` (or `GORM`)
- **Testing**: Standard `testing` package + `testify`
## 2. Essential Commands
- **Run App**: `go run cmd/server/main.go`
- **Run Tests**: `go test ./...`
- **Single Package Test**: `go test ./internal/usecase/...`
- **Lint**: `golangci-lint run`
- **Generate SQL Code**: `sqlc generate`
## 3. Architecture & Conventions
- **Directory Structure**:
- `cmd/server/`: Main application entry points.
- `internal/handler/`: HTTP handlers and request parsing.
- `internal/usecase/`: Application business rules (Interactions between domain and repository).
- `internal/domain/`: Entities and Repository interfaces.
- `internal/infrastructure/`: Database access and external API implementations.
- **Error Handling**:
- ALWAYS check `if err != nil`. Never ignore errors.
- Wrap errors with context using `fmt.Errorf("failed to do X: %w", err)`.
- **Concurrency**:
- Always pass `context.Context` down to DB and external HTTP calls.
## 4. Strict Prohibitions
- **NO Panic**: Never use `panic()` in business logic or handlers (use proper error returns).
- **NO Global Variables**: Pass dependencies explicitly via constructor functions (`NewService(...)`).
- **NO Package Cycle**: Strictly follow unidirection dependencies (`handler` -> `usecase` -> `domain` <- `infrastructure`).
💎 3. Ruby on Rails（API Mode / Service Object）
Rails は規約（CoC）が強いですが、肥大化しやすい Fat Model / Fat Controller を防ぐための「Service Object や Form Object の設計指針」を明記するのが重要です。
# CLAUDE.md - Ruby on Rails (API Mode) Rules
## 1. Tech Stack
- **Framework**: Ruby 3.3+ / Rails 7.1+ (API mode)
- **Database**: PostgreSQL
- **Background Jobs**: Sidekiq + Redis
- **Testing**: RSpec
## 2. Essential Commands
- **Server**: `bin/rails server`
- **Console**: `bin/rails console`
- **Linter**: `bundle exec rubocop` / Auto-fix: `bundle exec rubocop -A`
- **Run All Specs**: `bundle exec rspec`
- **Single Spec**: `bundle exec rspec spec/services/create_user_service_spec.rb`
- **DB Migration**: `bin/rails db:migrate`
## 3. Architecture & Guidelines
- **Skinny Controllers & Models**:
- Keep Controllers strictly for request routing and status codes.
- Keep Models strictly for associations, scopes, and simple validations.
- Put complex business logic into Service Objects (`app/services/`).
- **Response Format**:
- Use `Jbuilder` or `blueprinter` for JSON serialization.
- **Testing (RSpec)**:
- Write request specs for endpoints (`spec/requests/`) and unit specs for services (`spec/services/`).
- Use `FactoryBot` instead of fixtures.
## 4. Strict Prohibitions
- **NO N+1 Queries**: Always use `includes`, `eager_load`, or `preload` for associated data.
- **NO Callbacks for Business Logic**: Avoid `after_save` / `after_create` in ActiveRecord models for sending emails or calling external APIs (move these to Service Objects).
- **NO Direct DB Edits in Production**: Always write idempotent migration scripts.
💡 バックエンド向け CLAUDE.md 運用マニュアル
-
DB マイグレーションコマンドは確実に書く AI に「テーブル追加して」と頼んだ際、モデルコードだけでなく
Alembicやrails db:migrateなどのコマンドまで自律的に実行させるために必須です。 -
N+1 問題やトランザクション境界を指定する バックエンド特有の不具合（N+1、デッドロック、ロールバック漏れ）を防ぐため、「トランザクションブロックの中で外部 API を叩くな」「
includesを忘れるな」といったガードレールが効果的です。
GitHub Actions などの CI に AI コード生成のチェック（テスト・Lint・セキュリティ検証）を組み込む具体的な方法を教えてください。
CI（GitHub Actions）でこれらを全自動ガードレールとして検証し、AI のコードを安全にメインブランチへ統合するパイプラインの構築手順を解説します。
🛠️ 1. CI パイプラインで構築すべき 4 つの防壁
AI 駆動開発における CI パイプラインでは、通常のチェックに加えて AI 特有の問題を検知するステップを用意します。
[ AI による PR 作成 ]
│
├── ① 静的解析・型チェック (Lint / Type Check / AI 特有のハザード検知)
├── ② セキュリティ・秘密情報スキャン (Secret Detection / SAST)
├── ③ テスト & カバレッジ検証 (Unit / E2E / N+1 検知)
└── ④ AI レビュー & ドキュメント整合性チェック (PR Summary / Spec Check)
📄 2. GitHub Actions ワークフローの実装例
以下は、AI が作成した Pull Request（PR）に対して「型チェック」「Lint」「セキュリティスキャン」「テストとカバレッジ計測」を全自動で並列実行する GitHub Actions（.github/workflows/ai-code-check.yml）の実装例です。
name: AI Generated Code Verification
on:
pull_request:
branches: [ main, develop ]
jobs:
# -------------------------------------------------------------
# Job 1: Lint, Type Check & Basic Syntax
# -------------------------------------------------------------
lint-and-typecheck:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: 20
cache: 'npm'
- name: Install Dependencies
run: npm ci
- name: Run Type Check
run: npx tsc --noEmit
- name: Run ESLint
run: npm run lint
# -------------------------------------------------------------
# Job 2: Security & Secret Scanning (AI の誤記載・脆弱性防止)
# -------------------------------------------------------------
security-scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
# ① ハードコードされた API キーや秘密情報の検出
- name: Secret Detection (TruffleHog)
uses: trufflesecurity/trufflehog-actions-scan@main
with:
base: ${{ github.event.pull_request.base.sha }}
head: ${{ github.event.pull_request.head.sha }}
# ② 依存ライブラリの脆弱性チェック (AI が古い/悪意ある package を入れるのを防ぐ)
- name: Dependency Audit
run: npm audit --audit-level=high
# ③ コード内のセキュリティ脆弱性スキャン (SAST)
- name: CodeQL Analysis
uses: github/codeql-action/init@v3
with:
languages: 'typescript, javascript'
- uses: github/codeql-action/analyze@v3
# -------------------------------------------------------------
# Job 3: Automated Testing & Coverage Guardrail
# -------------------------------------------------------------
test-and-coverage:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: 20
cache: 'npm'
- name: Install Dependencies
run: npm ci
# テスト実行 ＆ カバレッジレポート出力
- name: Run Unit Tests with Coverage
run: npx vitest run --coverage
# カバレッジ低下の監視 (例: 80% 未満ならエラーにする)
- name: Check Coverage Threshold
run: |
COVERAGE=$(npx make-coverage-badge --print-only)
echo "Current Coverage: $COVERAGE%"
# しきい値チェックのスクリプトをここで実行
🎯 3. AI 特有の事故を防ぐ CI 運用ノウハウ
① ハルシネーションパッケージ（Package Hallucination）の撃退
AI は実在しない npm / PyPI パッケージ名や、タイポされた類似パッケージ（タイポスクワッティング）をインポートすることがあります。
-
対策: CI 内で
npm auditやpip-auditを必須化し、レジストリに存在しない/リスクの高いパッケージが入った時点でビルドを落とします。
② テストカバレッジの低減防止（カバレッジ・ラチェット）
AI に実装だけを行わせるとテストコードが書かれないまま PR が作られ、全体のリポジトリ品質が低下します。
-
対策: CI で「PR 提出前よりテストカバレッジが低下した場合はマージ不可」とするルール（カバレッジ・ラチェット）を設定します。
③ Claude / OpenAI API を活用した「AI による AI コードの二次レビュー」
CI 内で Lightweight な AI モデル（Claude 3.5 Sonnet など）のレビューアクション（例: coderabbitai や chatgpt-action）を起動し、次のような視点で自動コメントさせます。
-
「この変更は
CLAUDE.mdのアーキテクチャルールに違反していませんか？」 -
「パフォーマンス（N+1 問題など）上の懸念はありませんか？」
🔒 4. GitHub ブランチ保護ルールの設定
CI ワークフローを作成したら、GitHub の Settings > Branches から以下を有効にします。
-
Require status checks to pass before merging
-
上記の
lint-and-typecheck,security-scan,test-and-coverageすべての通過をマージ条件にする。
-
-
Require a pull request before merging
-
人間（テックリード等）による最低1名の Code Review 承認を必須にする。
-
このパイプラインを敷いておくことで、AI エージェントに「コードを書いて PR を作成するまで」を完全に任せても、人間は安心して最終レビューとマージ判断に集中できるようになります。
AI が生成したコードの脆弱性や秘密情報漏洩を検出する TruffleHog や CodeQL の詳しい設定とチューニング方法を教えてください。
eval や exec 等）の利用」「SQL インジェクションや XSS への配慮漏れ」が発生しやすい傾向があります。これらを防止する TruffleHog（秘密情報検出） と CodeQL（静的解析・SAST） について、GitHub Actions で高精度に機能させる設定とチューニング方法を解説します。
🔑 1. TruffleHog：秘密情報（APIキー・クレデンシャル）の検出
TruffleHog は、単なる正規表現マッチングだけでなく、検出した API キーが「実際に有効（Live）かどうか」を各サービスの API へ検証リクエストを送って判断する強力なツールです。
⚙️ おすすめの .github/workflows/trufflehog.yml 設定
AI が過去のコミット履歴や別ブランチにキーを紛れ込ませるケースに対応するため、PR の差分全体を検証するように指定します。
name: TruffleHog Secret Scan
on:
pull_request:
branches: [ main, develop ]
jobs:
trufflehog:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
with:
fetch-depth: 0 # 全コミット履歴を取得して過去の誤埋め込みも検出
- name: TruffleHog OSS Scan
uses: trufflesecurity/trufflehog-actions-scan@v3.82.6
with:
# PRのベースブランチからヘッドブランチまでの差分を完全スキャン
base: ${{ github.event.pull_request.base.sha }}
head: ${{ github.event.pull_request.head.sha }}
extra_args: --debug --only-verified # 有効（Live）と判定されたキーのみエラーにする
🎯 TruffleHog のチューニングポイント
-
--only-verifiedフラグの活用（ノイズ削減） ダミーのサンプルキー（例:sk_test_123456...）や開発用のダミー文字列による誤検知（False Positive）で CI が頻繁に止まるのを防ぎます。「実際に機能する本物のキー」が検出された場合のみ CI を失敗させます。 -
.trufflehogignoreによる除外設定 テスト用のモックデータや暗号化されたシークレットファイルを明示的に除外します。Plaintext# .trufflehogignore # テスト用ダミーデータディレクトリを除外 src/__tests__/mocks/ *.example.env
🛡️ 2. CodeQL：コードの脆弱性・アンチパターンの検出
CodeQL は、コードをデータベース化してクエリ（QL）を実行することで、「外部入力（Source）がセキュリティ対策なしで危険な処理（Sink）に到達していないか（タイント解析）」を検証します。
⚙️ おすすめの .github/workflows/codeql.yml 設定
AI 特有の脆弱性（SQL インジェクション、コマンドインジェクション、SSRF など）を厳格に弾くため、セキュリティ拡張ルールセット（security-extended）を指定します。
name: "CodeQL Advanced Security Scan"
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
analyze:
runs-on: ubuntu-latest
permissions:
security-events: write # SARIF レポート出力に必要
actions: read
contents: read
strategy:
fail-fast: false
matrix:
# プロジェクトで使用している言語を指定
language: [ 'javascript-typescript', 'python' ]
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Initialize CodeQL
uses: github/codeql-action/init@v3
with:
languages: ${{ matrix.language }}
# 標準ルールに加え、セキュリティ拡張ルールセットを適用
queries: security-extended,security-and-quality
# 独自の設定ファイルを読み込み
config-file: ./.github/codeql/codeql-config.yml
- name: Perform CodeQL Analysis
uses: github/codeql-action/analyze@v3
with:
category: "/language:${{matrix.language}}"
🔧 3. CodeQL のカスタマイズ・チューニング
デフォルトの設定では、テストコードや自動生成コード（Prisma Client や OpenAPI クライアントなど）に対して大量のアラートが出てしまいます。これらを排除するために .github/codeql/codeql-config.yml を作成してチューニングします。
📄 .github/codeql/codeql-config.yml の例
name: "Custom CodeQL Configuration"
# ① スキャン対象外とするファイルの指定（AIが生成した不要なコードやテストを除外）
paths-ignore:
- '**/node_modules/**'
- '**/dist/**'
- '**/*.test.ts'
- '**/*.spec.ts'
- 'src/__tests__/**'
- '**/migrations/**'
# ② 無効化するルールの指定（特定言語のノイズを抑える）
disable-rules:
# 例: 厳格すぎるコメント規約ルールなどをオフにする
- js/jsdoc-missing-documentation
💡 AI 開発特有のトリプル防御まとめ
| ツール | 検知対象 | 主なチューニング技法 |
|---|---|---|
| TruffleHog | 生の API キー、DB パスワード、アクセストークン |
|
| CodeQL | SQL インジェクション、XSS、SSRF、コマンド注入 |
|
| Lint / TypeCheck | 構文エラー、any 型乱用、非推奨 API |
ESLint / TypeScript の厳格化ポリシーを CLAUDE.md で指定。 |
これら2つのツールを GitHub Actions でブランチ保護ルール（Branch Protection Rules）に登録することで、AI が作成した PR の脆弱性やクレデンシャル漏洩を全自動でシャットアウトできます。
CodeQL や TruffleHog に引っかかるような脆弱性コードを AI が最初から出力しないようにするための CLAUDE.md やプロンプトのガードレール設定を教えてください。
CLAUDE.md およびシステムプロンプト向けセキュリティガードレール設定です。CLAUDE.md に具体的な「禁止事項」と「推奨実装パターン」をポジティブ／ネガティブの両面から明確にルール化しておくことで、CodeQL や TruffleHog に引っかかるコードの出力を大幅に抑制できます。
📄 セキュリティ特化型 CLAUDE.md のガードレール記述例
プロジェクト配下の ./CLAUDE.md に以下の Security & Guardrails セクションを追加・統合します。
## 🔒 Security & Code Safety Rules (STRICT COMPLIANCE)
AI must strictly adhere to the following security guidelines to prevent vulnerabilities (OWASP Top 10) and credential leaks.
### 1. Secrets & Credentials Management (Anti-TruffleHog)
- **NEVER Hardcode Secrets**: Never insert real or realistic-looking API keys, JWT tokens, AWS keys, passwords, or private keys directly into code or comments.
- **Environment Variables**: Always read credentials from environment variables using `process.env.KEY_NAME` (Node.js) or `os.environ.get("KEY_NAME")` (Python).
- **Test / Mock Data**: Use generic placeholder strings like `process.env.TEST_API_KEY || "dummy_key_for_testing"` in test files. Do NOT use authentic-looking hashing strings.
### 2. Database & SQL Injection Prevention (Anti-CodeQL)
- **NO Raw SQL Concatenation**: NEVER build SQL queries using string formatting or concatenation (e.g., `f"SELECT * FROM users WHERE name = '{name}'"` is STRICTLY PROHIBITED).
- **Parameterized Queries / ORM**: Always use parameterized queries or ORM methods (Prisma, SQLAlchemy, ActiveRecord, `sqlc`).
- *Bad*: `db.query(`SELECT * FROM users WHERE id = ${id}`)`
- *Good*: `db.query('SELECT * FROM users WHERE id = $1', [id])`
### 3. XSS & Code Execution Vulnerabilities (Anti-CodeQL)
- **NO Dynamic Code Execution**: NEVER use `eval()`, `exec()`, `Function()`, `setTimeout(string)`, or `dangerouslySetInnerHTML` without proper sanitization.
- **XSS Prevention**: In Web UI, ensure user input is HTML-escaped. Use DOMPurify if rendering rich text/HTML is required.
### 4. Input Validation & SSRF Prevention
- **Strict Input Validation**: Validate all incoming parameters (URL params, request body) using schema validators (`Zod`, `Pydantic`).
- **SSRF Prevention**: If making outbound HTTP requests based on user input, strictly validate the protocol (HTTP/HTTPS only) and disallow internal IP ranges (`127.0.0.1`, `10.0.0.0/8`, `169.254.169.254`).
### 5. Authentication & Authorization (RBAC)
- **Check Authorization First**: Every API route/endpoint must explicitly check user authentication and permissions before accessing or mutating resources. Never assume authorization.
🎯 効果を最大化する 4 つのプロンプト設計テクニック
CLAUDE.md に書くだけでなく、実際の指示（対話）やプロンプトテンプレートにも以下の要素を盛り込むと、出力精度が安定します。
① ネガティブパターン（NG例）とポジティブパターン（OK例）を対で提示する
AI は「〜するな」という抽象的な禁止事項よりも、「こういう間違い（Bad）を起こさず、代わりにこう書け（Good）」という具体対比に対して強い追従性を示します。
② シークレットのダミー表記方法を指定する
テストコード生成時などに AI が「リアルっぽいダミーキー（例: sk-live-51Nx...）」を自動生成すると、TruffleHog の静的パターン検知を叩いてしまいます。「テスト時のダミー文字列は dummy-secret-token や ENV_VAR_PLACEHOLDER に固定せよ」と指定します。
③ クリーンアップコマンドの自己実行を義務付ける
AI が作業途中で .env ファイルや一時的なログファイルにキーを出力してしまう事故を防ぐため、以下の一文を CLAUDE.md に記載します。
- Always check `git status` before finishing a task to ensure no sensitive configuration files, `.env` files, or temporary credentials have been staged or modified.
④ 堅牢化プロンプト（ワンショット指示の例）
セキュリティリスクの高い機能（認証・認可、ファイルアップロード、決済処理など）を生成させる際は、指示の冒頭に以下のコンテキストを付与します。
プロンプト例： 「ユーザープロフィール画像を S3 にアップロードする API エンドポイントを実装してください。実装にあたっては CodeQL や TruffleHog などの SAST ツールで検出される OWASP Top 10 脆弱性（SSRF、ファイルパスインジェクション、認証不備、APIキー直書き）が 0 件になるよう、安全なバリデーションと環境変数参照を徹底してください。」
🔄 セキュリティシフトライフサイクル
[ CLAUDE.md (事前防止) ] ➔ [ エージェント生成 ] ➔ [ TruffleHog / CodeQL (CI自動検知) ] ➔ [ 人間レビュー ]
事前の CLAUDE.md によるガードレール設定と、CI/CD での TruffleHog / CodeQL による機械的な検証を組み合わせることで、「そもそも危険なコードが生成・PR化されない」二重の防壁を構築できます。
0 件のコメント:
コメントを投稿