user-journey

User Journey Skill

6つの専門エージェントがチームで議論し、ユーザージャーニーマップを作成する。 ペルソナファイルがあれば自動連携するが、手動入力のみでも動作する独立スキル。

ワークフロー

1. ユーザーからプロダクト情報とターゲットユーザーをヒアリング
2. Agent Team を作成し、6エージェントを並列起動
3. フレームワーク設計 → リサーチ → ジャーニー執筆 → クロス分析
4. ジャーニーマップ + クロス分析 + 開発ロードマップを MD で出力
5. Pencil (.pen) でジャーニーマップを可視化（テーブル + 感情折れ線グラフ）

出力ディレクトリ構成

.claude/user-journey/{YYYY-MM-DD}_{project}/
├── context.md              <- プロダクト情報・ユーザータイプ一覧
├── log.md                  <- 議事録
├── research-data.md        <- タッチポイント・行動パターン調査
├── journeys/
│   ├── journey-01.md       <- ユーザータイプ1のジャーニーマップ
│   ├── journey-02.md
│   └── ...
└── insights/
    ├── cross-analysis.md   <- 全ジャーニー横断分析
    └── dev-roadmap.md      <- 優先度付き開発ロードマップ

Step 1: ヒアリング

以下を確認する（不明ならユーザーに質問）:

• プロダクト概要: 何をするサービス/アプリか、コア機能
• ターゲット市場: 国・地域、言語、年齢層
• ターゲットユーザータイプ: 3〜5タイプを推奨。各タイプの特徴:
  • 名前（ラベル）
  • 年齢層
  • 職業
  • デジタルリテラシー（高/中/低）
  • 主な課題・目標
• 重視するフェーズ: 全フェーズか、特定フェーズを深掘りするか
• 既存のペルソナファイル: あれば自動読み込みする

ペルソナファイル自動検出（オプション）

ペルソナファイルがある場合:

