個人開発の話です — 職場のプロジェクト・開発手法の話ではありません

生成AIを活用した開発いまこんなやり方を
試してます

現段階での試行錯誤の共有です。「こういうやり方はどうかな」と思っていることを話します。
※ 題材は私の個人開発プロジェクトです

個人開発 / personal projectgithub.com/greenwakame/ai-first-rebuild-lab1 / 13

前提30秒だけ背景の話

これは、私が個人でやっている開発の話です。職場で実施している開発手法ではありません。「個人でここまで試してみた」という共有です。

題材個人で関わっているワークショップの教材（業務システム）が老朽化したので、作り直しています。今日はこのプロジェクト自体の話はしません。

やり方実装は AI コーディングエージェント（Claude Code / Codex）に任せる前提でプロセスを組んでいます。今日はこの「進め方」の話をします。

全部公開しています設計判断・AIへの指示書・進め方のドキュメントは public リポジトリで公開中。github.com/greenwakame/
ai-first-rebuild-lab

NOTEコード本体は含まれていませんが、「どう進めているか」の実物ドキュメントはすべて読めます。

個人開発 / personal projectai-first-rebuild-lab2 / 13

課題AIに実装させてみて、困ったこと

AIに実装を任せると、3つの困りごとに当たる

困りごと ①

差分の良し悪しを
判断する基準がない

AIはそれっぽいコードを大量に出してくる。でも「これで完成」かどうかを判定する物差しを、こちらが持っていない。

「動いてるっぽいからマージ」していませんか

困りごと ②

AIが仕様の方を
書き換えて辻褄を合わせる

テストが通らないとき、コードを直すのではなく、テストや仕様の方を修正して「解決」してしまうことがある。

気づかないと、仕様がコードに従属し始める

困りごと ③

AIは自分の書いたUIを
一度も見ていない

レイアウト崩れもコントラスト不足も、AI自身には見えない。人間が起動して見るまで、誰も気づかない。

視覚の確認が全部人間に返ってくる

この3つに、仕組みで答えを作ってみた — というのが今日の話です

個人開発 / personal projectai-first-rebuild-lab3 / 13

考え方前提になる発想の転換

人の役割が「書くこと」から「検証すること」へ移る

設計書を書く	→	Issue の完了条件を合意する
レビューを受ける	→	レビューを受け、判断を ADR（意思決定記録）に残す
自分で実装する	→	AIエージェントが実装し、人が差分を検証する
動作確認する	→	検証コマンドを通し、確認できなかったことも書く

「設計を先に固める」規律がないままAIに実装させると、
生成された差分を評価する基準がそもそも存在しない。— これが今のところの、いちばん大事な学びです

個人開発 / personal projectai-first-rebuild-lab4 / 13

全体像回している開発ループ

AIが実装し、人が必ず検証するループ

AIエージェントが担う工程人が必ず担う工程「コードが生成されただけでは、タスクは完了していない」

個人開発 / personal projectai-first-rebuild-lab5 / 13

仕組み ①困りごと①「基準がない」への土台づくり

AIへの指示を、1つのファイルに集約するAGENTS.md — single source of instructions

AGENTS.md（1ファイル）

ミッション／触ってよい境界／作業手順／検証基準／レビュー観点を全部ここに。毎回チャットで同じ説明を繰り返さない。Claude Code でも Codex でも同じ指示を読む。

.agents/skills/（繰り返す手順6本）

Issue駆動の実装フロー、PR検査、DBマイグレーション管理、機能移行の計画、セキュリティレビュー、UI検証。

deliver-github-issueinspect-github-prmanage-supabase-migrationplan-replacement-slicereview-sensitive-changeverify-web-slice

# AGENTS.md から実物を抜粋

## Validation expectations
- A task is not complete because code was generated.
- Do not claim a check passed unless it was run
successfully in the current worktree.
- If a required check cannot run, explain the concrete
blocker and leave a reproducible next command.

# 「生成された＝完了」ではない、を指示レベルで固定する

運用ルール同じ修正指示をAIに2回出したら、その内容を AGENTS.md か skill へ昇格させる。指示は書いた分しか効かない。

個人開発 / personal projectai-first-rebuild-lab6 / 13

仕組み ②困りごと②「辻褄合わせ」への答え

仕様とコードのズレを、機械で検出するrequirement traceability & drift detection

仕様（受け入れ条件にID）

- [x] REQ-MEMBER-INTRO-005
自己紹介は有界の
plain textのみ許可

→

台帳 registry.yaml

id: REQ-MEMBER-INTRO-005
status: implemented
spec: docs/features/…

→

実装にマーカー

// @req REQ-MEMBER-INTRO-005
pub fn validate_
introduction(…)

→

テストにも同じマーカー

// @req REQ-MEMBER-INTRO-005
#[test]
fn allows_only_bounded…

$ mise run req:check　← PR前に必ず実行。片方だけ動いた状態を終了コードで検出
仕様だけが変更され、コードが動いていない　→ ERROR　／　実装だけが変更された → WARNING　／　「実装済み」の状態を下げて結果を消す → それ自体を検出

検出ツールに --fix は存在しない。ズレを見つけたAIは整合を取らずに停止し、人へ報告する。整合させる判断は人に残す。

限界も明示同じPRで仕様とコードを同時に書き換えれば検査は通る。検出できるのは「片方だけが動いた」ことであって、意味の一致ではない。

個人開発 / personal projectai-first-rebuild-lab7 / 13

仕組み ③困りごと③「AIはUIを見ていない」への答え

AIに、自分の書いたUIを見せるagent visual self-verification

