デルタメモ

AI開発

小さく始めるAIネイティブ開発—設計をdocsに置いてからコードへ

個人・小規模でも、要件と設計を実装リポのdocsに同居させ、ゲートを人間が持ってからエージェントに実装させる進め方。

個人事業や小さなチームでも、「コードを先に書かせてあとから整える」より、エージェントが辿れる文書を先に置く方が事故が減ります。この記事は、実装リポに要件・設計を同居させてからAIに実装させるときの最短セットです。

この記事でわかること

誰向けか

CursorなどのAIエージェントと一緒に、Web／SaaSを小さく始めたい個人・少人数向けです。大規模向けの仕様駆動プロセスをそのまま運ぶ話ではありません。文書体系と人間の確認ポイントを先に揃える、という実務の話です。

コードより先に、辿れる文書体系を置く

エージェントは、チャットの記憶よりリポジトリ内のファイルを繰り返し読みます。要件や設計が別フォルダ・別リポに散っていると、参照が切れやすく、勝手な解釈が増えます。

実務では次のように揃えると迷いにくいです。

置き場役割の例
docs/（実装リポ内）要件・設計・テスト観点・運用の正本
AGENTS.md やrulesやってはいけないこと（削除・本番書き込みなど）
動くモック（別置きでも可）画面感の正。パス参照でつなぐ

番号付きの小さいMarkdown（例: 01_… 02_…）に分けると、コンテキストを一度に食いつぶしにくいです。巨大な一枚物は避けます。

考え方の参考として、設計書・コード・テストを全部AIに書かせて半年間開発してみたよ（NTT DATA Tech） の「ドキュメント駆動」「設計書体系とアーキの対応」が近いです。ツールはCursorでも同じ芯です。

モックだけだと非機能が落ちる

動く画面があると安心ですが、モック段階では次が抜けやすいです。

実装に入る前に、番号付き設計として薄い一枚でもよいので置きます。「あとで足す」だと、エージェントはモック中心のまま進みがちです。決済の実キーが無くても、チェックリストだけ先に分離しておく進め方もあります。

詳細設計で処理を小説にしない

詳細設計にフローを一文ずつ書くと、コードと1:1対応を狙いたくなります。個人開発ではメンテコストが高く、エージェントも冗長な手順に引きずられます。

設計に書く芯は次で足ることが多いです。

処理の小説は書かず、実装タスクでは「参照ドキュメント」と「やらないこと」を明示します。

人間がゲートを持つ

設計を人間が一度確認するまで、実装フェーズに進ませない、と文章にしておきます。「だいたい良い」でよく、穴は設計を直してからコードです。

初手の依頼も、長く曖昧な「全部やって」は避けます。例:

参照: docs/…（該当ファイル）
対象: 申込〜ログインのみ
やらない: 実キー投入、本番デプロイ
完了条件: pending の利用者が本機能に入れないこと（サーバ側）

削除・デプロイ・本番相当の書き込みは、都度確認する運用にします。痛い事故が起きたら、そのとき初めてルールを厚くします。最初からプロンプトを何十個も用意する必要はありません。

テスト観点は設計とセット

設計書の切り方を変えたら、テスト観点も合わせて直します。人間が「何を確かめるか」を持ち、手順やコードはエージェントに任せる分担が現実的です。

作業前にAIへ渡す入力

人間向けの長い手順は書きません。次はすべて、作業前に AIに読ませる／貼る文 です。

AI向け：永続ルール（rules / AGENTS.md）

コードより先に、実装リポ内の docs（要件・設計・非機能・テスト観点）を辿れる状態を前提にする。
実装前ゲート（設計確認・やってはいけないこと・完了条件）を越えるまで本実装に入るな。
痛い事故から rules／設計を厚くする。最初から網羅プロンプトは不要。
削除・デプロイ・本番書き込みは確認制。曖昧なら聞いてから動く。

AI向け：この作業の開始時にチャットへ貼る文

実装に入る前に、参照する docs のパス、実装前ゲートの充足、やらないこと、完了条件を先に出せ。ゲート未充足ならコードを書かず、足りない文書だけ列挙せよ。

人間向け

なし。上をAIに渡すだけでよい。

まとめ

小さくAIネイティブに進めるときは、実装リポの docs/ に要件・設計・非機能・テスト観点を置き、人間がゲートを持ってからモジュール単位で依頼します。モックの見た目だけで走らせないことと、詳細設計の小説を書かないことが、個人規模での再発防止になります。

読者チェックリスト

参考リンク