🧠

どうせドキュメント腐っちゃうので、オンデマンドで作成するような仕組みを考えてみた

2025/10/14に公開

ドキュメントがないのはつらい。でもメンテしたくない。その両立を、LLMと要件マッピングの仕組みで実現するアイデアです。

ここで紹介するのは、「仕様書を保存しないドキュメント設計」。

情報をマッピング1枚に集約し、LLMで必要なときにだけ仕様を再構成します。
GitHub Repository: https://github.com/emrum01/llm-spec-generator

 💡 背景プロジェクトが成長すると、要件・仕様・テストの整合がすぐ崩れます。

WikiやNotionを整えても、数ヶ月後には陳腐化。

仕様書を保管し続けること自体がメンテナンスコストになります。
それならいっそ、仕様書を持たないという選択肢を。

必要な情報だけを1つのマッピングで管理し、

LLMに「仕様書の材料をオンデマンドで取得」させるのです。

 🗂 全体構成（極小）llm-spec-generator/
├── src/                          # Next.js アプリケーション
│   ├── app/phoenix-feed/         # フィード画面
│   ├── components/               # React コンポーネント
│   └── types/                    # TypeScript型定義
├── specs/
│   ├── registry.md               # 要件・テストのマッピング（唯一のソース）
│   └── templates/
│       ├── screen-spec.md        # 画面仕様出力テンプレート
│       └── api-spec.md           # API仕様出力テンプレート
├── tests/
│   ├── e2e/phoenix-feed.spec.ts  # E2Eテスト（@req コメント付き）
│   └── unit/                     # ユニットテスト
└── .claude/                      # Claude Code設定
    └── commands/                 # LLM仕様生成コマンド
この構成では保存される仕様書はありません。

LLMが毎回、registry.mdから最新の要件情報を読み取り、テンプレートに従って仕様を動的生成します。

 📘 要件マッピング（registry.md）下記のようなテーブルを用意してAIがテストと要件の対応を把握できるようにした


タグ
要件ファイル
要件ID
テストファイル


phoenix-feed
requirements/phoenix-feed.md
REQ-PF-001
tests/e2e/phoenix-feed.spec.ts

phoenix-feed
requirements/phoenix-feed.md
REQ-PF-002


stardust-inbox
requirements/stardust-inbox.md
REQ-SI-010
tests/unit/stardust-inbox.test.tsx

### 要件本文（抜粋）
#### requirements/phoenix-feed.md
- **REQ-PF-001**: フィード画面は最新20件のホロカードを時系列降順で表示しなければならない
- **REQ-PF-002**: ネットワーク遅延時はプレースホルダー骨組み表示を行わなければならない

#### requirements/stardust-inbox.md
- **REQ-SI-010**: インボックス画面は未読メッセージを優先的に上部に表示しなければならない
このファイルが"唯一の正"。

LLMはここからタグ・要件ID・要件文・関連テストを抽出し、仕様テンプレートを埋めます。

 🧩 テンプレート（仕様書の型）
 /specs/templates/screen-spec.md
## 画面名: {{screen_name}}
- 対応要件ID: {{req_ids}}
- 状態: draft | ready

### 1. 目的
- {{why}}

### 2. 画面構造
- コンポーネント: {{components}}
- 状態管理: {{state_management}}
- レイアウト: {{breakpoints}}

### 3. 振る舞い（Given-When-Then）
- {{behaviors}}

### 4. 入力検証・文言
- {{validation_rules}}

### 5. A11y/Perf
- {{accessibility}}
- {{performance}}

### 6. テスト観点
- Unit: {{unit_tests}}
- E2E: {{e2e_tests}}
LLMはこの構造を守って出力するため、

チーム全員が同じフォーマットで仕様を共有できます。

 🧠 LLMへの依頼（Claude Code統合）
 カスタムコマンド例# Claude Code内で実行
/create-screen-spec phoenix-feedに関係する画面仕様書を作って

 プロンプト本体https://github.com/emrum01/llm-spec-generator/blob/cee26799833de9adeb739a1f407be50f1fcc4e93/.claude/commands/create-screen-spec.md

 ⚙️ 実行の流れ
registry.md に要件を追加
LLMに create-screen-spec でリクエスト
LLMがテンプレートを埋めた仕様を出力
出力は保存せず、必要に応じて共有（PRやSlackなど）
"保存しない設計"により、

常に最新の要件・テスト構成をもとにした仕様を得られます。

 🧪 出力例：画面仕様書## 画面名: phoenix-feed
- 対応要件ID: REQ-PF-001, REQ-PF-002
- 状態: ready

