commit 4216635369648ee5898f090d8e69065cea6336dd Author: snc777 Date: Fri Mar 20 15:51:26 2026 +0900 初回コミット: パーソナル図解ツールキット Made-with: Cursor diff --git a/.claude/skills/creating-skills/SKILL.md b/.claude/skills/creating-skills/SKILL.md new file mode 100644 index 0000000..f83b52f --- /dev/null +++ b/.claude/skills/creating-skills/SKILL.md @@ -0,0 +1,68 @@ +--- +name: creating-skills +description: スキルを作成・更新・改善するスキル。「スキルを作って」「このスキルを改善して」「スキルを更新して」など依頼された際やスキルを更新する際に使用する。 +--- + +# Skill Creator + +**品質方針**: スキル作成は時間より品質を優先する。手順のスキップや品質チェックの省略は禁止。全ステップを確実に実行し、品質チェックを通過してから完了とする。 + +## 必読リファレンス（省略禁止） + +**作業開始前に必ず全て読むこと。時間短縮のためにスキップしない:** + +1. [references/principles.md](references/principles.md) — 核心原則・構造・判断基準 +2. [references/ssot-audit.md](references/ssot-audit.md) — SSoT 監査・ハードコード不整合レビュー（ゲートとして必ず実行） +3. [references/exemplar.md](references/exemplar.md) — 模範例・品質チェックリスト +4. [references/patterns.md](references/patterns.md) — 設計パターン・サイズ目安 + +## 作成プロセス + +### Step 0: リファレンスを読む + +上記4つのリファレンスを全て読む。省略禁止。 + +### Step 1: 種類を判断 + +汎用スキルかプロジェクト固有スキルかを判断する。 + +→ [principles.md](references/principles.md)（スキルの種類） + +### Step 2: 情報を分離 + +SKILL.md に置く情報と references/ に置く情報を分離する。 + +→ [patterns.md](references/patterns.md)（ディレクトリパターン、3段階ローディング） + +### Step 3: 洗練 + +核心原則に基づいてスキルの内容を精査する。 + +→ [principles.md](references/principles.md)（洗練、簡潔性） + +### Step 4: SSoT 監査（ゲート） + +**SSoT 監査を通過するまで次のステップに進めない。** + +[ssot-audit.md](references/ssot-audit.md) の全ステップを実行し、違反がないことを確認する。違反が見つかったら修正してから再監査。 + +### Step 5: 品質チェック + +[exemplar.md](references/exemplar.md) のチェックリストを全項目確認する。未通過の項目があれば修正。 + +### Step 6: ハードコード・不整合レビュー（ゲート） + +**このレビューを通過するまで完了としない。** + +作成したスキルに以下の問題がないか最終確認する: + +1. **ハードコードされた詳細情報がないか** — 参照先を読めばわかる具体的な値・構造・手順がスキル内にベタ書きされていないか +2. **参照先変更時の不整合リスクがないか** — 参照先が更新されたとき、スキル内の記述が古くなる箇所がないか + +→ [ssot-audit.md](references/ssot-audit.md)（ハードコード・不整合レビュー） + +### Step 7: 評価と反復 + +スキルを書いて終わりにしない。実際の使用を観察して改善する。 + +→ [exemplar.md](references/exemplar.md)（評価と反復プロセス） diff --git a/.claude/skills/creating-skills/references/exemplar.md b/.claude/skills/creating-skills/references/exemplar.md new file mode 100644 index 0000000..550ba61 --- /dev/null +++ b/.claude/skills/creating-skills/references/exemplar.md @@ -0,0 +1,321 @@ +# スキル模範例とチェックリスト + +## 目次 + +- description の書き方 +- 汎用スキル例 +- プロジェクト固有スキル例 +- コード付きスキル例 +- スクリプトの品質 +- 評価と反復プロセス +- チェックリスト + +--- + +## description の書き方 + +### 三人称ルール + +descriptionはシステムプロンプトに注入される。視点の不一致はスキル発見の問題を引き起こす。 + +```yaml +# 良い: 三人称 +description: スキルを作成・更新・改善するスキル。「スキルを作って」「このスキルを改善して」と依頼された際に使用する。 + +# 悪い: 一人称 +description: 私がスキルの作成を手伝います。 + +# 悪い: 二人称 +description: あなたがスキルを作成する時に使えます。 +``` + +### トリガーフレーズ + +Claudeが100+のスキルから選択する判断材料。具体的なキーワードを含める。 + +```yaml +# 良い: トリガーフレーズ3つ以上 + 具体的なキーワード +description: | + Cursor Hooksを作成・設定するスキル。 + 「フックを作って」「hookを追加して」「afterFileEditを設定して」と依頼された際に使用する。 + +# 悪い: トリガーがない +description: Hooksを処理するスキル。 + +# 悪い: 抽象的すぎる +description: 設定関連の作業を支援する。 +``` + +### 命名規則 + +gerund形式（動詞+ing）が活動を明確に伝える。 + +``` +良い: processing-pdfs, analyzing-data, managing-hooks +許容: pdf-processing, data-analysis（名詞句） +避ける: helper, utils, tools（曖昧） +``` + +--- + +## 汎用スキル + +プロジェクト固有の実装に依存しない。公式ドキュメント・仕様に基づく。 + +### 例: hook-creator + +```markdown +--- +name: hook-creator +description: Cursor Hooksを作成・設定するスキル。「フックを作って」「hookを追加して」「afterFileEditを設定して」と依頼された際に使用する。 +--- + +# Hook Creator + +Cursor Hooksの作成・設定を支援する。 + +## 概要 + +Hooksはエージェントループの特定タイミングでカスタムスクリプトを実行する仕組み。 + +## クイックスタート + +[最小限の例] + +## フックイベント一覧 + +| イベント | タイミング | 出力 | +|---------|-----------|------| +| afterFileEdit | ファイル編集後 | なし | +| stop | Agent停止時 | followup_message | + +**詳細スキーマ** → [references/events.md](references/events.md) +``` + +**ポイント**: +- 公式ドキュメントの内容のみ +- プロジェクト固有の実装パターンなし + +--- + +## プロジェクト固有スキル + +特定プロジェクトのワークフロー・データ構造に依存。依存先を明示する。 + +### 構造例 + +```markdown +--- +name: project-specific-skill +description: プロジェクト固有の作業を行うスキル。「〇〇を作って」「〇〇を更新して」と依頼された際に使用する。 +--- + +# Project Specific Skill + +## 依存 + +- `path/to/` 配下のディレクトリ構造 +- `config.json` スキーマ（references/schema.md） +- 品質チェックフロー（.cursor/hooks/validate.sh） + +## ワークフロー + +[プロジェクト固有のワークフロー] + +## 出力形式 + +[プロジェクト固有のスキーマ] +``` + +**ポイント**: +- 依存先を「依存」セクションで明示 +- 変更時の影響範囲が把握できる + +--- + +## コード付きスキル + +スクリプトで決定的処理を実行し、SKILL.md は仕組み・実行方法・出力を記載する。 + +### 例: hooks-toggle + +```markdown +--- +name: hooks-toggle +description: Cursorフックを一時的に無効化/有効化するスキル。「フックを止めて」「フックを無効にして」「フックを有効にして」「hooks off」「hooks on」と依頼された際に使用する。 +--- + +# Hooks Toggle + +Cursor hooks と SDK hooks を同時に無効化/有効化する。 + +## 仕組み + +各 `hooks-disabled` ファイルの有無でフックが動作を判定。 +- ファイルあり → フック無効 +- ファイルなし → フック有効 + +## 実行 + +bash .claude/skills/hooks-toggle/scripts/toggle-hooks.sh + +## 出力 + +| 状態 | 出力 | +|------|------| +| 有効→無効 | `Hooks disabled (Cursor + SDK)` | +| 無効→有効 | `Hooks enabled (Cursor + SDK)` | + +## 依存 + +- `.cursor/hooks/on-quiz-edit.ts` - スキップ判定ロジック +- `drill/tools/quiz-viewer/server/hooks/index.ts` - スキップ判定ロジック +``` + +**ポイント**: +- `scripts/toggle-hooks.sh` で状態管理（ファイル作成/削除）を確実に実行 +- SKILL.md は**仕組み・実行方法・出力**を記載（スクリプトの実装詳細は書かない） +- 依存セクションでフック判定ロジックの所在を明示 + +--- + +## スクリプトの品質 + +### Solve, don't punt + +スクリプト内でエラーを処理する。Claudeに丸投げしない。 + +```python +# 良い: エラーを自力で処理 +def process_file(path): + try: + with open(path) as f: + return f.read() + except FileNotFoundError: + print(f"File {path} not found, creating default") + with open(path, "w") as f: + f.write("") + return "" + +# 悪い: Claudeに丸投げ +def process_file(path): + return open(path).read() +``` + +### マジックナンバー禁止 + +設定値には根拠を示す。 + +```python +# 良い: 根拠がある +REQUEST_TIMEOUT = 30 # HTTPリクエストは通常30秒以内に完了 +MAX_RETRIES = 3 # 大半の間欠的エラーは2回目で解消 + +# 悪い: 根拠不明 +TIMEOUT = 47 # なぜ47? +RETRIES = 5 # なぜ5? +``` + +### 検証可能な中間出力 + +複雑なタスクでは「計画→検証→実行」パターンでエラーを早期発見する。 + +``` +analyze → changes.json作成 → validate_changes.py → 問題なければ実行 +``` + +バリデーションスクリプトのエラーメッセージは具体的に: +- 良い: `Field 'signature_date' not found. Available: customer_name, order_total` +- 悪い: `Validation failed` + +--- + +## 評価と反復プロセス + +### 評価駆動開発 + +スキルを書く前に、まずClaudeの現状の能力を測定する。 + +1. **ベースライン計測**: スキルなしでClaudeにタスクを実行させる +2. **Gap特定**: 失敗箇所・不足情報を文書化 +3. **評価シナリオ作成**: Gapをテストする3つ以上のシナリオを用意 +4. **最小限の記述**: Gapを埋める最小限のスキル内容を書く +5. **反復**: 評価を実行し、ベースラインと比較し、改善 + +```json +{ + "skills": ["pdf-processing"], + "query": "このPDFからテキストを抽出してoutput.txtに保存して", + "files": ["test-files/document.pdf"], + "expected_behavior": [ + "PDFライブラリを使用してファイルを正常に読み取る", + "全ページからテキストを漏れなく抽出する", + "output.txtに読みやすい形式で保存する" + ] +} +``` + +### Claude A/B パターン + +- **Claude A**（設計者）: スキルの内容を設計・改善する会話 +- **Claude B**（使用者）: スキルを使って実際のタスクを実行する会話 + +Claude Bの挙動を観察してClaude Aに報告し、改善する: + +| 観察 | 対応 | +|------|------| +| Claudeがバンドルファイルを一度も読まない | 不要か、SKILL.mdでの参照が不十分 | +| 同じファイルを繰り返し読む | そのコンテンツをSKILL.mdに昇格 | +| 参照リンクをたどらない | リンクをより目立たせる | +| 予想外の順序でファイルを読む | 構造が直感的でない可能性 | + +### チーム展開時 + +- スキルをチームメンバーに共有し、使用状況を観察 +- 「期待通りに発動するか？」「指示は明確か？」「何が足りないか？」を確認 + +--- + +## チェックリスト + +### 全スキル共通 + +- [ ] descriptionに「何をするか」と「いつ使うか」の両方がある +- [ ] descriptionにトリガーフレーズ3つ以上 +- [ ] descriptionが三人称で書かれている +- [ ] SKILL.md 500行以内 +- [ ] 冗長な説明なし +- [ ] 一貫した用語を使用 +- [ ] 時間依存情報なし +- [ ] 具体的な例がある +- [ ] ワークフローに明確なステップがある +- [ ] **SSoT 監査を通過済み**（[ssot-audit.md](ssot-audit.md) の全ステップを実行し、違反なしを確認） +- [ ] **ハードコード・不整合レビューを通過済み**（[ssot-audit.md](ssot-audit.md) のレビュー全項目を確認） +- [ ] 参照は1階層まで（深いネスト禁止） +- [ ] 100行超の参照ファイルに目次がある + +### 汎用スキル + +- [ ] 公式ドキュメント・仕様に基づいている +- [ ] プロジェクト固有のパターン・実装がない +- [ ] 他プロジェクトでも使える + +### プロジェクト固有スキル + +- [ ] 「依存」セクションがある +- [ ] 依存するファイル・ワークフローが明示されている +- [ ] 依存先が変更されたときの影響範囲が分かる + +### コード付きスキル + +- [ ] 実行方法が SKILL.md に記載されている +- [ ] 決定的処理がスクリプトで実装されている +- [ ] スクリプトがエラーを自力で処理する +- [ ] 設定値に根拠がある（マジックナンバーなし） +- [ ] 必要なパッケージが明記されている + +### テスト + +- [ ] 実際のタスクでテスト済み +- [ ] 3つ以上の評価シナリオがある +- [ ] 使用予定の全モデルでテスト済み（Haiku/Sonnet/Opus） diff --git a/.claude/skills/creating-skills/references/patterns.md b/.claude/skills/creating-skills/references/patterns.md new file mode 100644 index 0000000..c298459 --- /dev/null +++ b/.claude/skills/creating-skills/references/patterns.md @@ -0,0 +1,299 @@ +# パターン集 + +SKILL.mdを簡潔に保ちながら、必要な情報を適切なタイミングで提供するための設計パターン。 + +## 目次 + +- 3段階ローディング +- ディレクトリパターン（ハイレベルガイド / ドメイン分割 / 基本と応用 / コード付き） +- 自由度パターン +- ワークフローパターン +- フィードバックループ +- テンプレートパターン +- 条件分岐パターン +- アンチパターン +- サイズ目安 + +--- + +## 3段階ローディング + +``` +Level 1: description（常時） → トリガー判定（〜100トークン/スキル） +Level 2: SKILL.md（トリガー時） → 指示・手順（〜5kトークン） +Level 3: references/（必要時） → 詳細情報（実質無制限） +``` + +Level 3はファイルシステム上に存在するだけで、アクセスされるまでコンテキストを消費しない。スクリプトは実行のみで、コード自体はコンテキストに入らない（出力のみ）。 + +--- + +## ディレクトリパターン + +### パターン1: ハイレベルガイド + +概要＋クイックスタートをSKILL.mdに、詳細をreferences/に。 + +``` +skill/ +├── SKILL.md # 概要 + クイックスタート +└── references/ + ├── schema.md # 詳細スキーマ + └── examples.md # 使用例 +``` + +**使用場面**: APIドキュメント、チュートリアル系 + +### パターン2: ドメイン分割 + +複数ドメインをサポート。必要なドメインのみ読む。 + +``` +skill/ +├── SKILL.md # 選択ガイド + 共通手順 +└── references/ + ├── aws.md + ├── gcp.md + └── azure.md +``` + +**使用場面**: マルチプラットフォーム対応 + +### パターン3: 基本と応用 + +基本機能はSKILL.md、高度な機能はreferences/に分離。 + +``` +skill/ +├── SKILL.md # 基本操作 +└── references/ + └── advanced.md # 高度な機能 +``` + +**使用場面**: 基本と応用で複雑さが異なる + +### パターン4: コード付きスキル + +決定的処理をスクリプトで実行し、SKILL.md は目的・実行方法・出力を記載。 + +``` +skill/ +├── SKILL.md # 目的 + 実行方法 + 出力 +├── scripts/ +│ └── do-something.ts # 決定的処理 +└── references/ (任意) +``` + +**使用場面**: ファイルシステム操作、外部ツール連携、状態管理 + +スクリプトの実行意図を明確にする: +- 「`analyze_form.py` を実行してフィールドを抽出」→ 実行 +- 「`analyze_form.py` の抽出アルゴリズムを参照」→ 読む + +--- + +## 自由度パターン + +タスクの性質に応じて、指示の具体度を3段階で調整する。 + +### 高自由度（テキストベースの方針） + +ヒューリスティクスが指針となり、文脈で判断が変わり、複数のアプローチが妥当な場合。 + +```markdown +## コードレビュー + +1. コード構造と設計を分析 +2. バグや境界ケースの可能性を確認 +3. 可読性・保守性の改善を提案 +4. プロジェクト規約への準拠を検証 +``` + +### 中自由度（パラメータ付きの擬似コード） + +設定が挙動に影響し、ある程度の変動は許容されるが、推奨パターンがある場合。 + +```markdown +## レポート生成 + +以下のテンプレートを必要に応じてカスタマイズ: + +def generate_report(data, format="markdown", include_charts=True): + # データ処理 + # 指定形式で出力 + # オプションでチャートを含める +``` + +### 低自由度（具体的なスクリプト、変更禁止） + +操作が壊れやすく、一貫性が必須で、特定の手順を踏む必要がある場合。 + +```markdown +## データベースマイグレーション + +以下のスクリプトをそのまま実行: + +python scripts/migrate.py --verify --backup + +コマンドを変更したり、フラグを追加しないこと。 +``` + +--- + +## ワークフローパターン + +複雑なタスクを明確なステップに分解する。チェックリストを使うとClaudeが進捗を追跡できる。 + +```markdown +## ワークフロー + +このチェックリストをコピーして進捗を管理: + +- [ ] Step 1: フォームを解析（analyze_form.py実行） +- [ ] Step 2: フィールドマッピングを作成（fields.json編集） +- [ ] Step 3: マッピングを検証（validate_fields.py実行） +- [ ] Step 4: フォームに記入（fill_form.py実行） +- [ ] Step 5: 出力を検証（verify_output.py実行） + +**Step 1: フォームを解析** +実行: `python scripts/analyze_form.py input.pdf` +... + +**Step 5: 出力を検証** +検証に失敗した場合、Step 2に戻る。 +``` + +**ポイント**: +- 明確なステップがスキップを防ぐ +- チェックリストでClaudeとユーザーの双方が進捗を把握 + +--- + +## フィードバックループ + +「実行 → 検証 → 修正 → 再検証」のパターン。出力品質を大幅に改善する。 + +### コード付きスキルの場合 + +```markdown +## 編集プロセス + +1. `word/document.xml` を編集 +2. **即座に検証**: `python scripts/validate.py unpacked_dir/` +3. 検証失敗時: + - エラーメッセージを確認 + - XMLを修正 + - 再度検証を実行 +4. **検証が通るまで次に進まない** +5. リビルド: `python scripts/pack.py unpacked_dir/ output.docx` +``` + +### コードなしスキルの場合 + +```markdown +## コンテンツレビュー + +1. STYLE_GUIDE.md のガイドラインに従ってコンテンツを作成 +2. チェックリストでレビュー: + - 用語の一貫性 + - 例のフォーマット準拠 + - 必須セクションの網羅 +3. 問題があれば修正して再レビュー +4. 全要件を満たすまで次に進まない +``` + +**ポイント**: バリデーションスクリプトのエラーメッセージは具体的に（例: 「フィールド 'signature_date' が見つかりません。利用可能: customer_name, order_total」） + +--- + +## テンプレートパターン + +出力形式を指定する。要件の厳密さに応じて表現を変える。 + +### 厳密な要件 + +```markdown +## レポート構造 + +必ずこのテンプレート構造を使用: + +# [分析タイトル] + +## 要約 +[主要な発見の概要（1段落）] + +## 主要な発見 +- 発見1（データ付き） +- 発見2（データ付き） + +## 推奨事項 +1. 具体的なアクション +2. 具体的なアクション +``` + +### 柔軟なガイダンス + +```markdown +## レポート構造 + +以下はデフォルト形式。分析内容に応じて判断: + +# [分析タイトル] +## 要約 +## 主要な発見 +## 推奨事項 + +セクションは分析の種類に応じて調整すること。 +``` + +--- + +## 条件分岐パターン + +Claudeを決定ポイントで適切な分岐へ導く。 + +```markdown +## ドキュメント変更ワークフロー + +1. 変更の種類を判定: + + **新規作成?** → 下の「作成ワークフロー」へ + **既存の編集?** → 下の「編集ワークフロー」へ + +2. 作成ワークフロー: + - docx-jsライブラリを使用 + - ドキュメントをゼロから構築 + - .docx形式にエクスポート + +3. 編集ワークフロー: + - 既存ドキュメントを展開 + - XMLを直接修正 + - 変更ごとにバリデーション + - 完了後にリパック +``` + +ワークフローが大規模になる場合は、別ファイルに分離してClaudeに適切なファイルを読ませる。 + +--- + +## アンチパターン + +| 問題 | 解決 | +|------|------| +| SKILL.md 500行超え | references/に分割 | +| references/が深いネスト（2階層以上） | 1階層に平坦化 | +| 情報の重複 | 1箇所にのみ記載（SSoT） | +| descriptionにトリガーなし | トリガーフレーズ3つ以上 | +| 用語の不統一（「抽出」「取得」「取り出し」混在） | 1つの概念に1つの用語 | +| 選択肢の提示しすぎ | デフォルト1つ + 例外時の代替 | +| 時間依存情報（「2025年8月以前は〜」） | 現在の方法のみ記載 | + +--- + +## サイズ目安 + +| ファイル | 推奨 | 上限 | +|----------|------|------| +| description | 〜200文字 | 1024文字 | +| SKILL.md | 〜200行 | 500行 | +| references/各ファイル | 〜300行 | 目次必須（100行超） | diff --git a/.claude/skills/creating-skills/references/principles.md b/.claude/skills/creating-skills/references/principles.md new file mode 100644 index 0000000..36918fb --- /dev/null +++ b/.claude/skills/creating-skills/references/principles.md @@ -0,0 +1,119 @@ +# 核心原則 + +## 目次 + +- 洗練 (Refine) +- 簡潔性 (Concise) +- SSoT 厳守 +- 段階的開示・自由度 +- スキルの種類 +- 構造とフロントマター +- コード vs プロンプトの判断 +- コンテンツガイドライン + +--- + +## 洗練 (Refine) + +スキルは**公式ドキュメントや安定した仕様**に基づいて書く。 + +| 良い | 避ける | +|------|--------| +| 公式APIスキーマ | 現在の実装コード | +| 安定した仕様 | 変更されうるパターン | +| 普遍的な原則 | プロジェクト固有のワークフロー | + +**例外**: プロジェクト固有スキルは意図的に依存してよい（→ スキルの種類） + +--- + +## 簡潔性 (Concise) + +コンテキストウィンドウは共有資源。**本当に必要な情報だけ**を含める。 + +- 冗長な説明より簡潔な例 +- 「このトークンコストに見合う価値があるか？」「Claudeが既に知っていないか？」を問う + +--- + +## SSoT 厳守 + +**参照先の情報をスキル内に書かない。** 情報は必ず1箇所だけに存在させ、他の箇所からは参照する。スキーマが変更された時、スキル内のコピーは古くなり、矛盾が生じる。 + +違反パターンの具体例・監査手順 → [ssot-audit.md](ssot-audit.md) + +--- + +## 段階的開示・自由度 + +詳細 → [patterns.md](patterns.md)（3段階ローディング、自由度パターン） + +--- + +## スキルの種類 + +### 汎用スキル + +どのプロジェクトでも使える。公式ドキュメント・仕様に基づく。 + +**原則**: プロジェクト固有の実装パターンに依存しない + +### プロジェクト固有スキル + +特定プロジェクトのワークフロー・データ構造に依存。 + +**原則**: 依存先を「依存」セクションで明示し、変更時の影響範囲を把握できるようにする + +--- + +## 構造とフロントマター + +### ディレクトリ構造 + +``` +skill-name/ +├── SKILL.md (必須) +├── scripts/ (任意) +│ └── *.ts / *.sh +└── references/ (任意) + └── *.md +``` + +### フロントマター + +```yaml +--- +name: kebab-case（64文字以内、小文字・数字・ハイフンのみ） +description: 三人称で記述。何をするか＋トリガーフレーズ3つ以上（1024文字以内） +--- +``` + +descriptionの書き方・良い例・悪い例 → [exemplar.md](exemplar.md)（descriptionの書き方） + +--- + +## コード vs プロンプトの判断 + +スキルの処理を **scripts/ のコード** で実装するか、**SKILL.md のプロンプト指示** に任せるか。 + +| コードを書く（scripts/） | プロンプトで指示する（SKILL.md） | +|--------------------------|--------------------------------| +| 決定的（毎回同じ結果が必要） | 創造的・文脈依存 | +| ファイルシステム操作（再帰削除、ツリー構築） | コンテンツ生成・判断 | +| 外部ツール連携（git, gh, surge） | コードレビュー・分析 | +| 状態管理（フラグファイル、タイムスタンプ） | 対話的ワークフロー | +| スキーマに基づくファイル生成 | 自然言語の出力 | + +### コード作成時の規約 + +- **TypeScript**: Bun で実行。`pnpm` スクリプト経由で呼び出す（直接実行禁止） +- **Bash**: 標準Unixツールのみ。`bash path/to/script.sh` で実行 +- SKILL.md にはスクリプトの**目的・実行方法・出力**を記載（実装詳細は書かない） + +スクリプト品質の原則と具体例 → [exemplar.md](exemplar.md)（スクリプトの品質） + +--- + +## コンテンツガイドライン + +禁止事項・サイズ目安 → [patterns.md](patterns.md)（アンチパターン、サイズ目安） diff --git a/.claude/skills/creating-skills/references/ssot-audit.md b/.claude/skills/creating-skills/references/ssot-audit.md new file mode 100644 index 0000000..79bc443 --- /dev/null +++ b/.claude/skills/creating-skills/references/ssot-audit.md @@ -0,0 +1,259 @@ +# SSoT 監査ガイド + +スキル作成・更新時に必ず実行する SSoT（Single Source of Truth）監査の手順。**この監査を通過するまでスキルを完成扱いにしない。** + +## 目次 + +- SSoT 違反とは +- 違反パターンと修正方法 +- 監査手順 +- 判断に迷うケース +- ハードコード・不整合レビュー + +--- + +## SSoT 違反とは + +**同じ情報が2箇所以上に存在し、片方を更新しても他方が古いまま残るリスクがある状態。** + +スキルにおける SSoT 違反は2つの場面で発生する: + +1. **スキル内部**: SKILL.md と references/ の間で情報が重複 +2. **スキル ↔ 外部**: スキルが参照するファイル（スキーマ、設定、コード）の情報をスキル内にコピー + +--- + +## 違反パターンと修正方法 + +### パターン1: スキーマ・設定のコピー + +```markdown +# 違反 +## 出力形式 +JSONは以下の構造: +- name: string (必須) +- age: number (任意) +- email: string (必須) + +# 正解 +## 出力形式 +SSoT: `path/to/schema.ts` の型定義を参照 +``` + +### パターン2: ルール一覧の転記 + +```markdown +# 違反 +## バリデーション +以下のルールでチェック: +1. nameは3文字以上 +2. emailは@を含む +3. ageは0以上 + +# 正解 +## バリデーション +SSoT: `path/to/validator.ts` のバリデーションルールに従う +``` + +### パターン3: SKILL.md と references/ の重複 + +```markdown +# 違反 +SKILL.md に品質チェックリストを書き、references/exemplar.md にも同じリストがある + +# 正解 +チェックリストは exemplar.md のみに記載。SKILL.md は「品質チェック → exemplar.md」と参照 +``` + +### パターン4: 他スキルとの重複 + +```markdown +# 違反 +スキルAとスキルBの両方に同じデプロイ手順を記載 + +# 正解 +共通手順を共有リファレンスに置き、両方から参照 +``` + +--- + +## 監査手順 + +スキルの作成・更新が完了したら、以下の全ステップを実行する。 + +### Step 1: 情報ソースの列挙 + +スキルが参照する外部ファイルを全て列挙する: + +- スキーマファイル（.ts, .json） +- 設定ファイル +- 他のスキルの references/ +- プロジェクトのドキュメント + +### Step 2: スキル内コンテンツの監査 + +SKILL.md と references/ 内の**各テーブル・リスト・コードブロック**について問う: + +**「この情報の真のソース（原本）はどこか？」** + +- **スキル内が原本** → Step 3 へ +- **スキル外に原本がある** → 違反。参照に置き換える + +### Step 3: 重複の検索 + +スキル内が原本の情報について、プロジェクト内に同じ情報がないか確認: + +```bash +grep -r "キーワード" --include="*.md" --include="*.ts" --include="*.json" +``` + +重複が見つかったら: +- どちらを原本にするか決定 +- もう片方を参照に置き換え + +### Step 4: スキル内部の重複チェック + +SKILL.md と references/ の間で同じ情報が書かれていないか確認: + +- SKILL.md に書いた内容が references/ にもないか +- references/ の複数ファイルに同じ情報がないか + +### Step 5: 最終確認 + +以下を全て満たすことを確認: + +- [ ] スキル内の全テーブル・リストが「このスキルでしか定義されていない情報」のみを含む +- [ ] 外部ファイルの情報をスキル内にコピーしていない +- [ ] SKILL.md と references/ の間に重複がない +- [ ] references/ の複数ファイル間に重複がない + +--- + +## 判断に迷うケース + +### 「要約」は許されるか？ + +**原則: 方向性を示す一文は許容。詳細リストのコピーは禁止。** + +```markdown +# OK: 方向性だけ示して参照 +## 概要 +核心原則に基づいてスキルを設計する。 +詳細 → references/principles.md + +# NG: リストのコピー（要約に見せかけた重複） +## 概要 +原則: +- 洗練: 公式ドキュメントに基づく +- 簡潔性: 必要最小限の情報 +- SSoT: 情報は1箇所のみ +``` + +判断基準: **「参照先が変更された時、この記述も更新が必要か？」** +- Yes → SSoT 違反。参照に置き換える +- No → 許容 + +### テーブルの一部引用は？ + +**禁止。** テーブルの一部でも、元テーブルに行が追加された時に古くなる。 + +```markdown +# NG: 一部引用 +主要なイベント: afterFileEdit, stop（全一覧は references/ を参照） + +# OK: 参照のみ +イベント一覧 → references/events.md +``` + +### 「例」としての引用は？ + +**形式の例示は1つだけ許容。内容の列挙は禁止。** + +```markdown +# OK: 形式を1つだけ示す +フロントマターの例: +--- +name: my-skill +description: ... +--- +詳細な書き方 → exemplar.md + +# NG: 複数パターンの列挙（内容のコピー） +良い例: +- feat(認証): メールアドレスでのログイン機能を追加 +- fix(決済): 税率計算の誤りを修正 +悪い例: +- バグを修正 +- 対応 +``` + +--- + +## ハードコード・不整合レビュー + +SSoT 監査（上記 Step 1〜5）が「情報のコピー」を検出するのに対し、このレビューは **ハードコードされた詳細** と **暗黙的な依存** を検出する。SSoT 監査を通過したスキルに対して追加で実行する。 + +### チェック1: ハードコードされた詳細情報 + +参照先を読めばわかる**具体的な値・構造・手順**がスキル内に直接書かれていないか確認する。 + +**検出対象**: + +- ディレクトリ構造の展開（ツリー表示） +- 設定値・パラメータの列挙 +- 外部ツールのコマンドオプション一覧 +- スキーマのフィールド名・型の網羅的リスト +- ファイルパスの詳細な列挙 + +**判断基準**: 「この詳細が変更されたとき、スキルを手動で更新する必要があるか？」 + +- Yes → 参照に置き換えるか、方向性のみの記述に変更 +- No → 許容 + +```markdown +# NG: ディレクトリ構造をハードコード +## 出力先 +contents/ +├── 講義/ +│ └── Nヶ月目/第N回/ +│ ├── meta.json +│ ├── slides.json +│ └── script.md + +# OK: 参照先を示す +## 出力先 +`contents/講義/` 配下に、実際のディレクトリ構造に従って配置する。 +``` + +### チェック2: 参照先変更時の不整合リスク + +スキル内の記述が参照先の内容に**暗黙的に依存**していないか確認する。コピーではないが、参照先の更新により事実と乖離するリスクのある記述を検出する。 + +**検出対象**: + +- 参照先の件数に依存する表現（「3つの原則」「5つのステップ」） +- 参照先の内容を要約した記述（要約は参照先が変われば古くなる） +- 参照先の特定ステップ名・ラベルをインラインで使った記述 + +**判断基準**: 「参照先のファイルが更新されたとき、この記述はまだ正確か？」 + +- 不確実 → 参照先に依存しない表現に書き換える +- 常に正確 → 許容 + +```markdown +# NG: 参照先の個数に暗黙的に依存 +3つの核心原則に基づいてスキルを設計する。 +→ 原則が追加・削除されたら不正確になる + +# OK: 個数に依存しない +核心原則に基づいてスキルを設計する。 +詳細 → references/principles.md +``` + +### レビュー最終確認 + +以下を全て満たすことを確認: + +- [ ] スキル内にディレクトリ構造・スキーマ・設定値のベタ書きがない +- [ ] 参照先の件数・名前に依存する表現がない +- [ ] 参照先が更新されてもスキル内の記述が正確なままである diff --git a/.claude/skills/creating-visual-explainers/SKILL.md b/.claude/skills/creating-visual-explainers/SKILL.md new file mode 100644 index 0000000..d31b627 --- /dev/null +++ b/.claude/skills/creating-visual-explainers/SKILL.md @@ -0,0 +1,218 @@ +--- +name: creating-visual-explainers +description: Generates an illustrated HTML page about any topic and deploys it to surge.sh. Triggered by requests like "図解を作って", "図解を生成して", "このトピックを図解して", or "図解してデプロイして". +--- + +# Creating Visual Explainers + +任意のトピックについて、前提知識がなくても理解できる図解HTMLを生成し、surge.shに公開する。品質基準は「入社したての新卒社会人が読んでも腹落ちする明快さ」だが、この基準は出力には表示しない。 + +## 依存 + +- `references/base.html` — 図解テンプレート（Tailwind CSS CDN・Lucide Icons CDN・ADS配色を含む「額縁」） +- `references/model-answer.html` — 模範回答（品質基準・デザインパターンの実例）。base.htmlと同一の額縁を含む完全なHTMLファイル + +## ワークフロー + +### Step 0: 前提確認 + +`references/base.html` が存在するか確認する。 + +存在しない場合、以下を伝えて終了: + +> テンプレートファイルが見つかりません。スキルのフォルダ構成が壊れている可能性があります。運営に連絡してください。 + +### Step 1: 模範回答の読み込み + +`references/model-answer.html` を読み、以下を把握する: + +- 完成品の品質水準 +- デザインパターン（色使い・余白・カード・フロー図などの視覚表現） +- Tailwind CSSクラスの使い方 +- Lucide Iconsの使い方 +- コンテンツの構成・情報量・説明の深さ + +模範回答がデザインガイドラインの代わりになる。パーツ一覧やルールではなく、実物から読み取る。 + +### Step 2: テンプレートの読み込み + +`references/base.html` を読み、額縁の構造を把握する: + +- `` 〜 `` のプレースホルダー位置 +- ``, `` のプレースホルダー +- ADS配色のTailwind設定 +- 読み込み済みのCDN（Tailwind CSS・Lucide Icons） + +### Step 3: ウェブで情報収集 + +トピックについてウェブ検索を行い、正確かつ最新の情報を収集する。 + +検索は **2〜3回** に絞る。以下の観点でクエリを組み立てる: + +1. **正確な定義**: トピックの公式な定義、公式ドキュメントの説明 +2. **最新動向**: 直近の変更点、アップデート、現在のベストプラクティス +3. **具体例**: 実際の使われ方、初心者に伝わるたとえに使える事例 + +検索結果から以下を整理し、Step 4 の参考情報とする: + +- トピックの正確な定義（検索結果を優先。AIの学習データだけに頼らない） +- 最近変わった点があれば、それを明記する +- たとえ話に使えそうな事例や数字 +- **出典URL**: 図解に採用した情報のソースURLを控えておく（Step 4 でインライン出典に使う） + +### Step 4: コンテンツ生成 + +Step 3 で収集した情報をもとに、図解HTMLを生成する。検索結果で得た定義・事実・具体例を優先的に採用する。 + +模範回答のデザインを参考にしつつ、Tailwindの語彙で自由にレイアウトを組む。模範回答のパターンに合うものはそのまま使い、合わないものはTailwindクラスでその場で作る。テンプレートの定義済みパーツに縛られない。 + +### Step 5: ファイル作成 + +1. `output/` ディレクトリがなければ作成する +2. トピックに関連する短い英単語のスラッグを決める（例: `api-basics`, `git-rebase`） +3. `references/base.html` を `output/{スラッグ}.html` にコピーする +4. コピーしたファイル内のプレースホルダーをすべて置換する: + - `` → 図解のタイトル + - `` → 内容を要約した1文 + - `` 〜 `` → Step 4で生成したコンテンツ +5. ファイルを保存する（ブラウザで開くのは Step 6 のデプロイ後に行う。ローカルでは開かない） + +### Step 6: 公開 + +ファイル保存後、公開する前にまず Node.js の有無を確認する。 + +```bash +node --version +``` + +バージョン番号が表示された → そのまま「公開の実行」に進む。 + +`command not found` と表示された → `references/node-install-guide.md` の手順に従ってNode.jsのインストールを案内する。 + +#### 公開の実行 + +以下のスクリプトを**実行する**（中身を読む必要はない）。 + +**macOS / Git Bash（Windows）の場合:** + +```bash +bash .claude/skills/creating-visual-explainers/scripts/deploy-diagram.sh output/{スラッグ}.html [スラッグ] +``` + +**Windows（PowerShell）で bash が使えない場合:** + +```powershell +npx --yes surge output/{スラッグ}.html --domain diagram-[スラッグ].surge.sh +``` + +スラッグにはトピックに関連する短い英単語を指定する（例: `git-rebase`, `api-basics`）。 + +#### 初回の場合（Surge未登録） + +ターミナルにメールアドレスとパスワードの入力を求められる。以下を伝える: + +> 初回のみアカウント登録が必要です。 +> メールアドレスを入力して Enter → パスワードを決めて入力して Enter。 +> 確認メールが届いたらリンクをクリックすれば登録完了です。 +> 次回以降はこの手順は不要です。 + +#### エラーが出た場合 + +エラーメッセージをそのまま見せず、**何が起きていて何をすれば解決するか**を、専門用語を避けて平易に説明する。 + +よくあるエラーと対応: + +- **`npx: command not found`** — Node.js がまだ入っていない。`references/node-install-guide.md` の手順を案内する +- **`surge: not found` / surge関連エラー** — `npm install -g surge` を実行してから再度試す +- **認証エラー / `Login required`** — `npx surge login` を実行してメールアドレスとパスワードを入力する +- **その他** — エラーの内容を読み、「何が問題で」「次に何をすればいいか」を平易に説明する + +### 図解の削除 + +ユーザーが「この図解を削除して」と依頼した場合: + +1. `deploy-history.log` を読み、直近のデプロイURLを特定する + - ログが存在しない場合 → ユーザーに削除したいURLを聞く +2. `npx surge teardown [ドメイン]` を実行する +3. 削除完了をユーザーに伝える + +### Step 7: 完了報告 + +#### 公開に成功した場合 + +``` +完成・公開完了: 【図解のタイトル】 + +（図解の内容を1〜2文で要約） + +公開URL: +https://diagram-スラッグ.surge.sh + +図解の主なポイント: +- （主要トピックを3〜5個） + +この図解を削除したいとき: +チャット欄で「この図解を削除して」と伝えてください。 +``` + +#### 公開できなかった場合 + +``` +完成: 【図解のタイトル】 + +（図解の内容を1〜2文で要約） + +ファイルの保存先: +output/{スラッグ}.html（ブラウザにドラッグ＆ドロップすると表示できます） + +図解の主なポイント: +- （主要トピックを3〜5個） + +URLで共有したいとき: +チャット欄で「この図解を公開して」と伝えてください。 +``` + +## 守ること（禁止事項） + +- **React・shadcn/ui を使わない** — 静的な図解にJSフレームワークは不要。AIの出力を制限し、モデルによる品質差も限定的にしてしまう +- **絵文字を使わない** — OS依存で表示が変わる。アイコンはLucide Iconsを使う +- **インタラクティブ要素を入れない** — トグル、フェードイン、アニメーション、フォーム、クリックで開閉する要素は一切禁止 +- **` + + +
+ +
+
+ + + +
+ + + + + diff --git a/.claude/skills/creating-visual-explainers/references/model-answer.html b/.claude/skills/creating-visual-explainers/references/model-answer.html new file mode 100644 index 0000000..ce24d75 --- /dev/null +++ b/.claude/skills/creating-visual-explainers/references/model-answer.html @@ -0,0 +1,968 @@ + + + + + + + + + + + + APIの仕組み + + + + + + + + + +
+ +
+
+ + + + + +
+
+ + テクノロジー +
+

