196 lines
6.5 KiB
Markdown
196 lines
6.5 KiB
Markdown
---
|
||
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)
|