P1: add data and agents.md

AGENTS.md

@@ -0,0 +1,42 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+- `*.py`: Standalone analysis/optimization scripts (run directly with Python).
+  - `kmin_effectiveness.py`: k-min vs effectiveness/fairness analysis; writes artifacts to `data/`.
+  - `fairness_optimization.py`, `analyze_visits.py`, `plot_sites.py`: additional analyses/plots.
+- `prob/`: Problem statement and source dataset (e.g., `prob/MFP Regular Sites 2019.xlsx`).
+- `latex-template/`: Report template and compilation assets.
+- `data/` (generated): Output CSV/PNG artifacts produced by scripts.
+
+## Build, Test, and Development Commands
+
+This repo is script-driven (no package build step).
+
+- Run k-min analysis: `python3 kmin_effectiveness.py`
+  - Outputs: `data/kmin_effectiveness.png`, `data/kmin_effectiveness_data.csv`, `data/kmin_effectiveness_sites.csv`
+- Run visit analysis: `python3 analyze_visits.py` (generates plots in the workspace)
+- Run site map: `python3 plot_sites.py`
+- Quick syntax check: `python3 -m py_compile kmin_effectiveness.py`
+
+Dependencies commonly used: `numpy`, `pandas`, `matplotlib`, plus Excel readers like `openpyxl`.
+
+## Coding Style & Naming Conventions
+
+- Python: 4-space indentation; keep scripts runnable as `python3 <script>.py`.
+- Prefer descriptive names (`k_min`, `total_demand`) and Chinese comments/docstrings where already used.
+- Output files should be written under `data/` and named predictably (e.g., `kmin_effectiveness_*.csv/png`).
+
+## Testing Guidelines
+
+There is no formal test suite currently. When changing math/metrics:
+
+- Add a small deterministic check (e.g., `py_compile`, or seed-controlled simulation runs).
+- Prefer reproducible randomness via explicit seeds (see `RANDOM_SEED` in `kmin_effectiveness.py`).
+
+## Commit & Pull Request Guidelines
+
+Commit history uses short subjects, sometimes with prefixes (e.g., `P1:` / `add:`). Follow this pattern:
+
+- Keep messages concise and action-oriented (e.g., `P1: add gini plot`).
+- PRs should include: what changed, which script(s) to run, and expected outputs (file names under `data/`).