AI Operations & Prompt Guide

タスクの種類ごとに、先に読む正本と、確認するページを決めています。迷ったら Project Architecture Guide の Source of Truth Map へ。

• Content（本文作成・下書き）

  読む: agent content-policy.md ＋ 対象領域の sources/

  確認: 既存の類似ページ・/content-architecture

• Research（調査・ソース取り込み）

  読む: agent workflows/source-intake.md

  確認: Notion Source Index・agent sources/

• UI（画面・コンポーネント変更）

  読む: agent ux-design-system.md ＋ サイトリポ現行コード

  確認: /design-system・実画面（PC/スマホ幅）

• Review（原稿・実装レビュー）

  読む: agent content-policy.md・対象の正本

  確認: 出典・確認日・リンク・表示

• Update（既存コンテンツ更新）

  読む: agent workflows/entry-correction-update.md

  確認: 対象ページの現行本文・frontmatterの確認日

• Quality Control（品質確認）

  読む: agent workflows/publish-check.md

  確認: /site-reference（orphan・タグゆれ・非公開）

• Site Diagnostics（構造確認）

  読む: src/app/ 現行コード

  確認: /sitemap-view・/site-reference

どのタスクでも、着手前に揃える文脈。古い文書から現行コードを推測して上書きしないこと。

• Startup Documents: agent AGENTS.md の Startup Reading（毎回）
• Task-specific Documents: 上のTask Routingに従い、該当する正本だけ追加で読む
• Current Code: サイト実装ではサイトリポジトリの現行コードを先に確認する（実在ルート・UI・トークンはコードが基準）
• Sources: 事実を書くときは agent sources/ と一次情報
• Existing Content: 同種の既存ページ・エントリーの構成に合わせる
• Repository Responsibilities: どのリポジトリ・保存先に書くべきかを Content Architecture で確認する

AIへの依頼文の共通骨格。タスク別の完成テンプレートは今後 agent workflows/ 側で整備します（Draft）。

目的（Goal）: 何を達成するか1文で
範囲（Scope）: 対象ページ・ファイル・やらないこと
必須ソース（Required Sources）: 参照すべき正本・一次情報
既存ファイル（Existing Files）: 確認・踏襲する現行実装
出力先（Output Destination）: 書き込むリポジトリ・パス
制約（Constraints）: 変更禁止事項・依存追加可否
完了条件（Completion Conditions）: 何を満たしたら完了か

依頼側（人間）が揃える入力。欠けている場合、AIは推測せず確認するか、仮定を明示します。

• Goal・Scope が明確であること（「いい感じに」を避ける）
• Required Sources: 事実系タスクでは出典の指定または調査許可
• Output Destination: サイトリポ / エージェントリポ / Notion のどれに書くか
• Constraints: 触ってはいけないファイル・未コミット変更の有無
• Completion Conditions: lint / build / 表示確認など検証範囲

AIの成果物が満たす形式。

• File Format: エントリーはfrontmatter＋GFM（templates/entry.md 準拠）。文書はMarkdown
• Required Metadata: title・entry_type・tags・listing_status など必須frontmatter
• Source Links / Verification Date: 事実には出典と確認日（YYYY-MM-DD）を付ける
• Change Summary: 変更ファイル・意図・影響範囲を報告する
• Deferred Items: 見送った項目・未解決の論点を明示する

出典の扱い。詳細の正本は agent content-policy.md と workflows/source-intake.md。

• Primary Sources: 公式サイト・広報など一次情報を優先し、まとめサイトを根拠にしない
• Verification: 公開前に一次情報で再確認し、verified_date を更新する
• High-risk Information: 医療・防災・お金・法務は必ず一次情報＋人のレビュー
• Rewriting: 転載せず自分の言葉で要約する。権利不明の画像・文章は使わない

コンテンツを画面でどう伝えるかの選択。パターン定義の正本は Design System の Presentation Patterns（現状は共通構造のみ・Planned）。

• 手続き・申請の説明 → Procedure（概要・対象者・必要なもの・手順・期限・問い合わせ）
• 施設・店舗の紹介 → Facility Profile（place エントリーの骨格）
• 日時があるもの → Event（event エントリーの骨格）
• 緊急時の行動 → Emergency Action（防災・救急。広告なし・最上部固定）
• 選択肢の比較 → Comparison / よくある疑問 → FAQ

一覧は Design System › Presentation Patterns へ。 選択の考え方の正本は CIPValue Framework（Context × Information × Presentation → Value）です。 AIはCIPValueそのものではなく、Context整理・Pattern選択・構成・検証を行う利用者・オーケストレーターとして使います。

