app-docs

アプリドキュメント生成ツール

稼働中のウェブアプリを閲覧し、すべての画面のスクリーンショットを撮影して、公開できる品質のドキュメントを作成します。スクリーンショットを並べるだけではなく、アプリの使い方を伝える、構成の整ったガイドを作成します。

ブラウザツールの検出

ux-audit と同じです — Chrome MCP、Playwright MCP、または playwright-cli を使用します。

URL の解決

ux-audit と同じです — localhost よりも、デプロイ済みの URL／ライブ URL を優先します。

詳細レベル

詳細レベル	スクリーンショット	作成される内容	所要時間
quick	約10枚	1ページのクイックスタートガイド。主要な画面と、問題なく進む基本操作のみ。	10～15分
standard	約30枚	ユーザーガイド全体。すべてのページ、主要なワークフロー、リファレンステーブル。	30～60分
thorough	80枚以上	包括的なガイド。すべての状態、モバイル表示、すべての CRUD 操作、トラブルシューティング。	1～3時間
exhaustive	150枚以上	公開可能なドキュメント一式。thorough の内容に加え、導入チュートリアル、機能ごとの詳細解説、管理者ガイド、キーボードショートカットのリファレンス、FAQ、HTML 版。	3～6時間

デフォルト：standard

ワークフロー

1. アプリの詳細を確認する

ユーザーに次の内容を確認します。

• アプリの URL（必須 — または wrangler.jsonc／実行中の開発サーバーから自動検出）
• アプリ名（ガイドのタイトルに使用）
• 認証 — Chrome MCP はユーザーのセッションを使用します。Playwright では認証情報が必要です
• 詳細レベル — quick、standard、thorough、または exhaustive
• 対象読者 — 誰が読むのか（エンドユーザー、管理者、新しいチームメンバー、クライアント）

2. すべてのルートを確認する

アプリ内を移動して、ページの一覧を作成します。

• サイドバー／ナビゲーションメニューを確認する
• 最上位の項目とサブ項目をすべてクリックして確認する
• サブページ、ページ内のタブ、ネストされたナビゲーションを確認する
• 設定、プロフィール、管理者用エリア、ヘルプページがないか確認する
• 各ページの URL と目的を記録する
• 操作可能な要素（フォーム、ボタン、フィルター）があるページを記録する

ドキュメント作成の進捗を管理するためのタスクリストを作成します。

3. 各ページを記録する

一覧にある各ページについて、次の手順を実施します。

a. ページに移動して準備する

• ページに移動する
• データが読み込まれるまで待つ（スクリーンショットにスケルトン／スピナーが表示されていないこと）
• スクリーンショットの一貫性を保つため、ブラウザーのサイズを 1280x720 に変更する
• 「Test Client」や空のテーブルではなく、現実的なデータがページに表示されていることを確認する

b. 初期状態のスクリーンショットを撮る

• データが表示されたページの鮮明なスクリーンショットを撮る
• わかりやすい名前を付けて docs/screenshots/ に保存する

c. ページのセクションを書く

各ページについて、次の内容を記載します。

## [Page Name]

