docs: update AGENTS.md with test262, changeset, and bugfix workflow guidance (#20659)

xiaoxiaojx · claude · web-flow · commit 8e6aed2632a0 · 2026-03-17T20:18:24.000+03:00
- Add test262-cases to test directories and test commands table
- Clarify changeset descriptions should not use fix:/feat: prefix
- Add test-first workflow note for bug fixes

Co-authored-by: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/AGENTS.md b/AGENTS.md
@@ -33,6 +33,8 @@ If your change involves modifying or adding webpack configuration options:
 
 Modify source code in `lib/` as needed. If step 1 was performed, the latest type definitions are already available.
 
+For bug fixes, consider writing the test case (step 3) first. Run the test to confirm it fails, reproducing the bug. Then make the code change and re-run the test — a passing test confirms the fix.
+
 ### 3. Writing Tests
 
 Test files live in `test/` with naming conventions:
@@ -51,22 +53,24 @@ Test files live in `test/` with naming conventions:
 - `test/hotCases/` — HMR (Hot Module Replacement) test cases
 - `test/benchmarkCases/` — Performance benchmark cases (each has `index.js` + `webpack.config.mjs` + optional `options.mjs` with `setup()`)
 - `test/*.unittest.js` — Unit tests using Jest directly (e.g., `test/FileSystemInfo.unittest.js` uses `memfs` for filesystem mocking)
+- `test/test262-cases/` — ECMAScript test262 conformance cases (git submodule, init with `git submodule update --init test/test262-cases`; test runner: `test/test262.spectest.js`)
 
 ### 4. Running Tests
 
 Only run tests when test files are modified or explicitly requested.
 
 **Choose test command based on modified directory:**
 
-| Modified directory/file | Command                                                   |
-| ----------------------- | --------------------------------------------------------- |
-| `test/*.unittest.js`    | `yarn test:base -- --testPathPatterns="<filename>"`       |
-| `test/cases/`           | `yarn test:basic`                                         |
-| `test/configCases/`     | `yarn test:basic -- --testPathPatterns="ConfigTestCases"` |
-| `test/statsCases/`      | `yarn test:basic -- --testPathPatterns="StatsTestCases"`  |
-| `test/watchCases/`      | `yarn test:base -- --testPathPatterns="WatchTestCases"`   |
-| `test/hotCases/`        | `yarn test:base -- --testPathPatterns="HotTestCases"`     |
-| `test/benchmarkCases/`  | `FILTER="<case-name>" yarn benchmark`                     |
+| Modified directory/file | Command                                                                               |
+| ----------------------- | ------------------------------------------------------------------------------------- |
+| `test/*.unittest.js`    | `yarn test:base -- --testPathPatterns="<filename>"`                                   |
+| `test/cases/`           | `yarn test:basic`                                                                     |
+| `test/configCases/`     | `yarn test:basic -- --testPathPatterns="ConfigTestCases"`                             |
+| `test/statsCases/`      | `yarn test:basic -- --testPathPatterns="StatsTestCases"`                              |
+| `test/watchCases/`      | `yarn test:base -- --testPathPatterns="WatchTestCases"`                               |
+| `test/hotCases/`        | `yarn test:base -- --testPathPatterns="HotTestCases"`                                 |
+| `test/benchmarkCases/`  | `FILTER="<case-name>" yarn benchmark`                                                 |
+| `test/test262-cases/`   | `yarn test:test262` (requires `git submodule update --init test/test262-cases` first) |
 
 You can add `--testNamePattern="<case-name>"` to run only specific test cases for faster validation. Multiple patterns can be combined with `|`. For example, if you only modified `test/configCases/css/basic/`:
 
@@ -87,7 +91,7 @@ Every user-facing change needs a changeset file:
 Description of the change.
 ```
 
-Use `patch` for bug fixes, `minor` for new features, `major` for breaking changes.
+Use `patch` for bug fixes, `minor` for new features, `major` for breaking changes. Do not prefix the description with `fix:`, `feat:`, etc. — the change type is already indicated by `patch`/`minor`/`major`.
 
 ### 6. Updating Examples (if needed)
 
