Philippine Baseball Platform Docs
メニュー

運用手順

データ収集、アプリ開発、ドキュメント更新、配信の4つの流れをまとめます。各工程にはゲートがあり、失敗した場合は次へ進まずに戻します。

最終更新 2026-11-22コマンドはリポジトリ直下で実行

全体フロー

  1. 収集リソース評価 → 4系統の収集 → validate → アプリ JSON 再生成
  2. アプリ開発designer → developer → tester → Cloudflare Pages
  3. ドキュメントphb-docs-writer → check_docs.py → Cloudflare Pages
  4. 配信アプリとドキュメントは別プロジェクト・別の契機で公開
成果物でつなぐ

担当間の受け渡しは spec.md、data/、TEST-REPORT.md で行います。会話の文脈に依存させません。

データ更新

収集はフェーズ0〜4の順に進めます。フェーズ2の検証で1件でもエラーがあれば中止し、ユーザーに報告します。

0

リソース最新化

候補ドメインを 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 は自動昇格しない。運用者が判断する
1

専門収集4系統を並行

ニュース、選手、代表ロースター、試合動画の4担当が、resources.txt の RETAIN 先を横断探索し、data/ に蓄積します。各担当は一時ファイルを stats / valid JSON にまとめ、完了報告を返します。

担当主なスクリプト主な出力
news-collectorseen_urls.py / format_news.py --json-statsbaseball-news.csv
player-collectorformat_players.py --type uaap|lbp|colleges --json-stats選手3CSV
roster-collectorformat_roster.py --json-statsnational-team-rosters.csv
video-collectorcheck_video.py / seen_urls.py / format_videos.py --json-statsbaseball-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 パス)を確認する
2

全体検証

UTF-8、必須列、必須値、URL、日付形式、出典ドメインを検査します。--strict は警告もエラーとして扱います。

python3 .opencode/skills/phb-validate-baseball-data/scripts/validate.py --strict
出力
検証結果(JSON / 標準出力)
ゲート
エラー0件。1件でもあれば中止して報告する
3

アプリデータ再生成

全アプリの 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。期待値ガードや件数異常があれば止まる
4

配信

配布資源を 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-developerspec.md、生成データindex.html自己確認(HTTP 200、構文、fetch)が通る
検証phb-testerspec.md、data/、index.htmlTEST-REPORT.mdblock / major が0。FAIL は developer か designer へ戻す
配信phb-app-pages-deploydist、本番プロジェクト本番URL、検証結果200 と fetch 先の一致
同じ問題が2回続いたら

表面修正を繰り返さず、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 Pagesassemble_dist.py → wrangler pages deploy本番URLと fetch 先の 200、ポータルリンク
このドキュメントCloudflare Pagesdocs.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.ymldocs/** の 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 が 404Cloudflare 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 しない。