[One sentence: what this page is for and when you'd use it]

![Page name](screenshots/NN-page-name.png)

### What You'll See
[Describe the key elements: sidebar shows X, main area shows Y, toolbar has Z]

### What You Can Do
[List the actions available, each as a brief description]

### How To: [Primary Action]
1. [Step with screenshot reference]
2. [Step]
3. [Step — screenshot the result]

> **Tip:** [Helpful shortcut or non-obvious feature]

d. 主要なワークフローを記録する

操作可能なページでは、重要な各手順でスクリーンショットを撮り、手順に沿って記録します。

### How To: Add a New Client

1. Click the **"Add Client"** button in the top right
   ![Add button location](screenshots/12-clients-add-button.png)

2. Fill in the required fields — Name and Email are required, everything else is optional
   ![New client form](screenshots/13-clients-new-form.png)

3. Click **"Save"** — you'll be taken to the new client's detail page
   ![Client saved confirmation](screenshots/14-clients-saved.png)

> **Tip:** You can also press **Cmd+N** from anywhere to create a new client.

e. 詳細レベルごとの追加項目

追加項目	quick	standard	thorough	exhaustive
空の状態	省略	注記	スクリーンショット＋説明	スクリーンショット＋改善案
エラー状態	省略	注記	発生させてスクリーンショット	すべての検証エラーを記録
ダークモード	省略	省略	主要ページのスクリーンショット	すべてのページのスクリーンショット
モバイル（375px）	省略	省略	主要ページのスクリーンショット	すべてのページのスクリーンショット
CRUD 全般	省略	主要な操作のみ	すべての操作	エッジケースを含むすべての操作
設定／構成	省略	オプションを一覧化	それぞれ説明	例を含めてそれぞれ説明
キーボードショートカット	省略	表示されている場合は一覧化	完全なリファレンステーブル	専用のセクション
検索／フィルター	省略	言及	各フィルターを説明	すべての組み合わせを記録
権限／ロール	省略	省略	違いを注記	ロールごとに個別のセクション
API／連携	省略	省略	存在する場合は言及	エンドポイントと例を記録

4. 補足セクションを書く

ページごとのドキュメントに加えて、次の内容を作成します。

はじめに（すべての詳細レベル）：

## Getting Started

### Accessing [App Name]
- URL: [production URL]
- Supported browsers: Chrome, Firefox, Safari, Edge
- Mobile: [responsive / PWA / not supported]

### Logging In
[Screenshot of login page + steps]

### Your First 5 Minutes
1. [First thing to do after logging in]
2. [Second thing — the quick win]
3. [Third thing — explore the main feature]

ナビゲーションガイド（standard 以上）：

## Navigation

### Sidebar
[Screenshot with annotations describing each section]

### Quick Actions
- **Cmd+K**: Quick switcher — jump to any page or record
- **Cmd+N**: Create new [item]
[Other shortcuts]

### Breadcrumbs / Back Navigation
[How to navigate back, where breadcrumbs appear]

キーボードショートカットのリファレンス（thorough 以上）：

## Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| Cmd+K | Quick switcher |
| Cmd+N | New [item] |
| Cmd+S | Save |
| Escape | Close dialog / cancel |

トラブルシューティング（thorough 以上）：

## Troubleshooting

### [Error message or symptom]
**What it means**: [explanation]
**How to fix**: [steps]

### Common Questions
[FAQ generated from what would confuse a new user — based on the documentation process itself]

管理者ガイド（exhaustive）：

## Admin Guide

### User Management
[How to invite users, set roles, remove access]

### Settings Reference
| Setting | What it does | Default | Recommendation |
[Every setting documented]

### Data Management
[Export, import, backup, delete account]

5. 出力形式

Markdown（デフォルト）：docs/USER_GUIDE.md

• 相対画像パス：![alt](screenshots/NN-description.png)
• GitHub Flavored Markdown — GitHub、VS Code、Obsidian で表示できます

HTML（網羅的な詳細が必要な場合、またはリクエストがあった場合）：docs/user-guide.html

• Tailwind CDN を使用した、単独で完結する HTML ファイル
• スクリーンショットは相対パスを使用します（ファイルサイズを適切に保つため、base64 は使用しません）
• スムーズスクロールに対応した目次サイドバー
• 印刷に適した CSS（@media print）
• ダークモード対応

スクリーンショットの命名規則：docs/screenshots/NN-section-description.png

• 並べ替え用の番号：01-、02-、03-
• セクションのプレフィックス：01-dashboard-、05-clients-、12-settings-
• 内容がわかるサフィックス：-overview.png、-add-form.png、-saved-confirmation.png

6. モックアップと図

理解に役立つ場合は、スクリーンショットと図を組み合わせます。

ワークフロー図（テキストベース、外部ツール不要）：

### How a Client Moves Through the System

New Enquiry → Create Client → Add Policy → Send Renewal → Archive ↓ ↓ ↓ ↓ ↓ [Email] [Client Page] [Policy Page] [Email Outbox] [Archive]

注釈付きスクリーンショット：スクリーンショットに吹き出しが必要な場合は、本文で説明します。

![Dashboard](screenshots/01-dashboard.png)

The dashboard shows:
- **A** (top left): Your client count and active policies
- **B** (centre): Items needing attention today
- **C** (right): Recent activity feed

UI 要素の参照図：複雑なページでは、ラベル付きの図が役立ちます。

### Editor Layout

| Area | What it does |
|------|-------------|
| Left panel | Folder tree — organise your notes |
| Centre panel | Note list — shows notes in the selected folder |
| Right panel | Editor — write and preview your note |
| Top bar | Navigation, search (Cmd+K), and view toggles |

スクリーンショットの品質

• 解像度：1280x720（デスクトップ）、375x812（モバイル）
• データ：現実的なデータを使用します。「Test」や「Lorem ipsum」は使用しません。実際のアプリの使い方に沿ったデータを使います。
• タイミング：データが読み込まれるまで待ちます。完成版のスクリーンショットにスピナーやスケルトン画面が写らないようにします。
• 状態：データが入力され、関連セクションが展開され、主要な機能が見えるなど、ページを役立つ状態で表示します。
• 一貫性：同じビューポートサイズ、ズームレベル、ブラウザーを一貫して使用します。
• ダークモード：ダークモードについて記載する場合は、スクリーンショットを撮る前に切り替えます。1つのセクションでモードを混在させないでください。

自律性に関するルール

• すぐに実行する：ページを移動し、スクリーンショットを撮り、ページの内容を読み、ドキュメントを作成します。
• 簡潔に確認する：大きなドキュメントファイルを書き込む前に確認します。
• まず確認する：実データを使ってフォームを送信する前、および削除をクリックする前に確認します。
• 徹底的／網羅的なモード：ファイルの書き込みや、テストデータを使ったフォームへの入力では確認を省略します。

品質基準

ドキュメントは、次の条件を満たす必要があります。

1. **新規ユーザーが、ガイドに従うだけでどのタスクも完了できます。**助けを求める必要はありません。
2. **すべてのスクリーンショットに説明があります。**何を見ているのか、何をすればよいのかがわかります。
3. **手順は一つずつ完結しています。**番号付きの各手順は1つの操作だけとし、「XをクリックしてからYとZに入力する」といった手順にはしません。
4. **ヒントで隠れた便利機能を紹介します。**ショートカット、便利な機能、ユーザーが自力では気づきにくいことを説明します。
5. **トラブルシューティングは実際に役立ちます。**仮定上の FAQ ではなく、ドキュメント作成時に実際に遭遇したわかりにくい状況に基づいています。
6. **必要な情報をすばやく見つけられます。**見出し、スクリーンショット、表、ヒントを活用します。ドキュメントを最初から最後まで読む人はいません。必要な情報を探して読むものです。