shwldshwld6 days ago

シードスクリプトはpackage.jsonとAI向けドキュメントに両方追記する

スクロール検証用にローカルDBへ大量データを投入するシードスクリプトを作ったとき、package.json の scripts に追加するだけでなく、AIエージェント向けのガイドドキュメントにも明記した。

// package.json
"scripts": {
  "seed:scroll": "bash scripts/seed-scroll-data.sh"
}

AIエージェントは package.json の scripts を参照することもあるが、「スクロール確認のためにデータを大量投入したい」という意図と使い方は、ドキュメントに書かないと推測できない。エージェント向けのガイド(例: docs/agent-guide.md)に「ローカルでスクロール検証する場合は bun run seed:scroll を実行する」のように目的ベースで書いておくと、エージェントが自律的に適切なコマンドを選べるようになる。

手順書的な書き方(「手順1: コマンドを実行する」)より、いつ使うか(「大量データが必要なスクロール検証時」)を先に書く方がエージェントの文脈マッチングに効く。

スクリプト自体も再実行可能(idempotent)に作るのがセット。INSERT OR IGNORE や prefix 付き DELETE で安全に何度でも実行できるようにしておくと、エージェントが気軽に呼べる。