+ APIの仕組み +

+

+ 「APIって何？」と聞かれて、うまく答えられない。
+ ひとことで言うと ── +

+
+ + + + + +
+
+

+ API = ソフトウェアの「注文窓口」 +

+

+ 中身を知らなくても、決まった形で頼めば結果が届く +

+
+ + +
+ +
+
+ +
+
あなたのアプリ
+
「天気を教えて」
+
+ + +
+
+ リクエスト + + +
+
+ + +
+
+ +
+
API
+
注文を届け、結果を返す
+
レストランのウェイター役
+
+ + +
+
+ 依頼 + + +
+
+ + +
+
+ +
+
サービス
+
処理して結果を返す
+
+
+ + +
+
+ + 結果（レスポンス）があなたのアプリに届く +
+
+ + +
+
+
あなたも毎日使っている
+
+
+ + +
+
+ + 天気予報 +
+
+ + Googleログイン +
+
+ + オンライン決済 +
+
+ + 地図・ナビ +
+
+ +
+ +

+ ここから先で、この仕組みをひとつずつ丁寧に解説していきます。 +

+ + + + + +
+
+
+ +
+

そもそもAPIって何？

+
+ +

+ API（エーピーアイ）は Application Programming Interface（アプリケーション・プログラミング・インターフェース）の略称です。正式名称を聞いても「何のこと？」と思いますよね。 +

