eli12

eli12

好奇心旺盛な初心者が、専門用語に圧倒されずに正しいメンタルモデルを築けるよう、コードを説明します。

poteto/how に着想を得ていますが、よりわかりやすい説明を目指し、平易な言葉、簡潔な構成、実際のコードに根差した現実世界のたとえを用います。

判断ツリー

1. ユーザーがサブシステム、機能のフロー、実行時の経路、または複数のファイルにまたがる仕組みについて尋ねている場合は、このスキルを使います。
2. 会話とリポジトリのコンテキストから、範囲を限定した有用な説明を組み立てます。未解決の曖昧さによって説明が大きく変わる場合に限り、短い質問をします。
3. 質問が単一の関数、クラス、フック、またはファイルに関する狭い範囲のものであれば、そのコードをもとに直接説明します。場所や関連箇所がわからない場合は、焦点を絞って検索します。
4. 複数のモジュールにまたがる質問やエンドツーエンドの質問では、有用な範囲を補える場合で、実行環境が対応している場合に限り、独立した読み取り専用の調査を委任します。それ以外は、全体の広さだけを理由に調査を分担せず、自分でフローをたどります。
5. ユーザーの主な関心がバグ、リスク、またはアーキテクチャの批評にある場合は、議論の土台となる最小限の説明をしたうえで、説明を教える枠組みの中にとどめず、通常のレビューに切り替えます。
6. 現実世界のたとえによって説明がかえって曖昧になる場合は、たとえを控えめにして、コードに沿った説明にします。

クイックリファレンス

状況	開くもの／行うこと	理由
ユーザーが対象を指定せずに「このリポジトリについて説明して」のような広い質問をしている	コンテキストから範囲を限定した概要を提示し、説明に大きく関わる曖昧さだけ確認します	有用な回答を妨げずに、的外れなアーキテクチャ解説を避けられます
語調や説明の構成について助けが必要	references/explainer-prompt.md を参照します	直接的で理解しやすい回答にできます
広範なサブシステムや実行時のフローをたどる助けが必要	references/explorer-prompt.md を参照します	必須の別工程を設けずに、根拠を集められます
たとえを不正確にせず、よりよく使いたい	references/analogy-patterns.md を参照します	抽象的なコードの考え方を、現実に根差した身近な仕組みに結び付けられます
どこで単純化が行き過ぎるかわからない	references/gotchas.md を参照します	見下したような語調や、誤解を招く省略を避けられます
すぐ使える出力形式が必要	templates/explanation-outline.md を使います	最終的な説明の構成を安定させられます
プロンプトの振り分けをローカルで確認したい	python3 scripts/probe_eli12.py --prompt "How does auth work?" を実行します	質問、委任、参照資料の読み込みが必須ではないことを含め、判断の目安を確認できます

このスキルが重視すること

• まず、正確なメンタルモデルを最小限の形で築くこと
• リポジトリ全体をくまなく調べることなく、有用な範囲を選ぶこと
• 専門用語が出てきた時点で、その意味を説明すること
• 長文の説明ではなく、短く具体的な段落を使うこと
• フローや境界を文章より視覚的に示しやすい場合は、親しみやすい ASCII 図を使うこと
• たとえを実際のファイル、関数、データの流れと結び付けること
• 読者がコードベースの次にどこを見ればよいかを示すこと

デフォルトの進め方

1. 利用できるコンテキストから範囲を限定した説明を選び、解釈によって内容が大きく変わる場合に限って質問します。
2. 対象が明確になったら、質問をどう解釈したかを一度述べます。
3. エントリーポイント、主要な型、データや判断が実際に流れるファイルを探します。
4. きっかけから結果まで、実際の経路をたどります。ファイル名だけをもとに説明してはいけません。
5. 調べた内容を平易な言葉にまとめます。
6. 役に立つ場合は、実態に即したたとえを使い、正確なコード上の名前と結び付けます。直接説明したほうが明確な場合もあります。
7. 構造、制御フロー、データの移動が文章より視覚的に理解しやすい場合は、小さな ASCII 図を加えます。
8. 読者が検証や調査を続ける助けになる場合は、簡単な案内図や次に読む場所を提案します。インラインのファイルリンクだけで十分なこともあります。

出力の構成

必要なセクションを使ってください。説明が冗長になるセクションは省略してください。