なぜ19枚しか撮らないかスクリーンショットはAIのコンテキスト予算そのもの。網羅ではなく「判断に必要な最小集合」を画面×条件（幅360〜1920px、reduced motion、エラー状態…）で厳選。

何が変わるか人間のレビューが唯一の視覚検証経路だと、人間が並行度の上限になる。AIが自己修正できると、人は「AIには直せない判断」（情報設計・見た目の仕上げ）に集中できる。

限界も明示機械検査が通っても「アクセシブル」とは限らない。レイアウトの美醜や focus の見やすさは AI がスクショで判断し、最後は人が見る。

個人開発 / personal projectai-first-rebuild-lab8 / 13

規律検証文化のいちばん効くやつ

PRに「確認できなかったこと」を必ず書く

実際のPRの「確認できなかった事項」節（実物からの転記・要約）

「さらに表示」を実際にクリックしたときの挙動 — 手動レビュー環境が対話ターミナル必須のため、AIからは実行できず未確認（ユニットテストでは担保済み）
Tabキー移動時の focus ring の実際の見え方 — DOM順の一致はテスト済みだが、見た目は目視未確認
reduced motion 適用時にアニメーションが実際に止まっているか — 静止画のスクリーンショットでは判定不可

AIに、実行できなかったことを自己申告させないと、誰も気づけない。
だから「できなかったことを書く」をPRの必須項目にする。— 未確認事項が明示されると、レビュアーはそこを重点的に見られる。「全部確認済み」という誤解が消える

個人開発 / personal projectai-first-rebuild-lab9 / 13

実例1つのIssueがマージされるまで（実記録から）

表示改善Issue（7ファイル・+118/−68行）の一周

人

完了条件を「数値」で合意する

「きれいに整列」ではなく「1280 / 1440 / 1920px でラベル上辺が揃う」。後から誰でも判定できる形にしてから着手。

人

安易な回避策を着手前に禁止する

「invisible spacer・absolute配置・負margin で位置を合わせない」と Issue に明記。実装者（人でもAIでも）が楽な手段に流れる道を先に塞ぐ。

エージェントが実装（テストと文書も同じPRで）

コンポーネント3つ全部にテスト追加。設計ドキュメントの基準値も同時に更新。コードと文書の食い違いを残さない。

人

差分を読む → 検証コマンド → スクショ確認

mise run check（テスト189件+ビルド）、スクショ19枚+axe-core 違反0件。アバター直径は画像から実測。

人

未確認事項3点を明記したPR → レビュー → マージ

前ページの「確認できなかった事項」はこのPRの実物。

個人開発 / personal projectai-first-rebuild-lab10 / 13

まとめ個人開発で試して「効いている」と感じる3つ

もし使えそうなら、この3つから試せます※ 導入提案ではなく、いち個人の感想です

その 1

AIへの共通指示を
1ファイルにまとめる

毎回チャットで説明しない。「生成された＝完了ではない」のような原則を指示として固定する。

その 2

完了条件を「誰でも判定できる形」で
合意してから投げる

数値・状態で書く。これがないと、生成された差分の良し悪しを判断する基準がない。

その 3

PRに「確認できなかったこと」
欄を作る

AI相手だと特に効く。実行できなかったことを自己申告させないと、誰も気づけない。

ここで話したことの実物（AIへの指示書・設計判断23本・Issue実例）はすべて公開しています：
github.com/greenwakame/ai-first-rebuild-lab　おすすめは development-approach.md → issue-walkthrough.md

ご意見・ツッコミ歓迎です。「うちではこうしてる」の話が聞きたいです。

個人開発 / personal projectai-first-rebuild-lab11 / 13

APPENDIX A

補足要求トレーサビリティの詳細（質疑用）

ID体系と、検出できないものの明示

二系列のIDREQ-<領域>-<連番> は仕様の受け入れ条件（変化し続ける→ドリフト検出の対象）。ADR-<番号>-D<n> は設計判断（改訂履歴で追う対象）。性質ごとに分ける。

後退も検出する「実装済み」ステータスを下げる、要求の種別を弱い方へ移す — いずれも検出結果を消せてしまうため、後退そのものを検出対象にする。

逆生成の禁止既存コードから要求を逆生成しない。実装の言い換えは定義上コードと常に一致し、ズレを検出できない。しかも一度IDが付くと、以後のAIセッションはそれを「人が決めた事項」として読む。

段階導入いきなりCIでブロックせず、警告のみで運用を観測してから切り替える。却下した代替案4つもADRに記録してある。

前提この仕組みは「1つのIssueを1つの縦切りに保つ」運用が前提。仕組み単体では成立しない。

個人開発 / personal projectai-first-rebuild-lab12 / 13

APPENDIX B

補足プロジェクト自体について（質疑用）

題材プロジェクトの概要

ワークショップ教材として使ってきた業務システム（メンバー管理ほか）が老朽化したため、Next.js / Rust / Supabase でゼロから作り直しています。すべて合成データのみで開発しており、実在の人物情報は扱いません。

一括リライトではなく縦切り移行旧システムには自動テストがなく、認可も独自モデル。機能単位で「検証可能な最小の縦切り」を作ってはマージする方式。

契約優先API境界は OpenAPI を正としてクライアント型を自動生成、契約とコードの乖離はCIで検出。

公開しているもの設計判断（ADR23本）／AIへの指示書の実物／Issue実例／進め方の文書。コード本体は非公開。

個人開発 / personal projectai-first-rebuild-lab13 / 13

生成AIを活用した開発いまこんなやり方を試してます