+ +

+ まずは日常のたとえで考えてみましょう。レストランに行った場面を想像してください。 +

+ +

+ あなた（お客さん）は、厨房に直接入って料理を作ることはできません。厨房のルールも、調理器具の使い方も知りません。でも、ウェイターに「パスタをください」と注文すれば、厨房で作られた料理があなたのテーブルに届きます。厨房の中で何が起きているかを知る必要はありません。 +

+ + +
+

レストランで考えるAPIの役割

+ +
+ +
+
+ +
+
あなた
+
お客さん
+
「パスタください」
+
+ + +
+
+ 注文 + + +
+
+ + +
+
+ +
+
API
+
ウェイター
+
注文を伝え、料理を届ける
+
+ + +
+
+ 依頼 + + +
+
+ + +
+
+ +
+
サーバー
+
厨房
+
パスタを作って渡す
+
+
+ +
+
+ + 料理（レスポンス）があなたのテーブルに届く +
+
+
+ +

+ この比喩がAPIの本質をほぼ言い当てています。あなた（アプリ）は、厨房（サーバー）の中で何が起きているかを知る必要がありません。ウェイター（API）に決まった形式で注文を伝えれば、結果が返ってくる。これがAPIです。 +

+ + +
+
+
+ +
+
+

ここがポイント

