LoginSignup
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?

@OneKiloWatt

AI開発の最短ルート：ドキュメント先行で手戻りを約9割削減【実録＆テンプレ公開】

Posted at

"AIに作らせたら早い"は幻想。曖昧なまま投げると質問地獄→手戻り連鎖。先に最小ドキュメントを決めるだけで、会話が具体化して実装が一直線になります。この記事は実在アプリでやった手順・テンプレを全部見せます。

TL;DR

  • AIが書き、人間は決裁だけで0→1を回すには、最小ドキュメントを先に決めるのが最短。
  • コードと同時に"作りながら残す"運用にすると、スピードも再現性も両取りできる。

まず使ってみてください

突然ですが、このアプリを使ってみてください。

あえるまっぷ： https://onekilowatt.github.io/aerumap/

1000001207.png

「今どこ？」のやり取りなしで位置共有できる待ち合わせアプリです。インストール不要、URL共有で簡単に使えます。

このアプリ、実は「ドキュメント駆動開発」で作りました。AIに何をお願いすればいいか分からない方、必見です。

AIに丸投げが地獄な理由（具体例）

「ChatGPTで待ち合わせアプリ作って」と言った場合を想像してください。

AI： 「どんな認証方式ですか？」
私： 「えーっと...」

AI： 「データはどのくらい保持しますか？」
私： 「うーん...」

AI： 「デザインの方向性は？」
私： 「よく分からない...」

結果：

  • AIが作ったものが想像と違う
  • 「ここ違う、あそこ違う」で大幅手戻り
  • 何度も作り直し

これが「AIに丸投げ地獄」の正体です。AIが優秀でも、人間が曖昧だと迷走します。

解決策：ドキュメント先行で手戻り激減

答えは簡単：最初にドキュメントで方針を固める

ドキュメント駆動開発のサイクル

1. ドキュメント作成（AIと一緒に）
2. ドキュメントに基づいて実装（AIが担当）
3. 仕様変更があればドキュメント更新（AIと一緒に）
4. ドキュメントに基づいて修正（AIが担当）

これで：

  • AIとの会話が具体的になる
  • 手戻りがほぼなくなる
  • チーム開発でも迷わない

実例：あえるまっぷのドキュメント構成

実際にあえるまっぷをどう作ったか、ドキュメント構成を見てみましょう。

最小必要ドキュメント

docs/
├── REQUIREMENTS.md    # 要件定義（最重要！）
├── SECURITY.md       # セキュリティ要件
├── DESIGN.md         # UIルール
├── API/              # API仕様
├── DATA_STRUCTURES.md # DB設計
└── PAGES/            # 各画面仕様（複雑なUIがある画面のみ）

実際のPAGES/ROOM.md（ルーム参加ページ仕様）の一部

👀 実際のファイルを見てみる

ここまで詳細に仕様化します：

トースト通知の設計

分類 表示位置 表示時間 内容例
🟥 エラー系 画面上部 常駐（手動で閉じる） 位置情報取得失敗・参加失敗など
🟩 通知系 画面下部 自動で3〜5秒表示 メッセージ更新・退出完了など

位置情報送信の具体的ルール

条件 内容
最短更新間隔 5秒ごと（それ未満の送信は無視）
最大更新間隔 30秒以内に1回は必ず送信（静止時でも）
位置変化トリガー 前回送信地点から5m以上動いた場合に即送信

2段階確認フロー

STEP1: ニックネーム入力 + アプリ説明
↓
STEP2: 注意喚起モーダル「⚠️ このリンク、ほんとに信用できる？」
（チェックボックス必須）
↓
参加完了

結果：大きな仕様変更はほぼなし（微調整のみ）

1000001204.png

実際のルーム画面。地図上のマーカー表示と、画面下部の「メッセージ更新」トースト通知が仕様書通りに実装されています。

プロンプト実例（実際に使った指示）

ドキュメント作成時は認識合わせから始めるのがコツです。

仕様書作成時の基本プロンプト

これから仕様書を作っていきます。
私とあなたの認識が合ってから書き始めてください。
あなたが仕様書を書くのに足りてない情報があれば、あなたの方から指摘してください。
添付資料の内容を埋めてください。
追加で入れた方がいい内容があれば、積極的に提案してください。

実際の進め方

  1. REQUIREMENTS.md → 上記プロンプト + 要件定義テンプレートを添付
  2. SECURITY.md → 同様に認識合わせ + セキュリティテンプレートを添付
  3. DESIGN.md → 同様に認識合わせ + デザインテンプレートを添付

こうして「テンプレート → 認識合わせ → 完成」の流れで1つずつ確実に作ります。

導入手順（最短ルート）

