AI開発
教訓ガイドは判断基準を書く—ファイル一覧だけで終わらせない
事故のあと残す文章は、「何が不合格で何が合格か」が主。どのファイルを触るかの一覧だけだと、次の人に伝わらない。
ミスや事故のあと、「同じ指摘を二度させない」ためにガイドを残します。ここでやりがちなのが、「どのファイルを開けばよいか」の一覧だけ書いて終わることです。読んでも「何が悪くて、次はどう判断すればよいか」が分かりません。この記事は、教訓を 判断基準 として残す書き方です。
この記事でわかること
- ファイル一覧だけのガイドが伝わらない理由
- 代わりに書くべきこと（状況・失敗・合格／不合格・手順）
- 「このプロジェクト専用の手順」をどこに書くか
- 出す前に自分で確認する観点
- 作業前にAIへ渡す入力（貼り付け文）
何が分かりにくいか
次のような文は、書いた本人以外には意味が薄いです。
- 「教訓を汎化する」「特定環境の地図にしない」（比喩だけで中身がない）
- 「実装の置き場」の見出しの下に、パスと関数名の表だけがある
- 「あのスクリプトを触れ」だけで、合格・不合格の基準がない
- タイトルが「現行だけ直すな」「履歴とラベルを混ぜるな」のように抽象語だけで、何の売値／何の履歴かが分からない（偽の汎化）
読者が知りたいのは、だいたい次です。
1.どんな場面の話か（タイトルだけで種類が分かること。不動産・情報メモ・定時バッチなどの種類名は残してよい） 2.何をやってはいけなかったか 3.次は何を合格／不合格とするか 4.直すときはどの順でやるか
ファイルの場所は、必要ならあとから一行添えれば足ります。
代わりにこう書く
記事の芯は、次の順がわかりやすいです。
- 状況: 画面や作業で、何と何が並ぶか／何が起きやすいか
- 失敗の型: なぜそのまま出したくなるか（短くしたつもり、など）
- 悪い例／良い例: 具体的な文。パターンが分かればよい
- 合格条件: チェックできる文（例: 見出しを消しても要約に情報が残るか）
- 是正の手順: 同型をまとめて直す、同じ失敗を規範に残す、読者の画面で確認する
比喩やスローガンより、不合格の実例一文の方が伝わります。
「このプロジェクトだけの手順」は分けて書く
公開ガイドの主役は、他の人や次の作業でも使える判断基準です。
- 公開ガイド: 合格／不合格、悪い例、手順の型
- 手元の運用メモやエージェント向け短いルール: 「今のツリーではこのコマンドを先に走れ」など
どうしても今の環境のパスが必要なら、見出しを「参考（この環境）」にし、パスを消しても本文の主張が残るようにします。
出す前の確認
- 「どのファイルか」だけで終わっている章がないか
- パスを全部消しても、合格／不合格が残るか
- タイトル／descriptionだけで場面が分かるか（抽象語だけの偽汎化になっていないか）
- 初めて読む人が、同じ失敗を避けられるか
- 機械チェックがあるなら、通してから出す
## 作業前にAIへ渡す入力があり、AI向け（貼り付け文）と人間向け（原則なし）が明示されているか
作業前にAIへ渡す入力
人間向けの長い手順は書きません。次はすべて、作業前に AIに読ませる／貼る文 です。
AI向け：永続ルール（rules / AGENTS.md）
公開ガイド（draft: false）は次を満たすこと:
1. 芯は状況・失敗・悪い例／良い例・合格条件・是正手順。パス一覧だけで終わらせない
2. 「実装の置き場（このリポ）」だけで本文が終わらない
3. タイトルに場面が残る（種類名は残す。現行／履歴／正本だけの偽汎化は不合格）
4. ## 作業前にAIへ渡す入力 を置き、AI向け（永続ルール＋開始時に貼る文）と人間向け（原則なし）を明示する
5. 「ルールに残せ」だけ書いて残す文言が無い記事は不合格
draft: false 前に npm run check:prepublish を通すAI向け：この作業の開始時にチャットへ貼る文
教訓ガイドを書いて。判断基準（合格／不合格）が主。パス一覧だけで終わらせるな。
## 作業前にAIへ渡す入力 を置き、AI向けに rules 用の文と、この種の作業の開始時に貼る文をコードフェンスで書け。人間向けの長い手順は「なし」でよい。人間向け
なし。上をAIに渡すだけでよい。