CodexへWebサービスの改修を依頼するとき、単にいい感じに直してと書くと、削ってはいけない機能まで整理対象にされる可能性があります。このサイトでは、既存機能を温存しつつ、AdSense審査中だけ公開面を技術メディアへ切り替える必要がありました。そのため、仕様書には目的、制約、公開条件、完了条件を分けて書くようにしています。
今回の依頼で明示したこと
- 既存の管理機能やDBは削除しない
- 公開サイトからは旧テーマの要素を隠す
SITE_MODE=adsenseとENABLE_5CH_FEATURES=falseで切り替える- RSSとsitemapにレビュー済みの技術記事だけを出す
- 記事は一般論ではなく、実装と設定に基づいて改稿する
- AdSense合格を保証する表現は使わない
このように、やることだけでなく、やらないことを明示すると、既存機能を壊しにくくなります。特に個人開発のCMSでは、公開画面と管理画面が同じWorkerに入っているため、削除ではなく機能フラグで隠す方が安全でした。
完了条件を具体化する
完了条件は、実装者にも確認者にも分かる形で書きます。たとえば、公開記事だけが一覧に出る、noindex記事がsitemapに入らない、審査対象外URLがRSSに出ない、型チェックとテストが通る、といった条件です。今回の改善では、さらに review_status=reviewed の記事だけを公開条件に含めるようにしました。
事実確認できない記事を作らせない
AdSenseで有用性の低いコンテンツと判断された後の改稿では、AIに一般論を増やさせても改善になりません。仕様書には、架空のエラー、作業時間、PV、収益、審査通過を作らないことを書きました。確認できる材料は、src/index.ts、migrations/、wrangler.toml、gas/fetch_threads.gs、README、テストです。
テストまで依頼する理由
Codexに変更だけを依頼すると、動作確認が人間側に残ります。そこで、pnpm test、pnpm typecheck、必要に応じたローカル表示確認まで依頼に含めます。このリポジトリでは、公開URLのリダイレクト、RSS/sitemapの除外条件、コメント欄の停止、カテゴリ管理などをテストで見ています。
依頼文に入れるとよい項目
- 目的と背景
- 変更してよい範囲
- 壊してはいけない機能
- 公開条件と非公開条件
- 使ってよい一次情報
- 禁止する表現や創作
- テストと確認URL
- 最後に報告してほしい項目
Codexは、指示が具体的なほど既存コードに沿った改修をしやすくなります。今回のようにコンテンツ編集と実装変更が混ざる作業では、編集方針も仕様として書くことが重要でした。関連する改善記録は AdSense不承認後の改善ログ にまとめています。