0 Fork 0

Files

T

sganggs 713a292463 feedback7: AGENTS.md and CLAUDE.md — an entry point for AI coding assistants (GitHub #379 by @anAtheist987; the owner's OK of 2026-10-08)

- 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.

2026-10-08 20:14:29 +08:00

3.6 KiB

Raw Blame History

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 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

docs/ARCHITECTURE.md — the code map: where things live, data flow, golden results, import boundaries, where common changes start.
docs/DESIGN.md — the index of the rules: current rules in docs/design/, each release's revisions and their evidence in docs/history/.
The reference for the part you touch: docs/SIM.md (battle engine API, hooks, test harness), docs/META.md (match flow, shop, protocol), docs/DATA.md (generated data), 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. 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).
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:

node --test test/<area>/<file>.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.