+

+ APIは「仲介役」です。相手の内部構造を知らなくても、決まったルールで話しかければ結果が返ってくる。これがAPIの本質です。この「決まったルール」のことを、エンジニアは「インターフェース（Interface）」と呼びます。 +

+
+
+
+
+ + + + + +
+
+
+ +
+

もう少し正確に言うと

+
+ +

+ レストランのたとえで、ざっくりとしたイメージはつかめましたか？ ここからもう少しだけ正確に説明します。 +

+ +

+ APIとは、ひとことで言えば「ソフトウェア同士が会話するための窓口」です。あなたが使っているアプリの裏側で、別のサービスのデータや機能を借りてくるための「取り決め」と考えてください。 +

+ +
+
技術的な定義
+

+ API = あるソフトウェアの機能を、 + 別のソフトウェアから使えるようにする仕組み +

+

出典: MDN Web Docs — Web API の紹介

+
+ +

+ これだけだとまだ抽象的に感じるかもしれません。では、APIがある世界とない世界を比べてみましょう。 +

+ + +
+ +
+
+ + BEFORE — APIがない世界 +
+
    +
  • + + 天気情報が欲しければ、自分で気象観測の仕組みを構築する +
    • +
  • + + 決済機能が欲しければ、クレジットカード処理を自前で開発する +
    • +
  • + + 地図を表示したければ、地図データを自分で作成・更新する +
    • +
  • + + ユーザー認証はパスワード管理からセキュリティ対策まで全部自前 +
    • +
