本ドキュメントは、要件定義・設計書を日本語Markdownで統一して書くための 事前準備用ガイドである。
今後の方針として、
- 要件定義書・仕様書・設計書はMarkdownで作成する
- Gitで管理する
- AIレビュー・AI生成を前提とする
ことを目的とする。
- Visual Studio Code
- 日本語表示が有効になっていること
- Gitが利用できること
日本語化
- 拡張機能検索で
Japanese Language Pack - 発行者：Microsoft
Gitのインストール
- Git公式サイトよりインストール
- 「PATHに追加する」を選択
Markdownを書く・読むために 全員が入れる拡張機能。
Markdown編集を補助する基本拡張で以下に対応。
- 見出し・箇条書きの入力補助
- 目次（TOC）の自動生成
- 見出し構造の整理
インストール
- 拡張機能検索で
Markdown All in One - 発行者：Yu Zhang
Markdownを 読みやすく表示するための拡張。
できること
- 日本語が崩れにくいプレビュー
- 表・箇条書きが綺麗に表示される
- 将来的にPDF出力も可能
インストール
- 拡張機能検索で
Markdown Preview Enhanced - 発行者：Yiyi Wang
システム構成図・アーキテクチャ図を作るための拡張。
用途
- システム構成図
- コンポーネント関係図
インストール
- 拡張機能検索で
Draw.io Integration (diagrams.net) - 発行者：Henning Dieterichs
日本語文章を書くときの操作性を改善する拡張。
用途
- 日本語として自然なカーソル移動
- 削除・選択操作がしやすくなる
インストール
- 拡張機能検索で
Japanese Word Handler - 発行者：Suguru Yamamoto
Codexを利用するための拡張。
用途
- ｘｘｘ
インストール
- 拡張機能検索で
Codex - OpenAI's coding agent - 発行者：OpenAI
Markdownファイルを開いた状態で：
- Windows：Ctrl + Shift + V
- Mac：Cmd + Shift + V
右側にプレビューが表示されればOK。
以下は 全員共通で設定することを推奨。
- 設定画面を開く
- 右上の「settings.json を開く」を選択
- 以下を追記する
{
"editor.wordWrap": "on",
"editor.wordWrapColumn": 1,
"markdown-preview-enhanced.previewTheme": "github-light.css",
"markdown-preview-enhanced.fontFamily": "Meiryo, Hiragino Kaku Gothic ProN, Noto Sans JP, sans-serif",
"markdown-preview-enhanced.fontSize": 14,
"markdown-preview-enhanced.lineHeight": 1.8,
"git.enableSmartCommit": true,
"git.autofetch": true,
"git.confirmSync": false
}
※ 行間が広めの方が日本語は読みやすい。
- 見出しで構造を作る
- 文章をダラダラ書かない
悪い例：
- ユーザー管理（登録・編集・削除）
良い例：
- ユーザー登録
- ユーザー編集
- ユーザー削除
- 図：構成・関係性
- 文章：意味・理由・制約
図に説明を書きすぎないこと。
docs フォルダ配下に以下を作成する。
| ファイル名 | 内容 |
|---|---|
00_overview.md |
プロジェクト概要、対象範囲、全体像、用語定義 |
10_requirements.md |
機能要件、非機能要件、制約条件 |
20_system_design.md |
システム構成、データ設計、API設計 |
30_detail_design.md |
詳細機能設計、UI/UX設計、外部連携設計 |
40_implementation.md |
実装方針、開発環境、コーディングルール、ブランチ戦略 |
50_testing.md |
テスト計画、テスト種類、AI活用 |
60_code_review.md |
コードレビュー、品質管理指標 |
70_deployment.md |
デプロイ手順、運用監視、保守・改善 |
80_ai_guidelines.md |
AI生成物管理、ライセンス、学習データ、フィードバックループ |
glossary.md |
用語集 |
architecture.drawio |
システム構成図、概念図（Draw.ioで作成） |
※git configは設定しておく必要があります。
git config --global user.name "m-matsumoto"
git config --global user.email "m-matsumoto@wanbishi.co.jp"
- Git上にリポジトリを作成しておく。
- Git初期化
git init
- コミット
git add .
git commit -m "Initial commit"
- リモートリポジトリを追加
git remote add origin https://github.com/mitsuo-matsumoto/AI-DrivenDevelopment.
- プッシュ
git branch -M main
git push -u origin main
- Markdownは特別な技術ではないため、チャレンジしてみる
- ルールを追加したい場合は管理職・チームリーダーへ相談する
- AI駆動開発に向けた準備として、全員がMarkdownに慣れること
- 要件の抜け漏れが炙り出せる 例： 完了→戻す時 completedAt は？ カテゴリ削除時、紐づくタスクは？ タグ削除時は？ 同名カテゴリは許可？ テストを書こうとすると、 「あれ？これ仕様決めてない」が必ず出ます。 これが一番の価値。
- reducer設計が強くなる テスト観点を作ると、 純粋関数として書く 副作用を分離する 初期化ロジックを整理する 設計が一段綺麗になります。
- AIにコードを書かせる精度が上がる 今あなたはAI駆動開発をやっていますよね。 テスト設計があると： 「この仕様を満たす実装を書いて」 と明確に指示できる。 曖昧な実装にならない。
- README.md（このファイル）
- docs/00_overview.md（概念設計・フロー）
- docs/10_requirements.md（要求事項）
- docs/20_system_design.md（デザイン → Figmaも使うか検討）
- design/figma_export（figmaのデザイン結果）