add AGENTS.md

AGENTS.md

@@ -0,0 +1,63 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this repository.
+
+## Project Shape
+
+- `fetch_contests.py` is the data generator. It fetches contests, normalizes records with `platform`, `title`, `start_time`, `end_time`, `status`, and `url`, then writes JSON files in the repository root.
+- `.github/workflows/deploy.yml` is the GitHub Actions automation. It installs Python dependencies, runs `fetch_contests.py`, and commits generated JSON changes.
+- `server/index.php` is the serving/display layer. It reads the public raw `contests.json`, caches it locally, and renders the upcoming contest page.
+- User-facing documentation lives in [README.md](README.md) and [README_zh.md](README_zh.md). Keep both languages in sync.
+
+## Actions vs Server Responsibilities
+
+- Actions side: update contest data only. Change `.github/workflows/deploy.yml` when editing schedule triggers, Python version, dependency installation, generated files to commit, or commit/push behavior.
+- Data-fetch side: change `fetch_contests.py` when editing providers, normalization, filtering, output JSON shape, or output file policy.
+- Server side: change `server/index.php` when editing presentation, caching, raw JSON URL, platform labels/classes, countdown behavior, or PHP deployment behavior.
+- Do not put scraping logic in `server/index.php`; keep upstream fetching in `fetch_contests.py` so Actions can generate static JSON.
+
+## Adding or Removing a Contest Provider
+
+When adding a new contest provider, check all relevant surfaces:
+
+- `fetch_contests.py`: add a `fetch_<provider>()` function, normalize records through `make_contest()`, add it to both output flows in `main()`, and preserve `status` semantics.
+- `server/index.php`: add the platform name to `$platform_class` and define a matching `.platform.<class>` CSS rule if the provider appears in `contests.json`.
+- `README.md` and `README_zh.md`: update supported platforms, data-source notes, and any changed usage/output details.
+- `AGENTS.md`: update this guidance if the provider introduces a new pattern, dependency, output contract, or operational caveat.
+- `.github/workflows/deploy.yml`: update only if the provider needs new Python dependencies, generated files, secrets, or schedule behavior.
+
+When removing a provider, remove or adjust the same surfaces so stale platform labels, CSS classes, docs, and workflow dependencies do not remain.
+
+## Output Contracts
+
+- `contests.json` contains contests that have not ended yet: `upcoming` and `running`.
+- `contests_all.json` contains contests that finished within the last 30 days.
+- JSON timestamps are Unix timestamps in seconds.
+- Keep record keys stable unless the README files and server rendering are updated in the same change.
+
+## Validation
+
+After changing fetching, filtering, output shape, provider support, or workflow-generated files, run:
+
+```bash
+python fetch_contests.py
+```
+
+Then inspect the generated files with `jq` when available, for example:
+
+```bash
+jq 'group_by(.platform) | map({platform: .[0].platform, count: length})' contests.json
+jq 'group_by(.status) | map({status: .[0].status, count: length})' contests_all.json
+```
+
+For PHP-only presentation changes, also check that `server/index.php` still reads `contests.json` and handles unknown platforms with the default styling.
+
+## Documentation Rule
+
+Every feature addition, feature removal, provider change, output contract change, or workflow behavior change must update all three documentation files in the same change:
+
+- [README.md](README.md)
+- [README_zh.md](README_zh.md)
+- [AGENTS.md](AGENTS.md)
+
+Link to existing docs instead of duplicating long explanations. Keep agent guidance concise and operational.

README.md

@@ -86,6 +86,10 @@ A typical automation flow is:
 
 For GitHub Actions, install the Python dependencies before running the script.
 
+## Development Notes
+
+AI coding agents and maintainers should follow [AGENTS.md](AGENTS.md) when changing providers, output contracts, workflow behavior, or documentation.
+
 ## Notes
 
 - AtCoder uses the AtCoder Problems API and falls back to the official AtCoder contest page for upcoming contests when needed.

README_zh.md

@@ -86,6 +86,10 @@ define('JSON_URL', 'https://raw.githubusercontent.com/hanyixuanten/OI-contest-fe
 
 如果使用 GitHub Actions，请在运行脚本前安装 Python 依赖。
 
+## 开发说明
+
+AI coding agents 和维护者在修改比赛提供商、输出契约、工作流行为或文档时，应遵循 [AGENTS.md](AGENTS.md)。
+
 ## 注意事项
 
 - AtCoder 使用 AtCoder Problems API；在需要时会回退解析 AtCoder 官方比赛页面以获取即将开始的比赛。