+
+ + 膨大な開発コストと時間。バグのリスクも高い。 +
+
+ + +
+
+ + AFTER — APIがある世界 +
+
    +
  • + + 天気情報は天気予報APIに問い合わせるだけで取得できる +
    • +
  • + + 決済はStripe APIに任せれば数行のコードで完成 +
    • +
  • + + 地図はGoogle Maps APIで高品質な地図を即表示できる +
    • +
  • + + ログインはGoogleやAppleのAPIで安全に認証できる +
    • +
+
+ + 「自分が本当に作るべきもの」に集中できる。 +
+
+
+
+ + + + + +
+
+
+ +
+

APIの仕組み — リクエストとレスポンス

+
+ +

+ APIでのやり取りは、実はとてもシンプルです。基本は「聞く（リクエスト）」と「答える（レスポンス）」の2つだけ。 +

+ +

+ リクエスト（Request）とは、「こういう情報をください」「この処理をしてください」とAPIに送るメッセージのことです。レスポンス（Response）は、APIがその要求に対して返す結果です。この2つのやり取りを分解すると、4つのステップになります。 +

+ + +
+

APIリクエスト〜レスポンスの流れ

+ +
+
+
1
+ +
リクエスト送信
+
あなたのアプリが
「こういう情報ください」
とAPIに送る
+
+ +
+ + +
+ +
+
2
+ +
APIが受け取る
+
リクエストの内容を
チェック・認証する
（門番の役割）
+
+ +
+ + +
+ +
+
3
+ +
サーバーが処理
+
データベース検索や
計算など、実際の
処理を実行する
+
+ +
+ + +
+ +
+
4
+ +
レスポンス返却
+
処理結果をあなたの
アプリに返す
（料理が届く瞬間）
+
+
+
+ +

+ 言葉だけだとまだピンとこないかもしれません。では、実際のコードで見てみましょう。たとえば、天気予報APIから東京の天気を取得するコードは、たったこれだけです。 +

+ + +
+
+ + JavaScript — 天気予報APIの呼び出し例 +
+ 
// 1. APIにリクエストを送る（「東京の天気を教えて」と聞く）
+const response = await fetch("https://api.weather.example.com/current?city=tokyo");
+
+// 2. レスポンスをJSON形式（データの構造）に変換する
+const data = await response.json();
+
+// 3. 必要なデータを取り出して使う
+console.log(data.temperature); // → "22°C"
+console.log(data.condition);   // → "晴れ"
+console.log(data.humidity);    // → "65%"
+
+ + +
+

+ + コードの解説（1行ずつ読み解く） +

+
+
+ 1 + fetch() は「指定したURLに問い合わせる」命令。URLの末尾にある ?city=tokyo が「東京の情報が欲しい」というリクエストの中身です。レストランのたとえで言えば「パスタください」にあたる部分。 +
+
+ 2 + 返ってきたデータは機械向けの生データなので、.json() で人間が読みやすい形（JSON = JavaScript Object Notation）に変換します。JSONは「名前: 値」の組み合わせでデータを表現する書式で、Web業界で最も広く使われています。 +
+
+ 3 + 変換したデータから data.temperature のように、ドット（.）で区切って欲しい情報を名前で取り出します。辞書で単語を引くのに似ています。 +
+
+
+ +

+ ターミナル（コマンドを入力する黒い画面）からもAPIを試せます。curl（カール）というコマンドを使うと、たった1行でAPIにリクエストを送れます。 +

+ + +
+
+
+
+
+
+
+
+ + ターミナル — curlコマンドでAPIを叩く +
+
+ 
$ curl https://api.weather.example.com/current?city=tokyo
+
+# 返ってくるレスポンス（JSON形式）
+{
+  "city": "東京",
+  "temperature": "22°C",
+  "condition": "晴れ",
+  "humidity": "65%"
+}
+
+ +
+
+
+ +
+
+

ちょっと補足: URLの構造

+

+ https://api.weather.example.com/current?city=tokyo のURLは、大きく3つの部分に分かれます。api.weather.example.com がAPIの住所（ベースURL）、/current が「何を」（現在の天気）、?city=tokyo が「どこの」（東京）というパラメータです。レストランで例えると「〇〇レストランの（住所）、メインメニューから（何を）、パスタを（詳細）」に対応します。 +

+
+
+
+ +

+ では、このAPIのレスポンスが実際のアプリではどう表示されるのでしょうか？ あなたが見ている天気アプリの画面を覗いてみましょう。 +

+ + +
+
+
+
+
+
+
+
+ + weather-app.example.com +
+
+
+
+
現在地: 東京
+
+ + 22°C +
+
晴れ
+
+
65%
+
3m/s
+
+
+
+
+ +
+
+
+ +
+
+

APIの結果 → アプリの画面

+

+ 上の天気アプリは、裏側で temperature: "22°C" や condition: "晴れ" というAPIレスポンスを受け取り、見やすいデザインに変換して表示しています。あなたが普段見ているきれいな画面の裏側では、こうしたAPIのやり取りが行われているのです。 +

+
+
+
+
+ + + + + +
+
+
+ +
+

身近なAPIの例 — 実はあなたも毎日使っている

+
+ +

+ 「API」と聞くとプログラマーの専門用語に聞こえるかもしれません。しかし、あなたがスマホで何気なくやっている日常の操作の裏側では、たくさんのAPIが動いています。「あなたが見ている画面」の裏側で、APIが何をしているのかを図解します。 +

+ +
+ +
+
+
+
東京
+
+ + 22°C +
+
晴れ
+
+
65%
+
3m/s
+
+
+
+
+

+ 天気予報アプリ +

+
裏側でAPIがやっていること
+

気象庁のサーバーに「東京の最新天気データをください」とリクエストを送り、気温・天候・湿度・風速などのデータをJSON形式で受け取っている

+
+
+ + +
+
+
アカウントにログイン
+
+
+ G +
+ Google でログイン +
+
+
+ または +
+
+
メールアドレスで登録
+
+
+

+ 「Googleでログイン」ボタン +

+
裏側でAPIがやっていること
+

GoogleのOAuth API（オーオース = 認可の仕組み）に「このユーザーの身元を確認してください」と問い合わせ、認証トークン（本人確認済みの証）を受け取っている

+
+
+ + +
+
+
+ +
+
お支払い完了
+
¥1,980
+
VISA **** 4242
+
+
+

+ オンライン決済 +

+
裏側でAPIがやっていること
+

Stripe等の決済APIが、クレジットカード会社のサーバーと暗号化通信を行い、与信確認（この人は支払える？）→ 決済処理 → 結果通知を実行している

+

出典: Stripe API 公式ドキュメント

+
+
+ + +
+
+
+
+
+
+
+ 現在地 +
+
+
+
+ + 東京駅 +
+
12分
+
+
+
+
+

+ 地図・ナビアプリ +

+
裏側でAPIがやっていること
+

Google Maps APIが地図画像の取得、現在の交通情報の取得、経路計算をそれぞれ別のAPIに問い合わせ、統合して表示している

+
+
+
+ +
+
+
+ +
+
+

気づきましたか？

+

+ 上の4つの例に共通しているのは、あなたがAPIの存在を意識していないということです。天気を確認するとき「今からAPIを呼ぶぞ」とは思いませんよね。優れたAPIは、ユーザーにその存在を感じさせません。まるで空気のように、裏側で静かに仕事をしているのです。 +

+
+
+
+
+ + + + + +
+
+
+ +
+

APIを使うとどう嬉しいか

+
+ +

+ ここまで読んで「APIは便利そうだ」と感じてもらえたと思います。では、開発者の視点から見たとき、APIを使うことで具体的にどのくらいの効果があるのか。数字と一緒に見てみましょう。 +

+ +
+
+
50回+
+
あなたが1日に
APIを使っている回数
+
+
+
24,000+
+
世界で公開されている
APIの数
+

出典: ProgrammableWeb

+
+
+
0.2秒
+
多くのAPIの
平均応答時間
+
+
+ +
+
+
+ +
+
+

開発スピードが上がる

+

決済、認証、地図、翻訳...。これらをゼロから作ると何ヶ月もかかりますが、APIを使えば数日〜数時間で実装できます。車を作りたいとき、エンジンから設計する必要はないのです。

+
+
+ +
+
+ +
+
+

品質が担保される

+

Google Maps、Stripe、AWSなど、各分野の専門企業が何千人体制で開発・運用しているAPIの品質は、個人や小さなチームで再現できるレベルではありません。その品質を「借りる」ことができます。

+
+
+ +
+
+ +
+
+

保守の手間が減る

+

API提供元がバグ修正・機能改善・セキュリティ更新を継続的に行ってくれます。あなたはAPIを「使うだけ」。自分でゼロから作った機能は、自分でずっと面倒を見続ける必要があります。

+
+
+ +
+
+ +
+
+

レゴのように拡張できる

+

APIはレゴブロックのように組み合わせられます。たとえば「翻訳API + 音声合成API」を組み合わせれば、多言語音声読み上げ機能が作れます。1つのAPIだけでは実現できない価値が、組み合わせで生まれるのです。

+
+
+
+
+ + + + + +
+
+
+ +
+

よくある誤解

+
+ +

+ APIについて学び始めると、多くの人が同じところでつまずきます。ここでは、初学者が陥りがちな3つの誤解を取り上げて、正しい理解に修正します。 +

+ +
+
+
+
+ +
+

誤解: 「APIはプログラマーだけが使うもの」

+
+
+
+
+ +
+
+

実際は:

+

+ あなたも毎日APIを使っています。朝、天気アプリを開く。SNSにログインする。電子マネーで買い物する。これらの操作はすべて、裏側でAPIが動いています。プログラマーが「APIを使う」のは、この仕組みのコードを書いている側にいるだけの話。気づかないうちにAPIの恩恵を毎日受けているのです。 +

+
+
+
+
+ +
+
+
+ +
+

誤解: 「APIって難しい技術でしょ？」

+
+
+
+
+ +
+
+

実際は:

+

+ APIの概念自体は「注文して結果を受け取る」というシンプルな仕組みです。レストランで注文できるなら、APIの概念は理解できます。先ほどのコード例のように、実際のプログラムも数行で書けることがほとんどです。難しいのはAPIそのものではなく、「APIで何を作るか」を考える部分。道具はシンプル、使いこなすセンスが問われるということです。 +

+
+
+
+
+ +
+
+
+ +
+

誤解: 「APIを使うと個人情報が漏れそうで怖い」

+
+
+
+
+ +
+
+

実際は:

+

