全体フロー
- 収集リソース評価 → 4系統の収集 → validate → アプリ JSON 再生成
- アプリ開発designer → developer → tester → Cloudflare Pages
- ドキュメントphb-docs-writer → check_docs.py → Cloudflare Pages
- 配信アプリとドキュメントは別プロジェクト・別の契機で公開
担当間の受け渡しは spec.md、data/、TEST-REPORT.md で行います。会話の文脈に依存させません。
データ更新
収集はフェーズ0〜4の順に進めます。フェーズ2の検証で1件でもエラーがあれば中止し、ユーザーに報告します。
リソース最新化
候補ドメインを Cloudflare Clef-flash(@cf/cloudflare/clef-flash)の意味適合度と、decision_engine.py の5ルールで評価し、RETAIN / REVIEW / DROP に分類します。RETAIN だけが resources.txt に同期されます。
| ルール | 条件 | 判定 |
|---|---|---|
| Rule 1 CLEF_HIGH | 意味適合度が高い | RETAIN |
| Rule 2 EVIDENCE_RECENT_AND_RECURRING | 期間内の高密度報道 | RETAIN |
| Rule 3 MODERATE_RECENT_EVIDENCE | 中程度の報道実績 | REVIEW |
| Rule 4 UNIQUE_OR_PRIMARY_SOURCE | 希少な一次情報源 | REVIEW |
| Rule 5 DROP | 期間外・陳腐化・報道不足 | DROP |
- 実行
phb-discover-baseball-resourcesスキル- スクリプト
run_evaluations.py/decision_engine.py/resource_utils.py- 出力
references/resources.txt(RETAINのみ)、review_candidates.md、評価レポート- キャッシュ
- 24時間。再評価は
--force - ゲート
- REVIEW は自動昇格しない。運用者が判断する
専門収集4系統を並行
ニュース、選手、代表ロースター、試合動画の4担当が、resources.txt の RETAIN 先を横断探索し、data/ に蓄積します。各担当は一時ファイルを stats / valid JSON にまとめ、完了報告を返します。
| 担当 | 主なスクリプト | 主な出力 |
|---|---|---|
| news-collector | seen_urls.py / format_news.py --json-stats | baseball-news.csv |
| player-collector | format_players.py --type uaap|lbp|colleges --json-stats | 選手3CSV |
| roster-collector | format_roster.py --json-stats | national-team-rosters.csv |
| video-collector | check_video.py / seen_urls.py / format_videos.py --json-stats | baseball-game-videos.md |
- 実行
phb-collect-all-baseball-dataスキル- 監視
check_agent_status.pyがPHB_COLLECT_STATUSの完了マーカーを確認- 出力
data/の7ファイル、stats / valid JSON- 記録
record_run.pyがreports/runsに実行サマリーを残す- ゲート
- 各担当の完了報告(status と JSON パス)を確認する
全体検証
UTF-8、必須列、必須値、URL、日付形式、出典ドメインを検査します。--strict は警告もエラーとして扱います。
python3 .opencode/skills/phb-validate-baseball-data/scripts/validate.py --strict
- 出力
- 検証結果(JSON / 標準出力)
- ゲート
- エラー0件。1件でもあれば中止して報告する
アプリデータ再生成
全アプリの build-data.py を実行し、apps/<name>/data/*.json を最新化します。続けて refresh_docs_stats.py が公開docsの件数 docs/data/stats.json を更新します。データが変わった時だけ --force-date を付け、変わらない週は日付を据え置きます。再実行しても同じ結果になることが要件です。
for f in apps/*/data/build-data.py; do python3 "$f"; done
python3 .opencode/skills/phb-docs/scripts/refresh_docs_stats.py --date "$UNTIL"
- 出力
- 各アプリの生成 JSON、
docs/data/stats.json - ゲート
- 終了コード0。期待値ガードや件数異常があれば止まる
配信
配布資源を apps/<name>/deploy/dist/ に組み立て、Cloudflare Pages へ配信します。docs は docs.yml が別プロジェクトへ配信します。CI では収集から配信まで自動でつながります。
python3 .opencode/skills/phb-app-pages-deploy/scripts/assemble_dist.py
npx wrangler pages deploy apps/<name>/deploy/dist \
--project-name <name> --branch main --commit-dirty=true
- ゲート
- 本番URLと主要 fetch 先が 200。ポータルのカードリンクも一致する
- 注意
- 認証情報は環境変数で渡す。コマンドに直接書かない
アプリ開発
アプリの変更は phb-app-orchestrator を通し、designer → developer → tester の順に進めます。小さな見た目修正でも、spec に触れるなら designer から始めます。
| 工程 | 担当 | 入力 | 出力 | 次へ進む条件 |
|---|---|---|---|---|
| 設計 | phb-designer | 要望、元データ、既存アプリ | spec.md、apps/*/data/*.json | 受け入れ基準が検証可能な数値・文言になっている |
| 実装 | phb-developer | spec.md、生成データ | index.html | 自己確認(HTTP 200、構文、fetch)が通る |
| 検証 | phb-tester | spec.md、data/、index.html | TEST-REPORT.md | block / major が0。FAIL は developer か designer へ戻す |
| 配信 | phb-app-pages-deploy | dist、本番プロジェクト | 本番URL、検証結果 | 200 と fetch 先の一致 |
表面修正を繰り返さず、designer に spec の見直しを依頼して停止します。実装の独行で spec を変えません。
ドキュメント更新
このサイトは phb-docs-writer が phb-docs スキルに従って更新します。アプリやデータには書き込みません。
| 手順 | 内容 |
|---|---|
| 1. 変更源を確認 | データ、アプリ、agents、CI のどこが変わったかを特定する |
| 2. ページを更新 | docs/ と必要なら README.md を編集する |
| 3. 機械検査 | python3 .opencode/skills/phb-docs/scripts/check_docs.py |
| 4. 表示確認 | 390 / 768 / 1280px で横溢れとコンソールエラーを確認する |
| 5. 公開 | docs/** の変更が docs.yml で Cloudflare Pages に反映される |
python3 -m http.server 8000
# http://localhost:8000/docs/ を開く
配信
| 対象 | 配信先 | 方法 | 検証 |
|---|---|---|---|
| 5アプリ | Cloudflare Pages | assemble_dist.py → wrangler pages deploy | 本番URLと fetch 先の 200、ポータルリンク |
| このドキュメント | Cloudflare Pages | docs.yml → wrangler pages deploy docs | 全ページ 200、404.html、相対パス |
Cloudflare Pages は docs/ をそのまま配信します。静的ファイルなのでビルドは不要で、.nojekyll も使いません。内部リンクはすべて相対パスです。
CI
| ワークフロー | 契機 | 内容 |
|---|---|---|
collect.yml | 週1(月曜 03:00 JST)+ 手動 | devcontainer 内で収集 → validate --strict → 全 build-data.py → docs stats → OGP → commit・push |
deploy.yml | 配布物の push + 手動 | 鮮度チェック → dist 組立 → Cloudflare Pages 配信 → 5 URL と fetch 先の検証 |
docs.yml | docs/** の push + 手動 | check_docs.py → wrangler pages deploy docs → 全ページ 200 / 404 の検証 |
deploy.yml は data/** と apps/* の配布対象の変更で起動します。ドキュメントだけの変更では起動しません。docs は docs.yml が配信します。Secrets の名前・設定・ブランチ保護は .github/CI.md を参照してください。
workflow を追加・変更するときは .opencode/rules/github-actions.md と phb-github-actions スキルに従い、check_workflows.py --check-remote を通します。deprecated な Node runtime の action は使いません。
コマンド早見表
| 目的 | コマンド |
|---|---|
| データ検証 | python3 .opencode/skills/phb-validate-baseball-data/scripts/validate.py --strict |
| アプリ JSON 再生成 | cd apps/<name>/data && python3 build-data.py |
| 元データとアプリ JSON の照合 | python3 .opencode/skills/phb-app-test/scripts/spot_check.py --app <name> |
| アプリの自己確認 | python3 .opencode/skills/phb-app-develop/scripts/self_check.py --app <name> |
| dist の組立 | python3 .opencode/skills/phb-app-pages-deploy/scripts/assemble_dist.py |
| OGP 件数の検査 | python3 .opencode/skills/phb-app-pages-deploy/scripts/check_og_counts.py |
| docs の検査 | python3 .opencode/skills/phb-docs/scripts/check_docs.py |
失敗時の見方
| 症状 | 意味 | 対応 |
|---|---|---|
| collect が赤 | 収集・検証・生成・push のいずれかで失敗。配信されない | 実行ログを見て、失敗した工程を特定する |
| collect は緑、deploy が赤 | データは main にあるが配信に失敗 | 配信ログを見て deploy.yml を再実行する |
| 生成物が不一致 | build-data.py を実行せずに JSON を push した | ローカルで再生成し、生成物をコミットする |
| OGP で失敗 | meta や画像の件数がデータとずれている | build_og.py で画像を再生成し、meta も同時に更新する |
| docs のリンク切れ | ページ追加時にナビや相対パスがずれた | check_docs.py の指摘を直し、全ページのナビを揃える |
| docs が 404 | Cloudflare Pages のプロジェクト名か配信先が違う | docs.yml のログと --project-name を確認する |
環境
- devcontainer。 Python 3.12、Node、OpenCode を含む再現環境です。CI も同じ devcontainer を使います。
- エージェント実行。 OpenCode 上で、OpenCode Go の
deepseek-v4.1-flash-1017を使います。モデルはopencode.jsonで指定します。 - 開発用依存。 Playwright は任意です。
requirements-dev.txtから導入します。 - Secrets。 収集・配信・push 用のトークンは GitHub の Secrets で管理します。名前・設定・ブランチ保護は
.github/CI.mdを参照し、値はドキュメントにもログにも出しません。 - ブランチ保護。
mainは削除・force push を禁止し、人間の変更は PR 経由、週次の bot push だけがバイパスする運用です。
禁止事項
data/を収集担当の依頼なしに編集しない。apps/<name>/data/やdeploy/dist/を手で編集しない。必ず再生成する。- developer が
spec.mdを、tester が実装を、docs-writer がアプリを編集しない。 .envを読まない・コミットしない。秘密情報を docs に書かない。- ユーザーの明示的な指示なく commit / push しない。