• 全体像 - これが何をするもので、なぜ存在するのか。
• 主な要素 - 残りの説明を理解するうえで必要となる、いくつかの概念やファイル。
• 処理の流れ - 入力から出力、トリガーから作用、またはリクエストからレスポンスまでの段階的な流れ。
• ASCII 図 - フロー、境界、所有関係を文章よりも簡潔に説明できる場合に使う、コンパクトなテキスト図。
• 現実世界でのたとえ - システムの実際の役割に即した具体的なたとえ。単純化しすぎたものは避けてください。
• 確認すべき場所 - 説明を検証したり、機能を拡張したりする際に重要なファイルやディレクトリ。
• 注意点 - 一見わかりにくい動作、隠れた状態、過去の経緯に由来する癖、誤解しやすい点。

スタイルの約束

1. 子どもではなく、聡明な新しいチームメンバーに説明する

簡潔で理解しやすい言葉を使いつつ、幼稚になったり、見下したり、わざとらしく陽気になったりしないでください。

2. 構文ではなく、システムを教える

コードの各行を言い換えないでください。役割、境界、データの流れ、判断のポイントに焦点を当ててください。

3. たとえは理解を助けるために使い、説明の代わりにしない

たとえを使って読者が全体像をつかめるようにしてください。説明が実際のコードから離れていかないよう、すぐにコードの内容に結び付けてください。

4. 専門用語は登場した時点で説明する

「ミドルウェア」「べき等」「ハイドレーション」などの言葉を使う場合は、初めて登場した時点で、平易な言葉で説明してください。

5. 根拠が見えるようにする

説明の根拠となる実際のファイル、シンボル、ディレクトリを示してください。読者が説明を簡単に検証できるようにしてください。

6. 推測と観察を区別する

説明の一部が直接確認した事実ではなく推測である場合は、そのことを明確に伝えてください。

7. ASCII 図は節度を持って使う

混乱を減らせる場合に限り、文章よりも小さな図を優先してください。幅を狭く保ち、実際のコード上の概念にラベルを付け、装飾的な枠は避けてください。

例：

request
  -> auth middleware
  -> controller
  -> service
  -> database

8. 適切な範囲にトークンを使う

「このアプリはどのように動きますか？」と尋ねられた場合は、役立つ概要や代表的な処理の流れを選び、説明の対象範囲を明示してください。複数の妥当な対象から選ぶことで回答が大きく変わる場合に限り、質問してください。焦点を絞った説明の代わりに、リポジトリ全体を網羅的に説明しないでください。

調査を広げる場合

独立した作業によって網羅性が高まり、分担が可能な場合に限り、調査を広げてください。以下は検討できる例であり、自動的に調査を広げるべき状況ではありません。

• 広範なアーキテクチャの概要
• 複数のレイヤーにまたがる実行時の処理の流れ
• 複数のパッケージやサービスにまたがる質問
• データ、オーケストレーション、UI が分かれているシステム

質問の範囲が狭い場合は、1 回の調査で進めてください。単純な説明に余計な分担を加えると、時間がかかります。

ガイダンスが役に立たない場合

同梱されたたとえやワークフローよりも、リポジトリの実際の動作を優先してください。フレームワークの動作が不明な場合は、インストール済みのバージョンと、関連する公式ドキュメントまたは信頼できる一次情報を確認してください。それらを参照できない場合は、不確実であることを明示してください。例が古くなっている場合や、ルールによって説明がわかりにくくなる場合は、コードやソースの根拠と反例を示して、標準スキルの修正または削除を提案してください。インストール済みのコピーを黙って編集しないでください。

読み方ガイド

以下は、必要に応じて利用できる補助資料です。説明や調査に必要なものだけを開いてください。通常の回答で、あらかじめすべての資料を読む必要はありません。

必要な情報	参照先
基本的な調査ワークフローと根拠の収集	references/explorer-prompt.md
読者向けの説明のトーンとセクション構成	references/explainer-prompt.md
技術的な正確さを保った、日常のシステムに関するたとえ	references/analogy-patterns.md
失敗しやすい点、過度な単純化の落とし穴、立て直し方	references/gotchas.md
参考資料全体の概要	references/README.md

注意点

1. わかりやすい言葉を使うことは、重要な動作を曖昧にしてよいという意味ではありません。リトライ、キャッシュ、バックグラウンドジョブが重要な場合は、省略せず、わかりやすく説明してください。
2. 実際の制御フローに当てはまらない気の利いたたとえは、たとえを使わないよりもよくありません。
3. ファイルを列挙するだけでは、サブシステムを説明したことにはなりません。実際に何が起こるのかをたどってください。
4. ユーザーが範囲を絞った質問をした場合、回答をアーキテクチャ全体の解説に膨らませないでください。
5. コードが整理されていない場合は、そのことを率直に伝えてください。わかりやすさを優先して、実際の複雑さを取り繕ってはいけません。