Step 1: 要件定義から始める（10-30分）

# REQUIREMENTS.md
## 概要
- 何を作るか / 誰のためか / どう使うか

## 機能一覧
- 必須機能 / 任意機能

## 非機能要件
- セキュリティ / パフォーマンス / 制限事項

Step 2: セキュリティ方針を決める

# SECURITY.md
- 認証方式（匿名/リンクベース/トークンなど）
- データ保持期間・削除ポリシー
- アクセス制限・レート制限

Step 3: TOPページのモックHTML作成

デザインのイメージを固めるため、まずは簡単なHTMLモックを作成

  • 色合い・雰囲気を決める
  • ボタン・フォームのスタイル確認
  • レスポンシブの感覚を掴む

Step 4: DESIGN.mdでルール抽出

モックから具体的なデザインルールを抽出・文書化

# DESIGN.md
- カラーパレット（モックで使った色をHEXで明記）
- タイポグラフィ（見出し/本文/小テキスト）
- コンポーネント（ボタン/トースト/モーダル）

Step 5: API・DB設計

# API/rooms.md
GET /rooms/:id
POST /rooms/:id/locations

# DATA_STRUCTURES.md
Room { id, name, createdAt }
Location { memberId, lat, lng, ts }

Step 6: 複雑な画面は個別仕様

# PAGES/ROOM.md（複雑なUIがある画面のみ）
- 2段階確認フロー
- トースト通知の分類
- 位置情報送信ルール

Step 7: 実装開始

ここで初めてAIにコード生成をお願いします。ドキュメントがあるので、AIとの会話が具体的になります。

雛形テンプレート（コピペOK）

すぐに使える雛形を用意しました：

docs/REQUIREMENTS.md 

# 概要
| 項目 | 内容 |
|------|------|
| プロダクト名 | |
| 目的 | |
| 対象ユーザー | |
| 提供形態 | |

# 機能一覧
## 必須機能
- [ ] 
- [ ] 

## 任意機能
- [ ] 
- [ ] 

# 非機能要件
- セキュリティ：
- パフォーマンス：
- 制限事項：

docs/SECURITY.md 

# 認証
- 方式：
- トークン管理：

# データ保持
- 保存範囲：
- 期間：
- 削除ポリシー：

# アクセス制限
- 権限管理：
- レート制限：

docs/PAGES/ （複雑なUIがある画面のみ）

# 画面名.md
## 概要
- パス：
- 主な役割：

## 画面フロー
1. STEP1：
2. STEP2：

## UI仕様
- ボタン配置：
- エラーハンドリング：
- バリデーション：

なぜ最短なのか（メカニズム）

1. 曖昧さの除去

指示が「要件への参照」になるので、会話が具体化

2. 差分で話せる

変更はドキュメント差分で表現でき、漏れが減る

3. 属人化しない

新メンバーもドキュメントを読めば再現できる

4. QAがしやすい

テスト観点がドキュメントから引ける

5. AI時代だからこそのコスパ革命

「小規模でもここまで書く必要があるの？」 ← よくある反論ですが、AI時代では前提が変わりました。

従来（人力）vs 現在（AI支援）

項目 従来 AI時代
ドキュメント作成 数時間〜数日 10-30分
保守・更新 面倒で放置しがち 差分指示で即更新
品質のブレ 人によってバラバラ 一定品質を自動生成

AI時代のドキュメント価値

  • 作成コストが1/10以下になったからこそ、「ちゃんと書く」メリットが爆増
  • 人力では「コスト > 効果」だった小規模案件でも、「効果 >> コスト」に逆転
  • AIとの会話精度が上がるので、ドキュメント投資の回収が早い

結論: 「面倒だから書かない」から「AIが書くから当然書く」時代へ。ドキュメントの価値が再評価されています。

アンチパターン（避けるべき落とし穴）

❌ ドキュメントを書かずに実装開始

「一旦動かす」が後で最も高くつく

❌ ドキュメントを更新しない

仕様が二重化して破綻

❌ 粒度がバラバラ

詳細すぎる/粗すぎる項目が混在

❌ 根拠のないTODO

論点は必ずドキュメントへ昇格

まとめ

「AIが書き、人間は決裁」を成功させるコツは、最初にドキュメントで方針を固めることです。

  1. 要件定義を先に書く（AIと一緒に）
  2. 簡単なモックを作る（AIが担当）
  3. 詳細仕様を決める（AIと一緒に）
  4. 実装する（AIが担当）
  5. 変更時はドキュメント更新（AIと一緒に）

実際に動く「あえるまっぷ」が、その効果の証拠です。ぜひ試してみて、開発の詳細はGitHubリポジトリをご覧ください。

リンク

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?