0
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@tom20240926(tom)

codexのAGENT.mdをAIと一緒に考えてみた

0
Last updated at Posted at 2025-12-20

【検証レポート】Codex × AGENT.md × Amplify Gen2

1. はじめに（この記事で伝えたいこと）

AI コーディング支援（Codex / Copilot / Cursor など）は
コードを書く能力そのものは非常に高い一方で、以下のような問題が起きがちです。

  • 仕様を勝手に変える
  • 不要な依存を追加する
  • 設計や責務が崩れる
  • テストやドキュメントが後回しになる

本記事では、

AGENT.md を使って AI の行動を制御し、
実際のアプリ開発を通して「どこまで再現性のある開発ができるか」を検証する

という目的で、
AWS Amplify Gen2 + Vite + React + TypeScript を用いて、ChatGPTと一緒に食事管理アプリ（Meal Tracker）を Sprint 形式 で構築・検証した記録をまとめます。

2. 検証のゴールと評価観点

以下の 5 点を、机上ではなく 実装ベース で検証しました。

  • スマホ対応を前提にレスポンシブ UI を作れるか
  • DevSecOps 文脈でテストを同時に作れるか
  • Amplify Gen2（同一リポジトリ内 backend / CDK）と整合した構成を保てるか
  • 初見の人が理解できる 仕様書・README を作れるか
  • Atomic Design をどこまで守り、再利用性を維持できるか

3. 技術スタック

フロントエンド

  • Vite
  • React
  • TypeScript

テスト

  • Node.js 標準 node:test

バックエンド

  • AWS Amplify Gen2（同一リポジトリ内で管理）

AI / 開発支援

  • Codex（VS Code 拡張）
  • AGENT.md（日本語で定義）

4. AGENT.md とは何か（なぜ必要か）

AGENT.md は AI に対する「プロジェクト憲法」 として使いました。

主なルール

  • 不要な npm 依存を追加しない
  • UI / 仕様を勝手に変更しない
  • ロジックは src/lib に集約する
  • 機能追加時は docs / README を必ず更新する
  • テストを追加したら npm test が実行可能な状態にする

ポイント

「お願い」ではなく、
禁止事項・必須条件を明文化することで、AI の暴走を防げた のが最大の効果でした。

5. Sprint 1：初期構築の検証

5.1 目的

  • Atomic Design の骨格を作れるか
  • モバイルファーストな UI を維持できるか
  • docs / README が同時に作られるか

5.2 実装内容

  • Atomic Design 構成

    • atoms / molecules / organisms / pages

  • モバイル縦並び → デスクトップ 2 カラム

  • docs

    • overview
    • requirements
    • architecture

  • README

  • プロンプト

目的:
- 食事管理アプリ（Meal Tracker）の初期構築を行う（Vite + React + TypeScript）
- Atomic Design の骨格と docs 雛形を作る
- モバイルファーストで最低限レスポンシブなベースUIを作る

制約:
- AGENT.md を必ず遵守
- 新規npm依存を追加しない（必要なら追加はせず、提案だけする）
- CSSフレームワーク導入など大きな方針変更はしない
- 既存のテンプレートコードの削除・大改造は最小限

作業範囲:
- src/components/{atoms,molecules,organisms,pages}
- src/styles/globals.css
- src/lib/env.ts（雛形だけでOK）
- src/app/App.tsx もしくは src/App.tsx（既存構成に合わせる）
- docs/{overview,requirements,architecture}.md
- README.md

要件:
1) 画面
- Homeページ（Meal Trackerのトップ）を作る
- フォームの見た目だけ先に作る（入力はまだ保存しなくて良い）
  - 料理名（テキスト）
  - カロリー（数値）
  - メモ（テキスト/textarea）
  - 追加ボタン
- フォームはスマホ幅（320px）で崩れない縦並び
- 画面幅が広い場合は、フォームと「ダミーの一覧エリア（カード表示の枠だけ）」が2カラムになる

2) Atomic Design
- atoms: Button, Input, Textarea（必要ならLabelも）
- molecules: FormField（label + input + helper/error領域）
- organisms: MealForm（フォームをまとめる）
- pages: HomePage（ページとして組み立てる）

3) CSS（最小）
- globals.css に最小限の共通スタイル（フォント/余白/フォーム部品）
- レスポンシブはメディアクエリ1つでOK