+ 適切に設計されたAPIは、必要最小限の情報だけをやり取りします。たとえば銀行のAPIが口座残高を返す際、パスワードや暗証番号は一切含まれません。APIはデータの「窓口」であり、「何の情報を公開し、何を隠すか」を厳密に制御できます。むしろ、データベースに直接触るよりもAPIを介した方が安全なのです。レストランのたとえで言えば、お客さんが直接厨房に入るより、ウェイターを通した方が厨房の秩序が保たれるのと同じです。 +

+
+
+
+
+
+
+ + + + + +
+
+
+ +
+

まとめ — 覚えておきたい3つのこと

+
+ +

+ 長い図解を読んでいただきありがとうございます。最後に、この記事で伝えたかったことを3つに絞ってまとめます。 +

+ +
+
+
+
01
+
+

APIは「ソフトウェアの窓口」

+

+ レストランのウェイターのように、あなた（アプリ）とサーバーの間を取り持つ仲介役。相手の内部構造を知らなくても、決まったルール（インターフェース）で話しかければ結果が返ってきます。 +

+
+
+
+ +
+
+
02
+
+

あなたはすでにAPIユーザー

+

+ 天気予報、SNSログイン、地図検索、オンライン決済。気づかないうちに、あなたの日常はAPIに支えられています。APIは特別な人だけのものではなく、全員の生活を支える仕組みです。 +

+
+
+
+ +
+
+
03
+
+

APIで「車輪の再発明」がなくなる

+

+ すでにある優れた機能をAPIで借りることで、自分は「自分にしか作れない部分」に集中できます。開発スピードが上がり、品質も上がり、保守の手間も減る。これがAPIの最大の恩恵です。 +

+
+
+
+
+ +
+ +

APIは「知っている」だけで世界が広がる概念です。

+

+ 次にアプリを使うとき、「この裏側でどんなAPIが動いているんだろう？」と想像してみてください。天気予報の数字も、ログインボタンも、決済完了の画面も、すべてAPIが繋いでいます。テクノロジーの見え方が、少しだけ変わるはずです。 +

+
+
+ + +
+ + + + + diff --git a/.claude/skills/creating-visual-explainers/references/node-install-guide.md b/.claude/skills/creating-visual-explainers/references/node-install-guide.md new file mode 100644 index 0000000..7e4bf23 --- /dev/null +++ b/.claude/skills/creating-visual-explainers/references/node-install-guide.md @@ -0,0 +1,68 @@ +# Node.js インストールガイド + +SKILL.md の Step 5 で Node.js が未インストールだった場合に参照する。 + +## 説明と許可 + +以下をユーザーに伝え、インストールの許可を求める: + +> 図解の作成は完了しました。`output/` フォルダ内の HTML ファイルをブラウザにドラッグ＆ドロップすれば、今すぐ確認できます。 +> +> URLで公開するには「Node.js」のインストールが必要です。 +> Node.js は、パソコン上でプログラムを動かすための土台で、世界中で使われている安全な道具です。 +> **README にも記載の通り、AI-Driven School 運営が確認済みですので安心してください。** +> +> 今からインストールしてもよいですか？ + +ユーザーが許可しなかった場合 → ファイルの確認方法（生成された HTML ファイルをブラウザで開く）を伝えて終了。 + +## macOS の場合 + +インストーラーをダウンロードする: + +```bash +PKG_NAME=$(curl -sL https://nodejs.org/dist/latest-lts/ | grep -o 'node-v[0-9.]*\.pkg' | head -1) && curl -fsSL "https://nodejs.org/dist/latest-lts/${PKG_NAME}" -o /tmp/node-install.pkg && echo "ダウンロード完了: ${PKG_NAME}" +``` + +ダウンロード完了後、インストールを実行する**前に**以下を伝える: + +> インストールのために、パソコンのパスワードの入力が必要です。 +> これはパソコンにログインするときに使っているパスワードです。 +> 画面下のターミナル欄にパスワードを入力して Enter を押してください。 +> 入力中の文字は画面に表示されませんが、正常な動作です。 + +```bash +sudo installer -pkg /tmp/node-install.pkg -target / && rm /tmp/node-install.pkg +``` + +## Windows の場合 + +インストールを実行する**前に**以下を伝える: + +> インストール中に「このアプリがデバイスに変更を加えることを許可しますか？」という確認画面が表示されることがあります。 +> 「はい」を押してください。 + +```powershell +winget install OpenJS.NodeJS.LTS --accept-package-agreements --accept-source-agreements +``` + +インストール完了後、現在のターミナルで Node.js を使えるようにする: + +```powershell +$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User") +``` + +winget が使えない場合（「winget は認識されていません」と表示された場合）: + +```powershell +$msi = (Invoke-WebRequest -Uri "https://nodejs.org/dist/latest-lts/" -UseBasicParsing).Links.href | Where-Object { $_ -match "x64\.msi$" } | Select-Object -First 1; Invoke-WebRequest -Uri "https://nodejs.org/dist/latest-lts/$msi" -OutFile "$env:TEMP\node-install.msi" -UseBasicParsing; Start-Process msiexec.exe -ArgumentList "/i `"$env:TEMP\node-install.msi`"" -Verb RunAs -Wait; Remove-Item "$env:TEMP\node-install.msi" +``` + +## インストール完了の確認 + +```bash +node --version +``` + +バージョン番号が表示された → インストール成功。 +エラーが出た → Cursor を再起動してからもう一度試すよう案内する。 diff --git a/.claude/skills/creating-visual-explainers/scripts/deploy-diagram.sh b/.claude/skills/creating-visual-explainers/scripts/deploy-diagram.sh new file mode 100644 index 0000000..636cf5f --- /dev/null +++ b/.claude/skills/creating-visual-explainers/scripts/deploy-diagram.sh @@ -0,0 +1,58 @@ +#!/bin/bash +set -e + +HTML_FILE="${1:?使い方: deploy-diagram.sh [スラッグ]}" +SLUG="${2:-}" + +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +RED='\033[0;31m' +NC='\033[0m' + +if ! command -v node &>/dev/null; then + echo -e "${RED}エラー: Node.js がインストールされていません${NC}" >&2 + echo "Node.js をインストールしてから、もう一度試してください。" >&2 + exit 1 +fi + +if [ ! -f "$HTML_FILE" ]; then + echo -e "${RED}エラー: $HTML_FILE が見つかりません${NC}" >&2 + echo "先に図解を生成してください。" >&2 + exit 1 +fi + +if [ -n "$SLUG" ]; then + DOMAIN="diagram-${SLUG}.surge.sh" +else + DOMAIN="diagram-$(date +%y%m%d%H%M).surge.sh" +fi + +TEMP_DIR=$(mktemp -d) +trap 'rm -rf "$TEMP_DIR"' EXIT + +cp "$HTML_FILE" "$TEMP_DIR/index.html" +printf "User-agent: *\nDisallow: /\n" > "$TEMP_DIR/robots.txt" + +echo -e "${YELLOW}公開中...${NC}" +npx --yes surge "$TEMP_DIR" --domain "$DOMAIN" + +touch deploy-history.log +echo "$(date '+%Y-%m-%d %H:%M:%S') | https://${DOMAIN}" >> deploy-history.log + +echo "" +echo -e "${GREEN}完了！${NC}" +echo "URL: https://${DOMAIN}" + +if [[ "$OSTYPE" == "darwin"* ]]; then + echo "https://${DOMAIN}" | pbcopy + echo -e "${GREEN}URLをクリップボードにコピーしました${NC}" + open "https://${DOMAIN}" +elif command -v clip.exe &>/dev/null; then + echo -n "https://${DOMAIN}" | clip.exe + echo -e "${GREEN}URLをクリップボードにコピーしました${NC}" + start "https://${DOMAIN}" 2>/dev/null || true +elif command -v xdg-open &>/dev/null; then + xdg-open "https://${DOMAIN}" +fi + +echo -e "${YELLOW}削除するとき: npx surge teardown ${DOMAIN}${NC}" diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..2431bdc --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +output/*.html +deploy-history.log diff --git a/README.md b/README.md new file mode 100644 index 0000000..27e6a13 --- /dev/null +++ b/README.md @@ -0,0 +1,74 @@ +# パーソナル図解 + +自分の仕事に最適化された「パーソナル図解スキル」を作るためのツールキットです。 + +配布済みの図解ツールは汎用ツールですが、パーソナル図解スキルは違います。**あなたの仕事・あなたの読者に合わせた、あなた専用の図解ツール**です。 + +## フォルダの中身 + +``` +パーソナル図解/ +├── .claude/skills/ +│ ├── creating-skills/ ← スキルの作り方ガイド +│ └── creating-visual-explainers/ ← 図解を生成するスキル（配布済みの図解ツールと同じもの） +├── sample/ +│ └── majiai-diagram/ ← 模範解答（本気AIの図解スキル） +│ ├── .claude/skills/diagram-maji/ ← スキル本体 +│ └── docs/charactor-images/ ← キャラクター画像 +├── output/ ← 図解の保存先 +├── .gitignore +└── README.md ← この説明書 +``` + +| フォルダ | 説明 | +|---------|------| +| `.claude/skills/creating-skills/` | スキルの作り方ガイド。設計原則・パターン集・チェックリストが入っています | +| `.claude/skills/creating-visual-explainers/` | 図解HTMLを生成するスキル。配布済みの図解ツールと同じものです | +| `sample/majiai-diagram/` | 模範解答です。本気AIが実際に使っている図解スキルの構造がわかります | +| `output/` | 生成した図解の保存先 | + +## まず模範解答を見てみる + +`sample/majiai-diagram/.claude/skills/diagram-maji/` の中にある SKILL.md と references/ フォルダを開いて読んでみてください。 + +- **SKILL.md** — スキルの全体設計（どんな順番で何をするかのワークフロー） +- **references/** — デザインガイド、用語辞書、キャラクター設定など +- **docs/charactor-images/** — 図解に使うキャラクター画像 + +「スキルの中身はこうなっているんだ」と全体像をつかんでおくと、自分のスキルを作るときにスムーズです。 + +## パーソナル図解スキルの作り方 + +詳しい手順はポータルの課題ページに書かれています。ざっくりした流れは以下の通りです。 + +``` + ① ヒアリングシートを埋める + 「誰のどんな問題を解決するか」を言語化する + ↓ + ② AIにスキルを作ってもらう + ヒアリングシートをCursorに貼り付けて依頼する + ↓ + ③ 生成されたスキルを確認・修正する + 模範解答と見比べて、足りない部分を追加する + ↓ + ④ 図解を作って試す + 「○○を図解して」と依頼して、出力を確認する +``` + +## 図解を作る + +パーソナル図解スキルが完成したら、チャット欄で「○○を図解して」と依頼するだけです。 + +生成された図解は `output/` フォルダに保存されます。 + +## 図解を共有する + +PDF での共有方法や URL での公開方法は、配布済みの図解ツールと同じです。 +図解ツールの README を参照してください。 + +## 困ったとき + +何が起きても、まずはチャット欄で AI に状況を伝えてください。 +AI がエラーの内容を読み取り、次にやるべきことを教えてくれます。 + +解決しない場合は、ポータルの課題ページにあるトラブルシューティングを確認してください。 diff --git a/output/.gitkeep b/output/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/sample/majiai-diagram/.claude/skills/diagram-maji/SKILL.md b/sample/majiai-diagram/.claude/skills/diagram-maji/SKILL.md new file mode 100644 index 0000000..1f0de8f --- /dev/null +++ b/sample/majiai-diagram/.claude/skills/diagram-maji/SKILL.md @@ -0,0 +1,195 @@ +--- +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) diff --git a/sample/majiai-diagram/.claude/skills/diagram-maji/references/character-usage.md b/sample/majiai-diagram/.claude/skills/diagram-maji/references/character-usage.md new file mode 100644 index 0000000..8b150f6 --- /dev/null +++ b/sample/majiai-diagram/.claude/skills/diagram-maji/references/character-usage.md @@ -0,0 +1,166 @@ +# キャラクター利用ガイド + +## キャラクターの役割 + +| キャラクター | 役割 | 職業 | +|------------|------|------| +| **マジくん** | 読者の代弁者。技術に詳しくない視点で疑問を投げかける | マーケティングアシスタント（非エンジニア） | +| **マスター** | 導き手。本質を平易に説明する | 喫茶店マスター兼AI活用のプロ | + +--- + +## 表情の使い分け + +### マジくん（10種類） + +| 表情 | ファイル名 | 使用シーン | +|-----|----------|----------| +| 標準 | `マジくん-標準-512×512-透過.png` | 通常の発言 | +| 驚き | `マジくん-驚き-512×512-透過.png` | 新しい発見、「マジ？」 | +| マジ？ | `マジくん-マジ？-512×512-透過.png` | 心底驚いたとき | +| 調子に乗ってる | `マジくん-調子に乗ってる-512×512-透過.png` | 理解した気になっている | +| 疑っている | `マジくん-疑っている-512×512-透過.png` | 半信半疑、ケチをつける | +| 強く反発する | `マジくん-強く反発する-512×512-透過.png` | 納得いかない | +| 焦り | `マジくん-焦り-512×512-透過.png` | 困っている | +| ひどく慌てている | `マジくん-ひどく慌てている-512×512-透過.png` | パニック | +| 涙ぐむ | `マジくん-涙ぐむ-512×512-透過.png` | 落ち込み、感動 | +| 自信がない、落ち込んでいる | `マジくん-自信がない、落ち込んでいる-512×512-透過.png` | 失敗、挫折 | + +### マスター（4種類） + +| 表情 | ファイル名 | 使用シーン | +|-----|----------|----------| +| 標準 | `マスター-標準-512×512-透過.png` | 通常の説明 | +| 諭す | `マスター-諭す-512×512-透過.png` | 重要なポイント、本質を伝える | +| 思考、分析 | `マスター-思考、分析-512×512-透過.png` | 考え中、深い話 | +| 真顔 | `マスター-真顔-512×512-透過.png` | 厳しい指摘 | + +--- + +## 対話パターン + +### 1. 導入パターン（疑問→答え） + +```html + +
+ マジくん +
+

