eli5

ELI5

参照されている仕様や変更を、コードに詳しくない技術者が正確に理解できるよう、実態に即したイメージに置き換えます。平易な言葉で、精度はそのままに。説明を簡潔にしても、主張は変えません。

文体

成果物を、作業内容を知らない人にも読みやすくする必要があるとき、ほかのスキルはここを参照します。読者は技術者なので、擬似コードや厳密な主張は問題ありません。ただし、コードもセッション内のメッセージも読んでいません。差分も、トランスクリプトも、作業中に作られたラベルも知りません。ELI5 の文章を書くときは、次の点に従います。

• 抽象的な性質を説明するのではなく、きっかけとなるイベント、現在の動作、変更後（または実装されていない代替案）の動作を、一つの具体的なシナリオに沿って最初から最後まで説明します。
• 専門用語は、初めて使うときにすべて定義します。仕様、コード、セッション内で作られたラベルに頼ってはいけません。
• 正確な主張をたとえ話に置き換えず、小さく具体的な例を使います。
• 制御フロー、順序、タイミングを説明するときは、必要に応じて擬似コードを使います。「何かが起きるタイミング」を文章で説明すると、もっともらしく聞こえる一方で、抜けが隠れてしまいます。擬似コードを5行書けば、条件が明確になり、見落としたケースにも気づけます。実装ではなく、判断のレベルで書きます。つまり、実際の関数シグネチャではなく、条件とその順序を示します。説明に「〜の場合のみ」「〜の前に」「〜を除き」「〜するとすぐに」が含まれているのに、読者が2回目の呼び出しで何が起きるか説明できないなら、擬似コードが必要です。
• 判定基準：差分、仕様、トランスクリプトがなくても文章だけで内容が分かります。読者に「この部分を説明してください」と尋ねられるなら、要件を満たしていません。

ワークフロー

1. 参照されている成果物をすべて読み、仕様だけでは動作を把握できない場合は、現在の所有者も確認します。成果物が指定されていない場合は、セッションでの現在の変更（作業ツリーまたはブランチの差分）を説明します。現在存在するものと、提案にとどまるものを区別します。
2. 現在の設計が問題を引き起こす理由も含め、ユーザーまたは運用上の影響を通じて問題を説明します。
3. 解決策は、変更前と変更後の単純なデータフローとして説明します。各コンポーネントは、ファイル名や内部シンボルではなく、担う役割を紹介します。
4. スキーマと永続的な契約の変更を漏れなく列挙します。追加、変更、削除、リセット、意図的に変更しないものを含めます。保存データや読み取り側に影響する場合は、カーソルやワイヤーフォーマットの切り替えも含めます。スキーマ変更がない場合は、その旨を明記します。

出力

次の見出しをこの順序で使います。

1. Problem
2. Solution
3. Schema changes

最後に、変更後にユーザーが気づくことを短い一文で述べます。

ルール

• 挙動と境界を最初に説明します。実装名は、所有関係や契約を明確にする場合にのみ挙げます。
• 正式な記録と、派生インデックス、キャッシュ、要約、表示上のグループ分けを区別します。
• 破壊的なリセット、移行要件、互換性の挙動、結果整合性、意図的なデータ損失を明確に示します。
• スキーマ変更が運用上のもので、ユーザーから見えない場合も、省略してはいけません。