4) docs
- docs/overview.md: アプリ概要（何ができるか、画面構成）
- docs/requirements.md: 要件/非要件（MVP範囲）
- docs/architecture.md: フォルダ構成（Atomic + lib）と、将来 localStorage→Amplify backend移行方針を1段落で

5) README
- 目的、ローカル起動手順、主要ディレクトリ説明を簡潔に書く

出力:
- 追加/変更したファイル一覧と役割を短く説明
- 依存追加が必要だと思った場合は「提案」だけ書く（実行はしない）

5.3 結果と学び

  • ✅ ファイル構成・UI・Atomic Design は想定通り
  • ⚠️ docs は作られたが、後続 Sprint で更新されない兆候あり

対応策
→ 「機能追加時は docs / README 更新必須」を AGENT.md に追加。

6. Sprint 2：保存・ドメイン・テストの検証

6.1 目的

  • localStorage 保存を実装できるか
  • ロジックを UI から分離できるか
  • テストを同時に生成できるか

6.2 実装内容

  • domain

    • バリデーション
    • 日別カロリー集計

  • storage

    • MealRepository interface
    • localStorage 実装

  • tests

    • domain / repository のユニットテスト

  • プロンプト

目的:
- Meal Tracker のMVPとして「保存（localStorage）→一覧表示→日別合計」を実装する
- 併せてユニットテストを作成する（DevSecOpsの検証）

制約:
- AGENT.mdを必ず遵守
- 新規npm依存を追加しない（必要なら提案に留める）
- Atomic Designを維持する（pagesは組み立て、ロジックはlibへ）
- 既存のUIデザインは大きく変えない（必要最小限の表示追加のみ）

対象:
- src/lib/domain（型・バリデーション・集計）
- src/lib/storage（保存境界：interface + localStorage実装）
- src/components/organisms（MealFormのsubmit処理など最小結線）
- src/components/organisms（MealListなど必要なら追加）
- tests/unit（既存のテスト配置方針に従う）

要件:
- データ: MealRecord { id, eatenAt(ISO日付), name, calories, note? }
- バリデーション: name必須、caloriesは正の整数
- 保存: MealRepository interface を定義し、LocalStorageMealRepository を実装
- 取得: eatenAtの日付で並べ替えて表示（新しい順）
- 集計: 日別合計カロリーを計算する関数を用意して画面に表示
- テスト: バリデーション、集計、Repository（保存→取得）のユニットテストを追加

出力:
- 追加/変更したファイル一覧と役割
- テストが保証する内容を短く説明
- 依存追加が必要だと思った場合は提案のみ（実行しない）

6.3 問題①：npm test が動かない

原因

  • Node 標準 node:test を使用していたが
  • package.json に test script が無かった

対処

{
  "scripts": {
    "test": "node --test"
  }
}

学び

コードが正しくても「運用入口」が無いと DevSecOps 的には失敗

7. Sprint 3：Amplify Gen2 と差し替え設計の検証

7.1 目的

  • Backend を同一リポジトリ内に置けるか
  • フロントを壊さず差し替え入口を作れるか
  • 設計・資料が破綻しないか

7.2 実装内容

  • createMealRepository()

  • VITE_MEAL_REPOSITORY で切り替え

  • デフォルトは localStorage

  • backend はスタブ

  • docs 更新

    • 差し替えキー
    • 移行方針
    • CLI 手順案

  • README 更新

    • MVP 範囲
    • テスト実行方法
    • ロードマップ

  • プロンプト

目的:
- Amplify Gen2 のバックエンド雛形を amplify/ 配下に追加し、将来 localStorage から移行できる構造を作る
- フロントは壊さず、MealRepository の差し替え入口を追加する
- DevSecOps観点で、差し替え入口のテストと docs 更新も行う

制約:
- AGENT.md を必ず遵守
- 新規npm依存は追加しない（必要なら提案に留める）
- 既存のUI/挙動は変更しない（デフォルトは localStorage のまま）
- Atomic Design 配下（components）は原則触らない（必要なら最小）

作業範囲:
- amplify/ 配下（Amplify Gen2 backend の定義）
- src/lib/storage（Repository差し替え入口の追加）
- src/lib/env.ts（必要なら VITE_* の読み取り補助）
- tests/unit（差し替え入口のテスト）
- docs/architecture.md、docs/requirements.md、docs/overview.md、README.md（更新必須）