+ マジくん:
+ 「フック」って何ですか？プログラムに釣り針でも刺すんですか？ +

+
+
+ + +
+ マスター +
+

+ マスター:
+ 良い質問ですね。フックとは「割り込みポイント」のこと。 + 会社のセキュリティゲートを想像してください。 +

+
+
+``` + +### 2. 驚きパターン（発見の瞬間） + +```html +
+ マジくん +
+

+ マジくん:
+ マジ？
+ つまり、AIが何かする前に「ちょっと待って！」って止められるんですね！ +

+
+
+``` + +### 3. まとめパターン（理解の確認） + +```html +
+ マスター +
+

+ マスター:
+ その通りです。整理すると、フックには3つの役割があります。 +

+
+
+ +
+ マジくん +
+

+ マジくん:
+ これでボクも次期OpenAIのCEO候補ですね！ +

+
+
+``` + +--- + +## セリフの書き方 + +### マジくんの特徴 + +- **一人称**: 「ボク」 +- **基本**: 丁寧語（「〜です」「〜ます」） +- **反発時**: やや格式高い表現 +- **驚き**: 「マジ？」（心底驚いた時のみ単独で使用） +- **大袈裟な比喩**: 感情的になると誇張表現 + +``` +❌ 悪い例: 「すごいね！」「わかった！」 +✅ 良い例: 「これは人類の転換点かもしれません！」「ボクのキャリアに光が差しました！」 +``` + +### マスターの特徴 + +- **一人称**: 「私」 +- **口調**: 常に丁寧語、タメ口は使わない +- **説明**: たとえ話を必ず使う +- **名前呼び**: 「マジさん」 + +``` +❌ 悪い例: 「それは違う」「こうだ」 +✅ 良い例: 「その発言は、マジさんがまだ本質を理解できていない証拠ですね」 +``` + +--- + +## 配置ルール + +1. **対話シーンでは左右固定しない**: 上から順に配置 +2. **画像サイズ**: `w-20 h-20`（80px）が基本 +3. **吹き出しの向き**: 画像側に尖端 +4. **余白**: `gap-4`、`mb-6` で統一 + +--- + +## 画像パス + +HTML内での参照パス: + +```html +./images/マジくん-{表情}-512×512-透過.png +./images/マスター-{表情}-512×512-透過.png +``` + +デプロイ時にコピー元: + +``` +docs/design/charactor-images/square/512px/ +``` diff --git a/sample/majiai-diagram/.claude/skills/diagram-maji/references/exemplar.md b/sample/majiai-diagram/.claude/skills/diagram-maji/references/exemplar.md new file mode 100644 index 0000000..f16a3e5 --- /dev/null +++ b/sample/majiai-diagram/.claude/skills/diagram-maji/references/exemplar.md @@ -0,0 +1,230 @@ +# 模範解答パターン + +## 成功する図解の構造 + +``` +1. ヘッダー（グラデーション背景） + └─ タイトル + サブタイトル + +2. 導入（キャラクター対話） + └─ マジくん: 「〇〇って何ですか？」 + └─ マスター: たとえ話で概要説明 + +3. 用語解説ボックス + └─ 最初に出てくる技術用語を全て解説 + +4. まず覚える3つ + └─ 絞り込んだ最重要ポイント + └─ 重要度バッジ（必須/推奨/任意） + +5. 各セクション詳細 + └─ セクションカード形式 + └─ Lucide iconでビジュアル化 + └─ たとえ話で補足 + └─ コード例の前に日本語解説 + +6. まとめ（キャラクター対話） + └─ マスター: 要点を3つで整理 + └─ マジくん: 理解の確認 + +7. 目次（フローティング） + └─ デスクトップのみ表示 +``` + +--- + +## 「まず覚える3つ」の書き方 + +```html +
+
+
+ +
+
+

まず覚える3つ

+

最初はこれだけでOK！

+
+
+ +
+ +
+
1
+
+
+ PreToolUse + 必須 +
+

ツールが実行される前にチェック。「本当にやっていい？」と確認する門番。

+
+
+ + +
+
2
+
+
+ PostToolUse + 推奨 +
+

ツールが実行された後に確認。結果をログに残したり、通知を送ったり。

+
+
+ + +
+
3
+
+
+ Stop + 任意 +
+

AIが作業を終えるとき。「お疲れ様、次はこれをやってね」とフォローアップを追加。

+
+
+
+
+``` + +--- + +## たとえ話の展開パターン + +### パターン1: 会社のセキュリティゲート + +```html +
+
+ + たとえ話：会社のセキュリティゲート +
+
+

あなたが会社に出勤するとき、入口にはセキュリティゲートがありますよね。

+
    +
  • 社員証をかざす → 本人確認（PreToolUse）
    • +
  • ゲートが開く → 許可された行動が実行される
    • +
  • 入館記録が残る → ログ記録（PostToolUse）
    • +
+

フックは、このセキュリティゲートのような役割をプログラムの中で果たします。

+
+
+``` + +### パターン2: スマホの権限ダイアログ + +```html +
+
+ + たとえ話：スマホの権限ダイアログ +
+
+

スマホでアプリを使うとき、こんな画面を見たことありませんか？

+
+ 「カメラへのアクセスを許可しますか？」
+ [許可する] / [許可しない] +
+

これがまさにPreToolUseの動き！

+
    +
  • 許可する → allow（実行OK）
    • +
  • 許可しない → deny（実行NG）
    • +
  • 毎回確認する → ask（ユーザーに聞く）
    • +
+
+
+``` + +--- + +## 詳細セクションの書き方 + +```html +
+ +
+
+ +
+
+

PreToolUse

+

ツール実行前のチェックポイント

+
+
+ + +
+ マジくん +
+

「Pre」って「前」という意味ですよね？つまり、ツールを使う前に何かするってことですか？

+
+
+ +
+ マスター +
+

その通りです。AIが何かツールを使おうとしたとき、実行する前に「ちょっと待って」と割り込めるポイントです。

+
+
+ + +
+

+ + 何ができるの？ +

+
    +
  • + + 特定のツールの使用を禁止できる +
    • +
  • + + ツールに渡す入力内容を変更できる +
    • +
  • + + ユーザーに確認を求めることができる +
    • +
+
+ + +
+
+ + このコードがやること +
+

+ 「Writeツール（ファイルを書き込む道具）」が使われそうになったら、 + 許可しないというルールを設定しています。 +

+
+ 
hook.onPreToolUse((event) => {
+  if (event.toolName === 'Write') {
+    return { permissionDecision: 'deny' };
+  }
+});
+
+
+
+``` + +--- + +## 品質チェックリスト + +作成後、以下を確認： + +- [ ] 全ての技術用語に用語解説ボックスがある +- [ ] たとえ話が3つ以上ある +- [ ] 導入・中間・まとめにキャラクター対話がある +- [ ] 「まず覚える3つ」がある +- [ ] コード例の前に「このコードがやること」がある +- [ ] Lucide iconのみ使用（絵文字なし） +- [ ] 本気AIブランドカラーが適用されている +- [ ] キャラクター画像のパスが正しい +- [ ] スマホで読みやすい（レスポンシブ） +- [ ] 目次がフローティング表示される（デスクトップ） diff --git a/sample/majiai-diagram/.claude/skills/diagram-maji/references/html-structure.md b/sample/majiai-diagram/.claude/skills/diagram-maji/references/html-structure.md new file mode 100644 index 0000000..aae7f9c --- /dev/null +++ b/sample/majiai-diagram/.claude/skills/diagram-maji/references/html-structure.md @@ -0,0 +1,280 @@ +# HTML構造ガイド + +## 基本テンプレート + +```html + + + + + + 【図解タイトル】- 本気AI + + + + + + + + +
+
+

【タイトル】

+

サブタイトル

+
+
+ + +
+ +
+ + + + + +``` + +--- + +## Lucide Icon の使い方 + +### 基本構文 + +```html + +``` + +### よく使うアイコン + +| 用途 | アイコン名 | コード | +|-----|----------|--------| +| 重要 | `alert-circle` | `` | +| ヒント | `lightbulb` | `` | +| チェック | `check-circle` | `` | +| 情報 | `info` | `` | +| 警告 | `triangle-alert` | `` | +| 設定 | `settings` | `` | +| コード | `code` | `` | +| ファイル | `file-text` | `` | +| フォルダ | `folder` | `` | +| 矢印 | `arrow-right` | `` | +| ユーザー | `user` | `` | +| ロック | `lock` | `` | +| 鍵 | `key` | `` | +| 許可 | `shield-check` | `` | +| 禁止 | `shield-x` | `` | +| 質問 | `help-circle` | `` | +| 本 | `book-open` | `` | +| 学習 | `graduation-cap` | `` | +| ツール | `wrench` | `` | +| プレイ | `play` | `` | +| 停止 | `square` | `` | + +### セクションヘッダーでの使用例 + +```html +
+
+
+ +
+
+

