AI向けの文書に共通の心得

Agent SkillやCLAUDE.md・AGENTS.mdのように、AIが読んで従う文書を書く時は、以下の基準に従う。kuden:agent-skill skillとkuden:persistent-instructions skillに共通の心得で、Agent Skillに固有の基準はkuden:agent-skill skillに、ルール文書に固有の基準はkuden:persistent-instructions skillにある。

心得1. 読み手は賢いmodelである

文書を読んで実行するのは、文脈を読んで自分で判断できるmodelである。書くのは、modelが推論では到達できない事だけにする。プロジェクトや作者に固有の方針、隠れた制約、外からは見えない前提、やってみないと分からないgotchaがこれに当たる。

• 考えれば分かる判断を、防御的に明文化しない。edge caseの除外規定や、誤読を防ぐための但し書きを足さない
• 読解力の低いmodelに合わせて設計しない。文脈を読み取れないmodelは、文書が求める他の作業も実行できない
• 手順か例で目的が達成できるなら、背景説明を書かない。インシデントの話や、避けたい結果の説明がこれに当たる。gitの一般的な性質のように、考えれば分かる理由も書かない
• 比喩を書かない。読み手が比喩の別の側面を推論し、文の意味が曖昧になる

心得2. 実行するmodelに向けた事だけを書く

その方法を選んだ経緯や、試して却下した案は、commit messageやPR概要欄に書く。

心得3. 編集する時は、全体としての最善を目指す

既存の文書に手を入れる時、変更差分を小さく保とうとしない。足す内容を既存の節の末尾に継ぎ足すのではなく、その内容が最初からあったらどう書いたかを考える。構成を大きく変えて構わない。

心得4. レビュー指摘の採否

外部Agentやsubagentの指摘は、事実として正しくても、文書に書く価値があるとは限らない。指摘が正しいかの検証とは別に、採否を以下の問いで決める。

• 問1. 賢いmodelなら、その場で判断できる事ではないか
• 問2. 対象の文書の種類に固有の心得が、書かないと定めた物ではないか
• 問3. 実行するmodelではなく、将来の編集者に向けた事ではないか
• 問4. それが無いと、modelが実行に行き詰まる事ではないか

問1から問3に当たる指摘は採用しない。問4に当たる指摘は採用する。

採用しなかった指摘は、理由を添えてユーザーに報告する。