---
name: diagram-maji
description: 技術ドキュメントを「技術に詳しくない一般の人」向けにわかりやすく図解するスキル。「わかりやすく図解して」「マジ図解して」「図解を作って」と依頼された際に使用します。マジくんとマスターの対話形式で、本気AIブランドに準拠したHTMLを生成し、surge.shにデプロイします。
---

# Diagram Maji

技術ドキュメントを**技術に詳しくない一般の人**でも直感的に理解できるHTMLに変換する。

## 依存

- `docs/design/design-guideline.md` - ブランドカラー、トーン&マナー
- `docs/design/charactor-images/square/512px/` - キャラクター画像
- `contents/docs/方針・キャラ設定/キャラ設定.md` - キャラ設定

---

## ワークフロー

### Phase 0: リサーチ（サブエージェント）

**exploreサブエージェント**を起動して、対象技術を徹底調査する。

```
Task({
  subagent_type: "explore",
  description: "技術ドキュメントの調査",
  prompt: `
    以下の技術について徹底的に調査してください：
    【対象】{URL or トピック名}
    
    調査項目：
    1. この技術は何を解決するものか（Why）
    2. 主要な概念・用語の一覧
    3. 典型的なユースケース3つ以上
    4. 初心者がつまずきやすいポイント
    5. 関連する公式ドキュメントのURL
    
    結果は箇条書きで整理して返してください。
  `
})
```

### Phase 1: ソース読み込み

1. URLなら `WebFetch` で取得
2. ドキュメントなら内容を分析
3. **情報の全体像を把握**（漏れなく）
4. **Phase 0のリサーチ結果と照合**して抜け漏れを確認

### Phase 2: 用語翻訳表を作成

技術用語を洗い出し、やさしい言葉に変換する。

| 技術用語 | やさしい言葉 | たとえ |
|---------|------------|--------|
| コールバック関数 | チェック係 | 「何かあったら呼んでね」と登録しておく処理 |
| フック | 割り込みポイント | 会社のセキュリティゲート |
| API | 窓口 | 銀行の窓口のように、決まった手続きで依頼する場所 |

**詳細** → [references/term-dictionary.md](references/term-dictionary.md)

### Phase 3: たとえ話を3つ以上考える

| 種類 | 例 |
|-----|-----|
| 身近な例 | 会社のセキュリティゲート、郵便配達 |
| デジタルな例 | スマホの権限ダイアログ |
| 視覚的な例 | 信号機、地図、フローチャート |

### Phase 4: 情報を絞り込む

- 「まず覚える3つ」を決定
- 全体の中の位置づけを示す
- 優先度の低い情報は後半に配置

### Phase 5: キャラクター対話を設計

| キャラクター | 役割 | 表情の使い分け |
|------------|------|--------------|
| マジくん | 読者の疑問を代弁（マーケティング職） | 驚き、疑っている、調子に乗ってる |
| マスター | 本質を説明する導き手 | 標準、諭す、思考・分析 |

**詳細** → [references/character-usage.md](references/character-usage.md)

### Phase 6: HTML生成

1. Tailwind CSS CDN使用
2. **Lucide icon**を使用（絵文字禁止）
3. 本気AIブランドカラー適用
4. 用語解説ボックス配置
5. コード例の前に日本語解説

**詳細** → [references/html-structure.md](references/html-structure.md)

### Phase 7: 批判的レビュー（サブエージェント）

**リテラシーが低いユーザー視点**で、忖度なくレビューする。

```
Task({
  subagent_type: "generalPurpose",
  description: "図解の批判的レビュー",
  readonly: true,
  prompt: `
    あなたは「ITに詳しくない40代の事務職」です。
    プログラミング経験はゼロ、スマホは使えるがアプリの仕組みは知りません。
    
    以下のHTML図解を読んで、**忖度なく**批判してください：
    
    【HTMLファイルパス】{path}
    
    ## レビュー観点
    
    1. **わからない言葉**: 説明されていても難しい言葉はどれか
    2. **たとえ話の違和感**: ピンとこない、逆に混乱するたとえはないか
    3. **情報過多**: 読むのが辛くなる部分、スキップしたくなる部分
    4. **キャラクターの不自然さ**: セリフが専門家っぽすぎないか
    5. **結局何がわかったか**: 読み終わって説明できる自信があるか
    
    ## 出力形式
    
    ### 致命的な問題（これがあると読めない）
    - ...
    
    ### 改善すべき点（直せばもっと良くなる）
    - ...
    
    ### 良かった点（このまま残すべき）
    - ...
    
    ### 総評
    5段階評価: ⭐⭐⭐☆☆（3/5）のように
    一言: 「○○だから△△な人には難しい」のように
  `
})
```

### Phase 8: ブラッシュアップ

Phase 7のレビュー結果を踏まえてHTMLを修正する。

**優先度**:
1. 致命的な問題 → 必ず修正
2. 改善すべき点 → 可能な限り対応
3. 良かった点 → 維持

**よくある修正パターン**:
- 用語解説ボックスの追加
- たとえ話の差し替え・追加
- 長いセクションの分割
- キャラクターのセリフをより素朴に

### Phase 9: デプロイ

```bash
# 1. 一時ディレクトリ作成
DEPLOY_DIR=$(mktemp -d)

# 2. HTMLファイル作成
# index.html を $DEPLOY_DIR に書き込む

# 3. キャラクター画像をコピー
mkdir -p "$DEPLOY_DIR/images"
cp docs/design/charactor-images/square/512px/マジくん-*.png "$DEPLOY_DIR/images/"
cp docs/design/charactor-images/square/512px/マスター-*.png "$DEPLOY_DIR/images/"

# 4. surge.shにデプロイ
cd "$DEPLOY_DIR" && surge . --domain {ドメイン名}.surge.sh
```

---

## 品質チェックリスト

### 必須

- [ ] 技術用語には必ず「用語解説ボックス」がある
- [ ] たとえ話が3つ以上ある
- [ ] キャラクター対話が導入・中間・まとめにある
- [ ] 「まず覚える3つ」のような絞り込みがある
- [ ] コード例の前に「このコードがやること」がある

### デザイン

- [ ] Lucide iconを使用（絵文字禁止）
- [ ] 本気AIブランドカラーが適用されている
- [ ] キャラクター画像が正しく配置されている
- [ ] スマホでも読みやすいレスポンシブ対応

---

## 模範解答

具体的なHTML構造と成功パターン → [references/exemplar.md](references/exemplar.md)