From 351cac7734a44706f392ae67fa0f1393f79f84b6 Mon Sep 17 00:00:00 2001 From: mamamiyear Date: Fri, 15 May 2026 14:58:54 +0800 Subject: [PATCH] docs: add AGENTS.md --- .gitignore | 3 +++ AGENTS.md | 32 ++++++++++++++++++++++++++++++++ 2 files changed, 35 insertions(+) create mode 100644 AGENTS.md diff --git a/.gitignore b/.gitignore index 04cb0fe..64b9066 100644 --- a/.gitignore +++ b/.gitignore @@ -37,3 +37,6 @@ htmlcov/ # debug resources debug/ + +# Node dependencies for browser automation tooling +node_modules/ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..7b1279d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,32 @@ +# Repository Guidelines + +## Project Structure & Module Organization + +Core poker service code lives in `texas_holdem/`. Important modules include `engine.py` for Texas Hold'em rules, `service.py` for game management, `server.py` for the HTTP API, `agents.py` for local/HTTP agents, and `ai_client.py` / `human_client.py` for standalone agents. Prompt templates live in `texas_holdem/prompts/`. + +Replay UI code lives in `texas_holdem_replay/`, with static browser assets under `texas_holdem_replay/static/`. Tests are in `tests/`, named by feature area such as `test_engine.py`, `test_service.py`, and `test_replay_server.py`. Design notes belong in `docs/`. + +## Build, Test, and Development Commands + +- `python -m unittest discover -v` runs the full test suite. +- `python -m compileall texas_holdem texas_holdem_replay tests` checks import and syntax validity. +- `python -m texas_holdem.server --host 127.0.0.1 --port 8000` starts the game service. +- `python -m texas_holdem.human_client --port 9001 --keep-history` starts an interactive human HTTP agent. +- `python -m texas_holdem.ai_client --port 9101 --api-key "$OPENAI_API_KEY" --model gpt-4o-mini` starts an OpenAI-compatible AI agent. +- `python -m texas_holdem_replay.server --port 8088` starts the replay viewer. + +## Coding Style & Naming Conventions + +Use Python 3.11+ standard-library APIs unless a dependency is intentionally added to `pyproject.toml`. Keep modules focused and prefer explicit dataclasses for wire/state models. Use 4-space indentation, type hints, `snake_case` for functions and variables, `PascalCase` for classes, and concise comments only where logic is non-obvious. + +## Testing Guidelines + +Use `unittest`. Add tests near the behavior changed: engine rules in `tests/test_engine.py`, HTTP/service behavior in `tests/test_service.py`, agent transport in `tests/test_agents.py`, and replay UI server helpers in `tests/test_replay_server.py`. New bug fixes should include a regression test. Avoid tests that require external network access or real LLM calls. + +## Commit & Pull Request Guidelines + +History uses short Conventional Commit-style subjects, for example `feat: add replay server and web client` and `fix: game service api block when a game is running`. Keep commits scoped to one behavior change. Pull requests should include a short summary, test commands run, linked issue or motivation, and screenshots only for replay UI or visible terminal-output changes. + +## Security & Configuration Tips + +Do not commit API keys. Pass LLM credentials through `OPENAI_API_KEY` or CLI flags in local shells only. HTTP Agent endpoints are exclusive per active game; preserve this invariant when changing service concurrency.