From 713a2924638a2a0589410b5b6b223b6de4d096b5 Mon Sep 17 00:00:00 2001 From: sganggs Date: Thu, 8 Oct 2026 20:14:29 +0800 Subject: [PATCH] =?UTF-8?q?feedback7:=20AGENTS.md=20and=20CLAUDE.md=20?= =?UTF-8?q?=E2=80=94=20an=20entry=20point=20for=20AI=20coding=20assistants?= =?UTF-8?q?=20(GitHub=20#379=20by=20@anAtheist987;=20the=20owner's=20OK=20?= =?UTF-8?q?of=202026-10-08)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - AGENTS.md only indexes the existing documents (ARCHITECTURE, DESIGN index, SIM / META / DATA / I18N, the kits README) and their hard rules (official first + [ASSUMED], sim determinism and detmath, golden results, generated data, no game art, t() strings, docs with the code, commit / PR conventions, verification commands); CONTRIBUTING.md stays the full text. CLAUDE.md is one line pointing to it. - Tests: docs-paths, docs-consistency. --- AGENTS.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 3 +++ 2 files changed, 59 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..6c96fa55 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,56 @@ +# AGENTS.md + +Entry point for AI coding assistants (Codex, Claude Code, Cursor, Copilot …) working on this repository. It only +indexes the existing documents and their hard rules; when this file and a linked document disagree, the document wins. +Human contributors: [CONTRIBUTING.md](CONTRIBUTING.md) is the same material in full. + +## What this is + +A non-commercial fan remake of Arknights「卫戍协议：盟约」 that runs in the browser: a Node.js server (economy, rounds, +rooms) and a deterministic battle sim shared by the server and the browser. It aims to be faithful to the official mode. + +## Read first + +1. [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — the code map: where things live, data flow, golden results, + import boundaries, where common changes start. +2. [docs/DESIGN.md](docs/DESIGN.md) — the index of the rules: current rules in `docs/design/`, each release's + revisions and their evidence in `docs/history/`. +3. The reference for the part you touch: [docs/SIM.md](docs/SIM.md) (battle engine API, hooks, test harness), + [docs/META.md](docs/META.md) (match flow, shop, protocol), [docs/DATA.md](docs/DATA.md) (generated data), + [docs/I18N.md](docs/I18N.md) (interface strings), `server/sim/content/kits/README.md` (operator kits). + +## Hard rules + +- **Official first.** Rules come from the official data tables (`.cache/gamedata/excel/` after setup) and + [PRTS](https://prts.wiki/). A detail no source settles is implemented the simplest way and marked `[ASSUMED]` in the + code and the PR. Deliberate deviations from the official mode are the maintainer's decision only. +- **Determinism.** `server/sim/` is plain ESM that runs in Node and in browsers: no Node APIs, no `Math.random`, no + clocks, and no engine-approximated Math functions (use `server/sim/detmath.js`; ESLint and + `test/sim/detmath.test.js` enforce it). +- **Golden results.** A refactor must not change `test/golden/*.json`. An intended gameplay change runs + `npm run golden:update` in the same commit, and the commit / PR names every moved scenario and why + ([test/golden/README.md](test/golden/README.md)). +- **Generated data.** Never hand-edit `data/*.json`: change `tools/build-data.mjs` and regenerate. +- **No game art in git.** `public/assets/` is ignored; never commit extracted or downloaded game files. +- **Interface strings** go through `t('…')`, with entries in every pack under `public/i18n/` + (`node tools/i18n.mjs check --all --strict`). +- **Docs follow the code.** A rule change updates `docs/design/`, the current `docs/history/` file and the reference + docs; run `node --test test/docs-consistency.test.js test/docs-paths.test.js`. +- **Commits and PRs**: one topic per PR; a one-line message of what changed (Chinese or English) with the issue number; + no attribution trailers (`Co-Authored-By:`, `Generated with …`). The PR description states what, why, the sources, + the `[ASSUMED]` points, the tests you ran (paste the summary lines) and the golden moves. No ads, payments or other + monetisation — the project stays non-commercial. + +## Verify + +Run the tests of what you touched first, then everything before opening the PR: + +```bash +node --test test//.test.js # targeted +npm run ci # the CI checks locally (tools/ci.mjs): node --test, smoke, lint, imports, types +npm run golden # golden results +``` + +Browser suites are off by default and need Chrome: `SP_E2E=1` (UI), `SP_REAL_E2E=1` (real match, needs assets), +`RENDER_E2E=1`, `SIM_E2E=1` — see CONTRIBUTING.md §2. Battle tests are easiest with the helpers described in +docs/SIM.md (the test harness section) and the patterns in `test/content/op_siege.test.js`. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..92eb3a21 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,3 @@ +# CLAUDE.md + +Read [AGENTS.md](AGENTS.md) — the entry point for AI coding assistants (what to read first, the hard rules, how to verify).