要件:
1) Amplify Gen2 backend
- amplify/ 配下に MealRecord 相当のデータモデル（id, eatenAt, name, calories, note）を定義する雛形を追加
- 具体的なCLI実行手順が必要なら docs に「手順案」として記載する（この場でCLIを実行はしない）

2) Repository差し替え入口
- MealRepository interface は維持する
- createMealRepository() を追加し、import.meta.env.VITE_MEAL_REPOSITORY が "backend" の場合のみ BackendMealRepository を返す
- VITE_MEAL_REPOSITORY 未設定の場合は LocalStorageMealRepository を返す（現状維持）
- BackendMealRepository は現時点ではスタブ実装でよい（例: 未実装エラー or ダミー）。ただしUIからは呼ばれないようにする（デフォルトLocal）

3) テスト
- createMealRepository() が未設定時に LocalStorageMealRepository を返すこと
- "backend" 指定時に BackendMealRepository を返すこと
- 既存の node:test 方針を維持し、npm test で実行可能にする（scriptsの整備も含む）

4) docs / README（更新必須）
- docs/architecture.md: local→Amplify移行方針、Repository差し替え点、環境変数（VITE_MEAL_REPOSITORY）を追記
- docs/requirements.md / overview.md: 現状の保存方式（localStorage）と将来移行前提を整理
- README: 現状のMVP範囲、テスト実行方法（npm test）、次にやること（ロードマップ）を追記

出力:
- 追加/変更したファイル一覧と役割
- 依存追加が必要だと思った場合は提案のみ（実行しない）

8. Sprint 3 時点での総合評価

観点 評価
レスポンシブ ✅
Atomic Design ✅
テスト同時作成 ✅
Docs / README ✅
Amplify Gen2 整合 🟨（設計は合格、実体は次 Sprint）

9. 検証から得られた知見まとめ

Codex は「設計があると強い」

  • AGENT.md があると暴走しない
  • 無いと依存追加・過剰リファクタが起きやすい

AI は「運用入口」を作らない

  • npm test
  • CI
  • README の実行手順

→ 必須として明示しないと抜ける

ドキュメントは「完了条件」に含める

  • 「更新する」では弱い
  • 「更新されていること」を完了条件にする

Amplify Gen2 は差し替え設計と相性が良い

  • Repository パターンが有効
  • スタブ → 本実装への移行が安全

10. まとめ

  • AGENT.md は AI 開発における設計ガードレール

  • Sprint 形式で検証すると

    • 失敗が早く
    • 修正が小さく
    • 知見が蓄積される

「AI に全部任せる」のではなく
「AI が守るべきルールを先に作る」ことが重要

参考

今回作成したAGENT.md

# AGENT.md

## 役割
あなたはこのリポジトリのシニアフロントエンド/クラウドエンジニアです。
最小変更・保守性・セキュリティ・テスト容易性・ドキュメント整備を最優先に作業してください。

## 最重要ルール
- 新規npm依存を勝手に追加してはならない（必要なら理由と候補を提案に留める）
- 大規模な方針変更（CSSフレームワーク導入、状態管理導入、アーキ大変更）を勝手に実装してはならない
- 既存ファイルを不必要に書き換えてはならない（差分は最小）
- 変更対象は指示された範囲に限定する

## 技術前提
- Vite + React（TypeScriptを優先）
- 環境変数は import.meta.env を使用し、envアクセスは src/lib/env.ts に集約する
- Amplify Gen2 のバックエンドは amplify/ 配下で管理する（同一リポジトリ）

## セキュリティ/DevSecOps
- シークレット/トークンをハードコードしない
- CIで自動実行される前提（対話入力に依存しない）
- ロジック変更にはテスト（ユニット）を追加/更新する
- テストを追加した場合、npm test で実行できる状態を必ず整える

## Atomic Design
- src/components は atoms/molecules/organisms/pages に従う
- 再利用可能なUIは atoms/molecules に切り出す

## ドキュメント
- docs/ に概要・要件・構成を追加/更新し、初見でも把握できる状態にする
- documentは日本語で記述する
- 機能追加/仕様変更を行った場合、docs/ と README の該当箇所を必ず更新する（更新できない場合は理由を明記する）

## 出力
- 変更点を短く説明し、追加ファイルの役割を列挙する
0
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?