docs: expand coding, testing, and PR guidelines in AGENTS.md

AGENTS.md

@@ -22,6 +22,15 @@ This is the source code for the Angular CLI and related build tooling. This guid
   pnpm build --local
   ```
 
+## Coding Practices
+
+- **Imports:**
+  - Always use the `node:` protocol for Node.js built-in imports (e.g., `node:fs`, `node:path`, `node:assert`).
+  - Prefer named imports (e.g., `import { mkdtemp } from 'node:fs'`) or default imports (`import fs from 'node:fs'`) instead of namespace imports (`import * as fs`).
+  - Use type-only imports (`import type { ... }`) when importing types to avoid runtime side-effects.
+- **Classes:**
+  - Prefer ECMAScript private fields (`#field`) over TypeScript `private` keywords for encapsulated state.
+
 ## Testing
 
 - **Temporary Directories (`TEST_TMPDIR`):**
@@ -42,14 +51,15 @@ This is the source code for the Angular CLI and related build tooling. This guid
     });
     ```
   - **NEVER** use or fallback to `os.tmpdir()`. Bazel executes tests in hermetic sandboxes and sets `TEST_TMPDIR` to an isolated, sandboxed directory. Using `os.tmpdir()` can cause sandboxing failures, permission errors, or file leakage outside the Bazel sandbox.
-- **Imports:**
-  - Always use the `node:` protocol for Node.js built-in imports (e.g., `node:fs`, `node:path`, `node:assert`).
-  - Prefer named imports (e.g., `import { mkdtemp } from 'node:fs'`) or default imports (`import fs from 'node:fs'`) instead of namespace imports (`import * as fs`).
 - **Unit Tests:**
   - Run all unit tests: `pnpm bazel test //packages/...`
   - Run a specific test target: `pnpm bazel test //packages/angular/build:test`
   - Query test targets: `pnpm bazel query "tests(//packages/...)"`
   - Focus specific tests when debugging: use `fdescribe()` and `fit()`. NEVER commit focused tests to the repository.
+  - Run tests without sharding when isolating or debugging: use `--config=no-sharding` with a specific test target (e.g., `pnpm bazel test //packages/angular/build:test --config=no-sharding`).
+    This disables test sharding (`--test_sharding_strategy=disabled`) and flaky test retries (`--flaky_test_attempts=1`).
+    This is especially useful when isolating test runs or debugging with focused tests (`fit`/`fdescribe`) to avoid empty shard failures and unnecessary re-runs.
+    Do not use this flag when running broad test suites (such as `//packages/...`), as executing tests without sharding takes significantly longer.
 - **End-to-End Tests:**
   - Run subset of E2E tests: `pnpm bazel test //tests:e2e_node22 --config=e2e --test_filter="<filter>"`
 
@@ -58,7 +68,8 @@ This is the source code for the Angular CLI and related build tooling. This guid
 - Use the `gh` CLI (GitHub CLI) for creating and managing pull requests.
 - **Fixup Commits:**
   - When addressing review feedback, **ALWAYS** use fixup commits (`git commit --fixup <commit>`) instead of amending existing commits. This preserves commit history during review and allows reviewers to easily see incremental changes.
-  - Fixup commits are automatically squashed when merging with `pnpm ng-dev pr merge` or rebasing with `pnpm ng-dev pr rebase <pr>`.
+  - Only use fixup commits for changes that directly belong to the target commit. Unrelated changes must be made in a separate commit with their own commit message, not as a fixup commit.
+  - Fixup commits are automatically squashed when merging with `pnpm ng-dev pr merge` or optionally when rebasing with `pnpm ng-dev pr rebase <pr>`.
 - Use `pnpm ng-dev pr` commands:
-  - `pnpm ng-dev pr rebase <pr>`: Rebase a PR branch on its target branch and squash fixup commits.
+  - `pnpm ng-dev pr rebase <pr>`: Rebase a PR branch on its target branch and optionally squash fixup commits.
   - `pnpm ng-dev pr merge <pr>`: Merge an approved PR into its targeted branches.