セクションタイトル

+

サブタイトル

+
+
+ +
+``` + +--- + +## コード例の前の日本語解説 + +コードを見せる前に、必ず「このコードが何をするのか」を日本語で説明する。 + +### ❌ 悪い例 + +```html +
+ 

+hook.onPreToolUse((event) => {
+  if (event.toolName === 'Write') {
+    return { permissionDecision: 'deny' };
+  }
+});
+
+
+``` + +### ✅ 良い例 + +```html +
+
+ + このコードがやること +
+

+ 「Writeツール（ファイルを書き込む道具）が使われそうになったら、 + 許可しない」というルールを設定しています。 +

+
+
+ 

+hook.onPreToolUse((event) => {
+  if (event.toolName === 'Write') {
+    return { permissionDecision: 'deny' };
+  }
+});
+
+
+``` + +--- + +## フローチャートの表現 + +```html +
+
+ +
開始
+
+ + +
+ +
チェック
+
+ + +
+ +
完了
+
+
+``` diff --git a/sample/majiai-diagram/.claude/skills/diagram-maji/references/term-dictionary.md b/sample/majiai-diagram/.claude/skills/diagram-maji/references/term-dictionary.md new file mode 100644 index 0000000..f41885c --- /dev/null +++ b/sample/majiai-diagram/.claude/skills/diagram-maji/references/term-dictionary.md @@ -0,0 +1,100 @@ +# 技術用語→やさしい言葉 変換辞書 + +## 変換の原則 + +1. **機能で命名する**: 「何をするものか」で名前をつける +2. **身近な比喩を添える**: 日常生活での類似物を示す +3. **初出時に解説ボックス**: 最初に出てきたとき必ず説明 + +--- + +## よく使う変換表 + +### プログラミング基礎 + +| 技術用語 | やさしい言葉 | たとえ | +|---------|------------|--------| +| コールバック関数 | チェック係 | 「何かあったら呼んでね」と登録しておく処理。電話の折り返しと同じ | +| API | 窓口 | 銀行の窓口。決まった書類を出すと、決まったサービスを受けられる | +| インターフェース | 約束事 | 「この形式で頼めば対応します」というルール | +| パラメータ | 指示内容 | 注文票に書く内容 | +| 引数 | 渡す情報 | 窓口に提出する書類 | +| 戻り値 | 受け取る結果 | 窓口から返ってくる書類 | +| 変数 | 名前付きの箱 | ラベルを貼った引き出し | +| 関数 | 処理の塊 | 自動販売機（入れると出てくる） | + +### 非同期・イベント + +| 技術用語 | やさしい言葉 | たとえ | +|---------|------------|--------| +| 非同期処理 | 待たずに進む処理 | レストランで注文後、席で待つ。厨房の前で立ち尽くさない | +| イベント | きっかけ | ドアベルが鳴る、ボタンを押す | +| リスナー | 見張り役 | インターホンの前で待機している人 | +| トリガー | 発動条件 | 「このボタンを押したら」という条件 | +| フック | 割り込みポイント | 会社のセキュリティゲート | +| ハンドラ | 対応係 | イベントが起きたとき対応する担当者 | + +### データ・構造 + +| 技術用語 | やさしい言葉 | たとえ | +|---------|------------|--------| +| JSON | データの書き方 | 住所録の書式 | +| オブジェクト | 情報のまとまり | 名刺1枚（名前、電話番号、住所がセット） | +| 配列 | 順番付きリスト | 番号札のついた待合室の椅子 | +| スキーマ | 設計図 | 入力フォームの項目一覧 | +| バリデーション | 入力チェック | 書類の不備確認 | + +### セキュリティ・権限 + +| 技術用語 | やさしい言葉 | たとえ | +|---------|------------|--------| +| 認証 | 本人確認 | パスポートを見せる | +| 認可 | 許可 | 「この部屋に入っていいですよ」というOK | +| トークン | 入場券 | 映画のチケット | +| セッション | 接続状態 | 電話がつながっている間 | +| パーミッション | 権限 | 「閲覧OK、編集NG」のような許可レベル | + +### AI・エージェント + +| 技術用語 | やさしい言葉 | たとえ | +|---------|------------|--------| +| プロンプト | 指示文 | AIへの依頼書 | +| ストリーミング | 逐次表示 | 手紙を1文字ずつ読み上げる | +| コンテキスト | 文脈・前提情報 | 会話の流れ、今までの話 | +| エージェント | 自動で動くAI | 自分で判断して動く秘書 | +| ツール | AIが使える道具 | 秘書が使えるファイル、電話、パソコン | + +--- + +## 用語解説ボックスの書き方 + +```html +
+
+ +
+
「コールバック関数」とは？
+
+ 難しそうな名前ですが、要は「呼び出されたときに実行される処理」のこと。
+ 電話の「コールバック（折り返し電話）」と同じで、「何かあったら呼んでね」と登録しておく処理です。
+ この図解では「チェック係」と呼びます。 +
+
+
+
+``` + +### CSS + +```css +.term-explain { + background: linear-gradient(135deg, #f3e8ff 0%, #e9d5ff 100%); + border-left: 4px solid #9333ea; + padding: 1.5rem; + border-radius: 0.75rem; + margin: 1.5rem 0; +} +.term-word { + color: #7c3aed; +} +``` diff --git a/sample/majiai-diagram/docs/charactor-images/マジくん-ひどく慌てている-512×512-透過.png b/sample/majiai-diagram/docs/charactor-images/マジくん-ひどく慌てている-512×512-透過.png new file mode 100644 index 0000000..e852845 Binary files /dev/null and b/sample/majiai-diagram/docs/charactor-images/マジくん-ひどく慌てている-512×512-透過.png differ diff --git a/sample/majiai-diagram/docs/charactor-images/マジくん-マジ？-512×512-透過.png b/sample/majiai-diagram/docs/charactor-images/マジくん-マジ？-512×512-透過.png new file mode 100644 index 0000000..b2e55dc Binary files /dev/null and b/sample/majiai-diagram/docs/charactor-images/マジくん-マジ？-512×512-透過.png differ diff --git a/sample/majiai-diagram/docs/charactor-images/マジくん-強く反発する-512×512-透過.png b/sample/majiai-diagram/docs/charactor-images/マジくん-強く反発する-512×512-透過.png new file mode 100644 index 0000000..0fa8427 Binary files /dev/null and b/sample/majiai-diagram/docs/charactor-images/マジくん-強く反発する-512×512-透過.png differ diff --git a/sample/majiai-diagram/docs/charactor-images/マジくん-標準-512×512-透過.png b/sample/majiai-diagram/docs/charactor-images/マジくん-標準-512×512-透過.png new file mode 100644 index 0000000..4fff766 Binary files /dev/null and b/sample/majiai-diagram/docs/charactor-images/マジくん-標準-512×512-透過.png differ diff --git a/sample/majiai-diagram/docs/charactor-images/マジくん-涙ぐむ-512×512-透過.png b/sample/majiai-diagram/docs/charactor-images/マジくん-涙ぐむ-512×512-透過.png new file mode 100644 index 0000000..b4f839c Binary files /dev/null and b/sample/majiai-diagram/docs/charactor-images/マジくん-涙ぐむ-512×512-透過.png differ diff --git a/sample/majiai-diagram/docs/charactor-images/マジくん-焦り-512×512-透過.png b/sample/majiai-diagram/docs/charactor-images/マジくん-焦り-512×512-透過.png new file mode 100644 index 0000000..bb1e1b0 Binary files /dev/null and b/sample/majiai-diagram/docs/charactor-images/マジくん-焦り-512×512-透過.png differ diff --git a/sample/majiai-diagram/docs/charactor-images/マジくん-疑っている-512×512-透過.png b/sample/majiai-diagram/docs/charactor-images/マジくん-疑っている-512×512-透過.png new file mode 100644 index 0000000..3737c1f Binary files /dev/null and b/sample/majiai-diagram/docs/charactor-images/マジくん-疑っている-512×512-透過.png differ diff --git a/sample/majiai-diagram/docs/charactor-images/マジくん-自信がない、落ち込んでいる-512×512-透過.png b/sample/majiai-diagram/docs/charactor-images/マジくん-自信がない、落ち込んでいる-512×512-透過.png new file mode 100644 index 0000000..8bc6a2a Binary files /dev/null and b/sample/majiai-diagram/docs/charactor-images/マジくん-自信がない、落ち込んでいる-512×512-透過.png differ diff --git a/sample/majiai-diagram/docs/charactor-images/マジくん-調子に乗ってる-512×512-透過.png b/sample/majiai-diagram/docs/charactor-images/マジくん-調子に乗ってる-512×512-透過.png new file mode 100644 index 0000000..392f967 Binary files /dev/null and b/sample/majiai-diagram/docs/charactor-images/マジくん-調子に乗ってる-512×512-透過.png differ diff --git a/sample/majiai-diagram/docs/charactor-images/マジくん-驚き-512×512-透過.png b/sample/majiai-diagram/docs/charactor-images/マジくん-驚き-512×512-透過.png new file mode 100644 index 0000000..5d60548 Binary files /dev/null and b/sample/majiai-diagram/docs/charactor-images/マジくん-驚き-512×512-透過.png differ diff --git a/sample/majiai-diagram/docs/charactor-images/マスター-思考、分析-512×512-透過.png b/sample/majiai-diagram/docs/charactor-images/マスター-思考、分析-512×512-透過.png new file mode 100644 index 0000000..9400560 Binary files /dev/null and b/sample/majiai-diagram/docs/charactor-images/マスター-思考、分析-512×512-透過.png differ diff --git a/sample/majiai-diagram/docs/charactor-images/マスター-標準-512×512-透過.png b/sample/majiai-diagram/docs/charactor-images/マスター-標準-512×512-透過.png new file mode 100644 index 0000000..45298ab Binary files /dev/null and b/sample/majiai-diagram/docs/charactor-images/マスター-標準-512×512-透過.png differ diff --git a/sample/majiai-diagram/docs/charactor-images/マスター-真顔-512×512-透過.png b/sample/majiai-diagram/docs/charactor-images/マスター-真顔-512×512-透過.png new file mode 100644 index 0000000..086b809 Binary files /dev/null and b/sample/majiai-diagram/docs/charactor-images/マスター-真顔-512×512-透過.png differ diff --git a/sample/majiai-diagram/docs/charactor-images/マスター-諭す-512×512-透過.png b/sample/majiai-diagram/docs/charactor-images/マスター-諭す-512×512-透過.png new file mode 100644 index 0000000..ead3b51 Binary files /dev/null and b/sample/majiai-diagram/docs/charactor-images/マスター-諭す-512×512-透過.png differ