AGENTS.md

1# Instructions
2 
3## General rule
4 
5-   Read the codebase - the codebase is source of truth, and you should prefer reading lots of source code over searching.
6-   Do not search web unless explicitly asked to do so. Web search does not help in general for our project.
7-   Write performant code. Always prefer performance over other things.
8-   Use `gh` CLI tool for fetching data from `github.com`.
9-   Do not let sandbox constraints stall progress. If sandbox restrictions block required work, request escalation promptly and continue.
10 
11## Code style
12 
13-   Write comments and documentations in English.
14-   Write documentation for your code.
15-   When introducing a workaround, leave sufficient comments explaining why it is needed and any known limitations.
16-   Commit your work as frequent as possible using git. Do NOT use `--no-verify` flag.
17-   Prefer multiple small files over single large file.
18-   Prefer enum (or dedicated type) based modeling over raw string literals whenever possible.
19 
20---
21 
22-   When creating Atom instances, it's better to use `Cow<str>` or `&str` instead of `String`. Note that `&str` is better than `Cow<str>` here.
23 
24## Debugging and logging
25 
26-   Do not guess behavior. Verify assumptions by reading source, fixtures, and tests.
27-   Debug with logs when behavior is unclear.
28-   Write sufficient logs for debugging and operational troubleshooting.
29-   Prefer structured logging in Rust (`tracing`) over ad-hoc plain text logs when feasible.
30 
31## Shell safety
32 
33-   For shell commands or scripts, prefer `$(...)` over legacy backticks for command substitution.
34-   Quote and escape all dynamic shell values strictly.
35 
36## Git workflow
37 
38-   Run `git commit` only after `git add`.
39-   Once changes are staged, commit without unnecessary delay so staged history is preserved.
40-   When creating or updating a pull request, follow the repository pull request template.
41-   When creating a pull request, use the `add-changeset` skill to create the required changeset.
42-   After addressing pull request review comments and pushing updates, resolve the corresponding review threads.
43 
44## Testing
45 
46-   Write unit tests for your code.
47-   Prefer fixture tests over inline (`#[test]`) tests.
48-   Before running tests, run `git submodule update --init --recursive` to initialize and update all submodules.
49-   You can do `UPDATE=1 cargo test` to get test outputs updated for fixture tests.
50-   When instructed to fix tests, do not remove or modify existing tests.
51 
52### Fixture Test Common Guide
53 
54- Add new coverage by extending existing fixture suites instead of adding ad-hoc inline tests.
55- Find the exact fixture harness before adding files with: `rg -n "#\[(testing::)?fixture\(" tests src --glob "*.rs"`.
56- Keep each suite's naming conventions (for example: input.*, output.*, exec.*, .ans).
57- For snapshot-style tests, update expected outputs with `UPDATE=1 cargo test -p ...` using the exact crate command documented in each crate's AGENTS.md.
58- Always rerun the same crate tests without `UPDATE` before finishing.
59 
60## Verification
61 
62-   Before finishing a task, always run this baseline locally.
63    -   `cargo fmt --all`
64    -   `cargo clippy --all --all-targets -- -D warnings`
65-   For each touched Rust crate, run crate-level verification locally.
66    -   `cargo test -p <crate>`
67-   If wasm binding packages are touched, run:
68    -   `(cd bindings/binding_core_wasm && ./scripts/test.sh)`
69    -   `(cd bindings/binding_minifier_wasm && ./scripts/test.sh)`
70    -   `(cd bindings/binding_typescript_wasm && ./scripts/test.sh)`
71    -   `(cd bindings/binding_es_ast_viewer && ./scripts/test.sh)`
72-   If node bindings or integration paths are touched, run:
73    -   `(cd packages/core && pnpm build:dev && pnpm test)`
74 
75## Compatibility rule
76 
77-   Do not use unstable, nightly only features of rustc.
78-   Respect the project's MSRV. Do not rely on Rust language features or standard library APIs newer than the MSRV unless the change intentionally raises the MSRV.
79