改修ガイド

ワンだふる (apps/suteki-bot) を変更するときに必ず守るルール。

1. このページ群を最初に読む。仕様の前提を踏まえてから着手する。
2. 層の責務を破らない。domain / application から Slack / KV の SDK を直接呼ばない。新しい外部依存は port を切ってから infrastructure で実装する。
3. TeamConfig のスキーマを変えるときは KV の互換性を考える。既存キーをマイグレーションするか、emptyTeamConfig で安全に default を返せる形にする。
4. Slack の権限を増やすときは README とこのドキュメント群の "Bot Token Scopes" を必ず更新する。Slack App 側の scope 追加 → 既存ワークスペースで再インストールが必要になる点も注意。
5. 署名検証を外さない・弱めない。公開 Worker なので /slack/events と /slack/commands は必ず verify-signature.ts を通す。検証前に副作用を起こさない。
6. 3 秒 ack を守る。イベント処理を fetch ハンドラで同期実行しない。重い処理は ctx.waitUntil に逃がし、event_id の重複排除を経由する。
7. プライベートチャンネルのスキップを外さない。notify-reaction.ts の channel?.isPrivate ガードはプライバシー上の不変条件。
8. シークレットを増やすときは 4 箇所: .dev.vars.example, wrangler.toml のコメント, index.ts の Env, そして 運用ページ の環境変数表。
9. テストを必ず書く。各層に対応する *.test.ts がある。
10. 改修後はこのドキュメント群を更新する。仕様変更がドキュメントに反映されないと改修ガイドが嘘になる。