情報提供フォームやソースの内容から、AIがコンテンツブロック（Content Blocks for Entry）のRegistryを参照して「エントリ本文をどう構成するか」を提案する型付き計画。正本化（下書き）工程の内部成果物で、本番表示時にAIは呼びません。

流れ: 信頼済み入力台帳（expectedInputs）をAIの計画作成前に確定（sourceRef・公開可否・情報源区分・公式か・公式URL）→ Context・Risk・Intended Value を整理 → Registry から block を選び EntryPresentationPlan を作成 → 決定論的 validator（validatePresentationPlan(plan, expectedInputs)）にかける → 人が確認 → 承認後に content/entries/*.md へ反映。 情報の完全性の根拠は AI出力ではなく expectedInputs 側に置き、AIが台帳の情報を落とす/台帳に無いsourceRefを足すと error になります。 型・validator の正本は src/lib/entry-content/presentation-plan.ts、block一覧は Design System › コンテンツブロック、 正本化workflowはエージェントリポ workflows/entry-presentation-plan.md。

AIが行うこと

• 入力のTask・Situation・Risk・Intended Value を整理する
• Registry の current block から構成と表示順を提案する（sourceRefごとに配置先と理由を残す）
• frontmatter / 本文block / 標準Markdown / merged / hold / private / omit へ全入力を割り当てる
• 既存blockで安全に表せない情報は component gap として申し送る（情報は捨てない）
• high-risk では公式確認導線・出典・確認日を保持する

AIが行ってはいけないこと

• 元情報にない事実・価格・日時・評価・推薦を補わない
• 既存UIに合わせて情報を黙って捨てない
• スポンサー・協賛を推薦や品質保証へ変換しない
• 固定hero・基本情報・地図・出典・訂正導線を消す/本文へ複製しない
• frontmatter情報を本文blockへ不用意に複製しない
• 申込終了・満員・営業中などを自動判定しない
• component gap を無理に既存blockへ押し込まない
• 人の承認前に公開Markdownへ反映しない・本番runtimeでLLMを呼ばない

人が確認する項目

• expectedInputs（信頼済み入力台帳）が正しく確定しているか（AIより前に人が用意）
• validator の error が 0 か（台帳の配置漏れ・台帳外ref追加・公開/非公開競合・public違反・未知kind・parse不能・高リスク導線不足など）
• 選んだblockと表示順、各配置の理由が妥当か
• hold / private / omit の判断と理由、component gap の要否
• 事実・出典・確認日・公式リンク、そして公開可否（最終判断は人）

component gap の扱い

既存blockで十分なValueを実現できない場合、AIはまず暫定fallback（標準Markdownや hold）で情報を保持し、 「表現したい情報 / 不足理由 / intended value / risk・guardrail / 暫定fallback / 新規block候補 / 人が判断すべき点」を出力します。 このPhaseで新しいUIを大量実装せず、新規block追加は人の承認後に Registry と実装へ反映します。

公開・コミット前の検査。チェック手順の正本は agent workflows/publish-check.md。

• Content Accuracy / Source Verification: 事実と出典の突き合わせ
• SEO: title・description・見出し階層（プロジェクト参照ページはnoindex維持）
• Accessibility: コントラスト・キーボード操作・色だけに頼らない表現（正本: ux-design-system.md）
• Internal Links / Status: リンク切れ・listing_status・orphan（/site-reference で確認）
• Build / Lint: npm run lint と npm run build が通ること
• Human Review: 公開判断は人（下のHuman Review）

AIが単独で進めてよい範囲と、人の承認が必要な範囲の境界。

• Review Required: 公開コンテンツの新規・変更はすべて人のレビューを経る
• Approval Required: 「公開OK」への移行と本番公開の最終承認は人だけが行う（/entry-workflow 参照）
• High-risk Content: 医療・防災・法務・お金は必ず一次情報の確認込みでレビュー
• Publication Decision: 掲載可否・削除判断はAIが下さない

作業終了時・スレッド移行時の報告。長い作業では agent project-documents/SESSION-HANDOFF.md を更新します。

• Changed Files: 変更・追加・削除したファイル一覧
• Decisions: 作業中に下した判断とその理由
• Remaining Work / Deferred: 残タスク・見送り
• Risks: 影響が読み切れていない箇所
• Next Steps: 次に着手すべきこと

AIが扱わない・置かないもの。プロジェクト参照ページを含む公開サイトには公開して問題のない情報だけを載せます。

• Personal Data / Form Responses / Private Contacts: フォーム回答の生データ・非公開連絡先はGit外管理。リポジトリ・プロジェクト参照ページに書かない
• Credentials / Billing: APIキー・token・環境変数・契約・請求情報を出力しない
• Destructive Operations: 明示的な依頼なしに削除・強制push・本番公開をしない
• git push はユーザーが明示的に頼んだときだけ（ローカルコミットまで）