README強化・トップページとしての改善

[Kewton]

概要

READMEをGitHubのトップページ（ランディングページ）として機能するよう改善する。

背景・課題

• npmからGitHubへの導線が弱い（package.jsonのrepository/homepage/bugs、CLIヘルプにリンク）
• 初見ユーザーが「何ができるか」を1秒で理解しにくい
• Quick Startの視認性、セキュリティ説明、ユースケース例が不足

改善ポイント

必須

1. ファーストビュー改善: キャッチを1本に絞り、30秒デモGIFを配置
2. Quick Startを3ステップに圧縮: install → init → start のコピペ形式
3. バッジ追加: npm version / downloads / license / CI
4. 累積ダウンロード数の表示
5. npmからGitHubへの導線: package.jsonのrepository/homepage/bugs設定

推奨

6. ターゲット明確化: 「こんな人向け」チェックリスト
7. 仕組みの1枚図: Browser ↔ CommandMate Server ↔ tmux ↔ Claude Code
8. 具体的ユースケース3つ: 通勤中 / 育児の合間 / 週末個人開発
9. セキュリティ説明整理: ローカル完結の要点、推奨構成、NG例
10. Troubleshooting: tmuxセッション直接確認方法を追加
11. FAQ強化: 詰まりどころトップ3を前面に
12. Status / Roadmap: 成熟度宣言と次の3項目

関連

• 統合元: README強化 #244（README強化）

受入条件

• ファーストビューで「何ができるか」が1秒で伝わる
• Quick Startがコピペ3ステップで完結する
• バッジ（version/downloads/license/CI）が表示されている
• npmパッケージからGitHubリポジトリへの導線がある

[Kewton]

インタビュー結果 — 実装方針の決定事項

Issue記載の10ポイント改善提案 + 改稿ドラフトについて、以下の方針で確定しました。

---

基本方針

項目	決定事項
言語戦略	現状維持（README.md=英語、docs/ja/README.md=日本語、両方を改善）
改稿アプローチ	10ポイントをガイドに、現READMEの構成をベースとした独自構成（ドラフトそのままではない）
デモGIF	プレースホルダーコメントのみ（GIF作成自体は別タスク）
ステータス宣言	Beta
Roadmap	載せない
アーキテクチャ図	Mermaid形式（GitHub直接レンダリング）
スクリーンショット配置	トップに1枚（デスクトップ） + 機能紹介セクションに残りを配置

---

10ポイントの具体方針

1. ファーストビュー — キャッチを1本に絞り、3つの箇条書きベネフィット + CTA（npm install / Quick Startリンク）
2. ターゲット明確化 — 「こんな人向け」チェックリスト + 「向かない人」1行追加
3. Quick Start圧縮 — コピペ3ステップに簡略化、詳細はリンクへ
4. アーキテクチャ図 — Mermaidで Browser ↔ CommandMate Server ↔ tmux sessions ↔ Claude Code の構造を可視化
5. セキュリティ — ローカル完結の要点3行 + 推奨構成/NG構成を簡潔に
6. 差別化 — 「何が独自か」（Prompt待ち検知 + 返信UI + worktree整理）を太字で明記
7. ユースケース — 3つの具体例（通勤中、育児の合間、並列開発）
8. FAQ/Troubleshooting — 詰まりどころTop3をQuick Start直後にミニ枠で配置
9. ステータス — Beta宣言のみ（Roadmapセクションは設けない）
10. 見栄え — バッジ追加（npm version, license, CI ci-pr.yml）、目次追加

---

スコープ外（今回対応しない）

• デモGIFの撮影・作成
• Roadmapセクション
• 日英バイリンガル併記（1ファイル内）

[Kewton]

作業計画

Issue #286の作業計画を策定しました。

📋 計画概要

サイズ: M
見積もり工数: 3.5-6時間
対象ファイル: README.md, docs/ja/README.md

---

🎯 Phase 1: 英語版README改善

Task 1.1: ファーストビュー改善

• デモGIFプレースホルダー追加
• キャッチコピー1本化
• 3つの箇条書きベネフィット
• CTA明確化（npm install + Quick Startリンク）
• トップにスクリーンショット1枚配置

Task 1.2: ターゲット明確化 + 差別化

• 「こんな人向け」チェックリスト
• 「向かない人」1行追加
• 独自性を太字で明記（Prompt待ち検知 + 返信UI + worktree整理）

Task 1.3: Quick Start圧縮 + Troubleshooting

• 3ステップに圧縮（install / init / start）
• 詰まりどころTop3配置（CLIパス/ポート競合/tmux直接確認）
• tmuxセッション命名規則と確認コマンド追加

Task 1.4: アーキテクチャ図追加

• Mermaid形式で構造可視化
• Browser ↔ Server ↔ tmux ↔ Claude Code

Task 1.5: セキュリティ・ユースケース・FAQ整理

• ローカル完結の要点3行
• 推奨構成（VPN/認証付きリバプロ）とNG構成
• 3つのユースケース（通勤中/育児中/並列開発）

Task 1.6: バッジ・目次・ステータス追加

• npm version/downloads/license/CI（ci-pr.yml）バッジ
• 手動目次
• Status: Beta 宣言（Roadmapなし）

---

🌐 Phase 2: 日本語版README改善

Task 2.1: 日本語版全セクション改善

• Phase 1の全改善を日本語版に反映
• 日本語特有の表現調整
• 画像パス調整

---

✅ Phase 3: 品質確認

Task 3.1: レビュー・整合性確認

• 英日内容一致確認
• リンク切れチェック
• 画像表示確認（altテキスト/サイズ最適化）
• Mermaid図レンダリング確認
• バッジ動作確認

---

📊 タスク依存関係

Task 1.1 → Task 1.2 → Task 1.3 → Task 1.4 → Task 1.5 → Task 1.6
                                                            ↓
                                                        Task 2.1
                                                            ↓
                                                        Task 3.1

---

✅ Definition of Done

• 英語版READMEに11ポイント全て反映
• 日本語版READMEに11ポイント全て反映
• 全リンク有効、全画像表示、altテキスト設定
• Mermaid図が正しくレンダリング
• 全バッジ動作
• CI（lint）パス
• コードレビュー承認

---

詳細は dev-reports/issue/286/work-plan.md を参照。

次のステップ: ブランチ feature/286-readme-improvement を作成して実装開始。