### 1. 目的
- 最新20件のホロカードを時系列降順で表示し、ユーザーがフィードを閲覧できるようにする
- ネットワーク遅延時でもスムーズなユーザー体験を提供する

### 2. 画面構造
- コンポーネント: HoloCard, SkeletonCard, FeedGrid, LoadMore/Pagination
- 状態管理: useState/useEffect (カード一覧、ローディング状態、エラー状態)
- レイアウト: Desktop (3列)、Tablet (2列)、Mobile (1列) のレスポンシブグリッド

### 3. 振る舞い（Given-When-Then）
- **Given** ユーザーがフィード画面にアクセスする
  **When** 画面が読み込まれる
  **Then** 最新20件のホロカードが時系列降順で表示される

- **Given** ネットワーク遅延が発生している
  **When** データ取得に時間がかかる
  **Then** 1秒以内にスケルトンローダーが表示され、20件のプレースホルダーが表示される

- **Given** ユーザーがスクロールやクリック操作を行う
  **When** ローディング中である
  **Then** 操作が正常に機能する（レスポンシブな操作性を維持）

### 4. 入力検証・文言
- エラーメッセージ: "フィードの読み込みに失敗しました。再度お試しください。"
- ローディング中のアクセシビリティテキスト: "フィードを読み込んでいます..."
- 空状態: "表示するホロカードがありません"

### 5. A11y/Perf
- **アクセシビリティ**:
  - スクリーンリーダー対応（適切なaria-label、role属性）
  - キーボードナビゲーション対応
  - ローディング状態の音声読み上げ対応
- **パフォーマンス**:
  - 初期表示1秒以内
  - スケルトンローダー表示1秒以内
  - 無限スクロール時の仮想化対応

### 6. テスト観点
- **Unit**: HoloCardコンポーネントの表示、SkeletonCardのアニメーション、データソート機能
- **E2E**:
  - 最新20件の表示確認
  - 時系列降順ソートの確認
  - レスポンシブ表示（3列→2列→1列）
  - スケルトンローダーの表示タイミング（1秒以内）
  - ローディング中の操作性確認
  - データ取得完了後のスムーズな切り替え

 🧾 運用ルール

目的
操作


要件の追加
registry.md に追記

仕様の取得

create-screen-spec or 手動プロンプト

テスト紐づけ
テーブルのテスト列を編集

ドキュメント更新
LLMが再生成、保存しない

編集するのは registry.md のみ。

情報が古くなることはありません。

 ✅ メリット
ドキュメントを持たないことで整合性が崩れない

材料（マッピング）だけを永続化するので更新が軽い

LLMの整形能力を最大限活用して出力形式を自在に変更可能
チームの誰でも create-screen-spec で即座に仕様を取得できる

要件ベーステストにより完全なトレーサビリティを実現

 🧭 まとめこの仕組みの本質は「仕様を保存しない」こと。

保存せず、必要なときに再構成できる環境を持つことで、

ドキュメントの陳腐化や管理負担を根本的に排除します。
永続化するのは「要件のマッピング」だけ。

仕様は動的に生成される表現であり、

LLMがいつでも最新状態から再構成できるようにする。
これが、ドキュメントを持たない開発運用の最小単位です。

 🚀 今すぐ試すgit clone https://github.com/emrum01/llm-spec-generator.git
cd llm-spec-generator
pnpm install

# Claude Codeで以下を実行
/create-screen-spec phoenix-feed REQ-PF-001
Repository: https://github.com/emrum01/llm-spec-generator
実際の動作確認や詳細な実装については、GitHubリポジトリをご覧ください。

タグ	要件ファイル	要件ID	テストファイル
phoenix-feed	requirements/phoenix-feed.md	REQ-PF-001	tests/e2e/phoenix-feed.spec.ts
phoenix-feed	requirements/phoenix-feed.md	REQ-PF-002
stardust-inbox	requirements/stardust-inbox.md	REQ-SI-010	tests/unit/stardust-inbox.test.tsx

目的	操作
要件の追加	registry.md に追記
仕様の取得	`create-screen-spec` or 手動プロンプト
テスト紐づけ	テーブルのテスト列を編集
ドキュメント更新	LLMが再生成、保存しない

GitHubで編集を提案

どうせドキュメント腐っちゃうので、オンデマンドで作成するような仕組みを考えてみた

💡 背景

🗂 全体構成（極小）

📘 要件マッピング（registry.md）

🧩 テンプレート（仕様書の型）

`/specs/templates/screen-spec.md`

🧠 LLMへの依頼（Claude Code統合）

カスタムコマンド例

プロンプト本体

⚙️ 実行の流れ

🧪 出力例：画面仕様書

🧾 運用ルール

✅ メリット

🧭 まとめ

🚀 今すぐ試す

Discussion