モジュール 01ターム1 · 基礎

AI を活用したエンジニアリングワークフロー

ログインすると、進捗を複数のデバイスで保存できます。ログインするまでは、このブラウザに保存されます。

なぜ重要なのか

DORA の 2025 年の調査は、AI を「導入先のシステムが持つ性質を増幅するもの」と表現しています。小さなバッチ、テスト、速いフィードバックを持つチームはさらに速くなります。それらがないチームは、バグをより速く出荷するだけです。このモジュールでは、AI をさらに導入する前に、まずその土台となるシステムを整えます。

学習目標

  1. AI が実装の拠り所にできる仕様書と受け入れテストを書ける。
  2. コンテキストを設計できる：ルールファイル、アーキテクチャメモ、実装例、制約。
  3. git をセーフティネットにして、小さくレビュー可能なバッチで作業できる。
  4. AI の出力を体系的にレビューし、AI に自分の主張を証明させられる。
  5. DORA の5つの指標でデリバリーを測定できる。

レッスン

1.1 まず仕様、プロンプトはその次

良い AI タスクには、ゴール、コンテキスト、制約、インターフェース、受け入れ基準、スコープ外が含まれます。

GOAL: Users can reset their password by email.
CONTEXT: Next.js app router, Supabase auth, Resend for email. See /docs/architecture.md.
CONSTRAINTS: Token single-use, expires in 30 min, stored hashed. Rate limit 5 requests/hour per email and per IP. Same response whether or not the email exists.
ACCEPTANCE: tests in /tests/reset.spec.ts must pass (write them first).
OUT OF SCOPE: SMS reset, UI redesign.

1.2 コンテキストエンジニアリング

  • リポジトリ単位のルールファイル（AGENTS.md テンプレート）に、AI が毎回従うべき標準を書きます。
  • /docs/architecture.md：コンポーネント、データフロー、信頼境界。
  • /docs/decisions/：ADR を置き、決着済みの選択を AI が蒸し返さないようにします。
  • コードベース内の良い既存例を1つAI に示してください。AI はパターンを忠実にコピーします。良いものも、悪いものも。

1.3 小さなバッチと git の規律

  • 1ブランチにつき1機能、1コミットにつき1つの関心事。
  • AI とのセッションの前には必ずコミットしてください。そうすれば、変更点をすべて git diff で確認し、気に入らないものを git restore で戻せます。
  • 承認なしに、エージェントに git push --force、本番環境へのマイグレーション、削除コマンドを実行させてはいけません。
  • 小さな変更は、DORA が特定した中で、速度と安定性の両方に最も効果のある唯一のレバーです。

1.4 仕様としてのテスト

AI 向けに調整したテストピラミッドです。

  • ユニットテスト： 純粋なロジック（価格計算、適格性判定、バリデーション）。
  • インテグレーションテスト： Docker 上の実データベース、実際のクエリ、実際の RLS ポリシー。
  • E2E テスト： 重要なユーザージャーニー（サインアップ、決済、コア機能）を Playwright でテストします。
  • セキュリティテスト： 「ユーザー A はユーザー B のデータを読めない」ことを確かめる認可テスト。あなたが書く中で最も価値のあるテストです。
  • Eval： LLM 機能向け（06 · AI とエージェントのセキュリティを参照）。

ルール：テストは自分で書くかレビューし、実装は AI に書かせる。 AI に両方を書かせると、両方を同じように間違えることがあります。

1.5 AI の出力をレビューする

レビューチェックリスト（PR テンプレートに貼り付けてください）：

  1. すべてのエンドポイントで、誰が呼び出しているか、そしてその人がリソースを所有しているかをチェックしているか？
  2. サーバー側の環境変数以外に、シークレット、キー、トークンが置かれていないか？
  3. タイムアウトのない外部呼び出しはないか？
  4. ループの中に DB クエリはないか？
  5. 新しい依存パッケージはあるか？ それは実在し、メンテナンスされ、バージョンが固定されているか？
  6. エラーは処理され、ログに記録され、表に出されているか。それとも握りつぶされているか？
  7. その変更は元に戻せるか？ マイグレーションはあるか？ 後方互換性はあるか？
  8. タスクのスコープ外のファイルに手を入れていないか？

AI に主張を証明させてください。「テストを実行して出力を貼り付けてください」「EXPLAIN プランを見せてください」「ユーザー A がユーザー B のレコードに対して 403 を受け取ることを示す curl を見せてください」。

1.6 デリバリーの測定：DORA の5つの指標

グループ 指標
スループット 変更のリードタイム、デプロイ頻度、失敗したデプロイからの復旧時間
不安定性 変更失敗率、デプロイの手戻り率

DORA は、これらを目標値にしてしまうことに警鐘を鳴らしています（グッドハートの法則）。ボトルネックを見つけるために使ってください。

1.7 AI が省きがちな品質の基本

CI でのリンティングとフォーマット、TypeScript の strict モード、アクセシビリティ（セマンティック HTML、ラベル、キーボード操作、WCAG 2.2 AA を満たすコントラスト）、そしてあらゆる境界でのスキーマライブラリ（Zod、Valibot）による入力バリデーション。

Lab 1：プロのやり方で機能を作る

仕様テンプレートを使って、「パスワードリセット」または「チームメイトの招待」を作ります。

  1. 仕様とテストを先に書きます（下書きは AI に手伝わせてもかまいませんが、承認するのはあなたです）。
  2. ブランチ上で AI に実装させます。
  3. チェックリストでレビューし、見つかった問題をすべて記録します。
  4. PR を作成します。CI で lint、型チェック、テストを必ず実行します。

完了の定義（Definition of Done）

AI プロンプト集

  • 「コードを書く前に、この仕様のエッジケースと障害モードを列挙してください。まだ実装はしないでください。」
  • 「認可が欠けていたら失敗するテストを書いてください。」
  • 「敵対的なシニアエンジニアとして、この diff をレビューしてください。問題点だけを、深刻度の高い順に挙げてください。」