1. Glob で ~/.claude/persona-creation/*/personas/persona-*.md を検索
2. 最新セッション（日付プレフィックス順）を選択
3. 各ペルソナファイルからユーザータイプ情報を抽出
4. ユーザーに確認: 「これらのペルソナをベースにジャーニーを作成しますか？」

Step 2: チーム作成とエージェント起動

TeamCreate で user-journey チームを作成。以下6エージェントを 1つのメッセージで並列に Task ツールで起動する。

name	役割	主な手段
context-manager	コンテキストファイル・議事録の管理	Write/Edit
journey-architect	フレームワーク設計・品質管理	分析
ux-researcher	タッチポイント・行動パターン調査	WebSearch, Write
journey-writer	ジャーニーマップ執筆	Write/Edit
insight-analyst	クロス分析・開発ロードマップ	Write/Edit
journey-visualizer	Pencil (.pen) ビジュアライゼーション	Pencil MCP

各エージェントは agents/ ディレクトリにサブエージェントとして定義済み。

タスク作成

TaskCreate で7つのタスクを作成:

1. context-manager: コンテキストファイルの初期作成
2. journey-architect: フレームワーク設計（addBlockedBy: ["1"]）
3. ux-researcher: タッチポイント・行動パターン調査（addBlockedBy: ["1"]）
4. journey-writer: ジャーニーマップ執筆（addBlockedBy: ["2"]）- フレームワーク確定後すぐに開始。リサーチデータは届き次第取り込む
5. insight-analyst: クロス分析・開発ロードマップ（addBlockedBy: ["4"]）- 全ジャーニー完成後に開始
6. journey-visualizer: Pencil ビジュアライゼーション（addBlockedBy: ["4"]）- 全ジャーニー完成後に開始。テーブル + 感情折れ線グラフを .pen で構築
7. 統合レポート + 最終確定（addBlockedBy: ["1","2","3","4","5","6"]）

起動設定

subagent_type: "context-manager"  # agents/ で定義済み
team_name: "user-journey"
mode: "bypassPermissions"
run_in_background: true

プロンプトに含める情報（全エージェント共通）:

• プロダクト概要、ターゲット市場、ユーザータイプ情報
• ベースディレクトリの絶対パス（⚠️必須）: init.sh が出力する絶対パスをそのまま使う
  • 例: /Users/babashunsuke/Desktop/miravy/.claude/user-journey/2026-02-21_miravy/
  • ⚠️ Write ツールは絶対パスのみ受け付ける。.claude/... のような相対パスは動作しない
• ファイル書き込み注意: 「init.sh はディレクトリのみ作成し、テンプレートファイルは作成しない。全てのファイルはあなたが Write ツールで新規作成する必要がある」と明記する
• ジャーニーファイル命名規則: journey-writer のプロンプトにファイル名を明示する（journey-01.md, journey-02.md, ... のゼロ埋め2桁。journey-1.md 形式は禁止）

Step 3: エージェント間フィードバックループ

フィードバックプロトコル（全エージェント共通ルール）

1. 自分の作業が完了したら即座に関連エージェントへ共有
2. 実質的な内容のある返信のみ送る - ACKメッセージは不要
3. フィードバックを受けたら修正し、変更内容を共有する
4. 待ちすぎない: 2人以上から反応があれば次のフェーズに進んでよい
5. 全成果物は必ずファイルに書き出す - Write → Read → SendMessage の順序厳守

Round 1: フレームワーク設計 + リサーチ（並列進行）

[journey-architect]
  -> 全員に: 5フェーズ×8行のマッピングルール
  -> journey-writer: 「このフレームワークに従って執筆してください」
  -> ux-researcher: 「各ユーザータイプのタッチポイントを調査してください」

[ux-researcher]
  -> journey-writer に: リサーチデータ（ファイル + 要約メッセージ）
  -> journey-architect に: タッチポイント調査結果

[context-manager]
  -> 全員に: context.md, log.md 作成完了通知

Round 2: ジャーニー執筆（並列レビュー）

[journey-writer]
  -> 1体完成ごとに全員に共有
  -> journey-architect: フレームワーク準拠チェック依頼
  -> ux-researcher: リサーチデータ整合性チェック依頼

[journey-architect]
  -> 1体完成ごとにレビュー → journey-writer にフィードバック

[ux-researcher]
  -> タッチポイント整合性を確認 → journey-writer にフィードバック

Round 3: クロス分析 + 開発ロードマップ

[insight-analyst]
  -> 全ジャーニー読み込み → クロス分析 → 開発ロードマップ
  -> チームリーダーに完了報告

[context-manager]
  -> log.md を最終更新

Step 3.5: ファイル書き込み検証（チームリーダー必須）

全エージェントのタスクが completed になった後、最終レポート作成の前にファイル存在を検証する。

user-journey/{date}_{project}/
├── context.md              <- context-manager
├── log.md                  <- context-manager
├── research-data.md        <- ux-researcher
├── journeys/
│   ├── journey-01.md       <- journey-writer（内容があること）
│   ├── journey-02.md
│   └── ...
└── insights/
    ├── cross-analysis.md   <- insight-analyst
    └── dev-roadmap.md      <- insight-analyst

検証手順:

1. Glob で journeys/*.md のファイル数を確認（ユーザータイプ数と一致するか）
2. 各ファイルを Read して、空でないことを確認
3. 不足・空のファイルがあった場合: 該当エージェントに SendMessage で催促、応答なければフォールバック書き込み

Step 4: 最終レポート出力

全ファイルが揃ったら JOURNEY_REPORT.md をプロジェクトルートに出力する。

レポートに含める:

• 作成したジャーニーマップの一覧と概要
• 各ジャーニーの要約（テーブル形式）
• クロス分析のハイライト
• 開発ロードマップの優先度 P0 施策
• 各ファイルへのパスリンク

Step 4.5: Pencil ビジュアライゼーション（journey-visualizer が担当）

Journey Map の Markdown データを Pencil (.pen) ファイルで可視化する。 journey-visualizer エージェントが全ジャーニー完成後に自動で .pen ファイルを構築する。

構成要素

1. テーブルレイアウト: ラベル列（160px）+ フェーズ5列（各288px）
2. 感情折れ線グラフ: 各ユーザータイプの感情スコア（-2〜+3）を折れ線でつなぎ、データポイントと感情ラベルを表示
3. セクション間スペーシング: ユーザータイプ間に 24px のスペーサーフレームを挿入して視認性を確保

デザイン仕様

詳細は references/pen-design-spec.md に記載:

• フレーム構成・サイズ計算式
• フォントサイズガイドライン（セル内本文は fontSize 10 が標準）
• テキスト切れ防止ルール（264px 利用可能幅 → 日本語最大22文字）
• カラーパレット（フェーズ色、感情スコア色、行タイプ色）
• 感情折れ線グラフ座標計算
• セクション間スペーシング仕様

テキスト切れ防止ルール（必須・全エージェント共通）

Pencil でテーブルを作成する際:

• セル内本文 fontSize は 10 を標準（12 ではテキスト切れが頻発）
• テキスト利用可能幅 = 288 - (12 × 2) = 264px → 日本語最大約22文字
• 超える場合: fontSize 9 に下げるか、テキストを短縮

Pencil 品質チェック（必須）

1. snapshot_layout(problemsOnly: true, maxDepth: 10)
2. "No layout problems." → 合格 → get_screenshot で目視確認
3. 問題あり → 修正ループ:
   - テキストノード → fontSize を 1pt 下げる（最小 9pt）
   - フレームノード → 親フレームの width を拡大
   - 再度 snapshot_layout → 問題なくなるまでループ

Step 5: クリーンアップ

1. 全エージェントに shutdown_request を送信
2. 全員シャットダウン後に TeamDelete でチーム削除

---

Shell Scripts リファレンス

init.sh - プロジェクト初期化

bash scripts/init.sh <project-name>

# 例
bash scripts/init.sh miravy
# -> .claude/user-journey/2026-02-21_miravy/ を作成（カレントディレクトリ直下）