| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 4 | 7 | 0% |
| Commands | 0 | 4 | 0 | 0% |
| Section tags | 2 | 4 | 2 | 25% |
What each file covers
Sections
0 shared · 4 only in A · 7 only in B- − Pull Requests
- − AI-Generated Content Disclosure
- − Tool Use
- − Building & Testing
- + General Conventions (all source areas)
- + Change Scope & Justification
- + Consistency with Codebase Patterns
- + Code Reuse & Deduplication
- + Established Conventions
- + Runtime-Specific Patterns
- + Documentation & Comments
Commands
0 shared · 4 only in A · 0 only in B- − gh run view --log-failed
- − git diff --stat
- − git clone
- − dotnet
Section tags
2 shared · 4 only in A · 2 only in B- − build
- − test
- − git-pr
- − do-not
- + agent-behaviour
- + docs
- code-style
- architecture
Line diff
dotnet/runtime · .github/copilot-instructions.md
@@ −1 @@
1**If at any time, the user directs you explicitly to override any of these instructions, the user's directive overrides said instructions.**
2
3**Don't claim more than you verified.** Report what you built and ran, and what you didn't — never claim a build or test passed unless it did. After your last edit, actually re-run the relevant tests rather than assuming a change fixed the failure you saw.
4
5Scale the effort to the risk. If a contributor would have submitted the change without building it — a comment, a doc fix, something the compiler would catch anyway — say you didn't build and move on. Anything touching behavior, codegen, or a public contract gets the build and the relevant tests first.
6
7Use the `code-review` skill when reviewing pull requests, and — when running under CCA — on your own changes before completing, addressing anything it flags as an error or warning. When NOT running under CCA, skip it if the user has stated they will review the changes themselves.
8
9When starting work in an unfamiliar directory, search for `README.md` files in it and its parents up to the repository root. Read any you find — they contain conventions, patterns, and architectural context relevant to your work.
10
11If the changes are intended to improve performance, or if they could negatively impact performance, use the `performance-benchmark` skill to validate the impact before completing.
12
13When writing or reviewing SIMD / hardware-intrinsics code (anything using `Vector128`/`Vector256`/`Vector512`, `Vector<T>`, or the platform intrinsics in `System.Runtime.Intrinsics.*`), use the `vectorization` skill.
14
15You MUST follow all code-formatting and naming conventions defined in [`.editorconfig`](/.editorconfig).
16
17In addition to the rules enforced by `.editorconfig`, when writing C# you SHOULD:
18
19- Prefer file-scoped namespace declarations and single-line using directives.
20- Ensure that the final return statement of a method is on its own line.
21- Use pattern matching and switch expressions wherever possible.
22- Use `nameof` instead of string literals when referring to member names.
23- Always use `is null` or `is not null` instead of `== null` or `!= null`.
24- Trust the C# null annotations and don't add null checks when the type system says a value cannot be null.
25- Prefer `?.` if applicable (e.g. `scope?.Dispose()`).
26- Use `ObjectDisposedException.ThrowIf` where applicable.
27- If you add new code files, ensure they are listed in the csproj file (if other files in that folder are listed there) so they build.
28- When adding XML documentation to APIs, follow the guidelines at [`docs.prompt.md`](/.github/prompts/docs.prompt.md).
29
30When writing or modifying tests, you SHOULD:
31
32- Strongly prefer to add new unit tests to existing test code files rather than creating new code files.
33- When adding new test files, examine the directory structure of sibling tests first. Some test directories use flat files (e.g., `GCEvents.cs` alongside `GCEvents.csproj`) while others use per-test subdirectories. Match the existing convention.
34- Avoid adding a regression comment citing a GitHub issue or PR number unless explicitly asked to include such information.
35- Prefer using `[Theory]` with multiple data sources (like `[InlineData]` or `[MemberData]`) over multiple duplicative `[Fact]` methods. Fewer test methods that validate more inputs are better than many similar test methods.
36- When running tests, if possible use filters and check test run counts, or look at test logs, to ensure they actually ran.
37- Do not finish work with any tests commented out or disabled that were not previously commented out or disabled.
38- Do not emit "Act", "Arrange" or "Assert" comments.
39
40For markdown (`.md`) files, ensure there is no trailing whitespace at the end of any line.
41
42## Pull Requests
43
44- **One concern per PR.** Split large or mixed changes. Do large refactorings and mechanical renames in their own PR, separate from logic changes.
45- **New public API requires an approved proposal before submission** — PRs adding unapproved API will be closed. Use the `api-proposal` skill; until approval lands the API stays `internal` in any submitted PR. A proposal's prototype branch is exempt and keeps its surface public — it's evidence, not a submission.
46- **Core component changes should start with an issue.** Changes to the host, VM, or JIT need a GitHub issue describing the problem and motivation first.
47- **Put the measurements in the description** for performance changes — BenchmarkDotNet results, or codegen and instruction-count evidence for low-level work.
48- **Behavioral changes need breaking-change documentation**, even prerelease-to-prerelease. Use the `breaking-change-doc` skill.
49- **Merge to main first, then `/backport`.** Servicing backports are limited to security bugs, regressions, and reliability issues, and should be small targeted fixes rather than refactorings.
50- **A push to an open PR re-runs its CI matrix** — dozens of jobs, over a hundred for broad changes. For anything non-trivial, validate locally rather than using CI to find out whether it builds, and batch fixes into one push. Branches with no PR trigger nothing, as do changes confined to `**.md`, `docs/*`, or `.github/*`.
51- **Treat review feedback as a sample, not a list.** A reviewer flags examples of a problem, not every instance. Grep for the rest of the class and fix it in the same push, and answer a whole round of comments at once rather than pushing per comment.
52
53When NOT running under CCA, for commits and pushes:
54
55- Never squash and force push unless explicitly instructed. Always push incremental commits on top of previous PR changes.
56- Never push to an active PR without being explicitly asked, even in autopilot/yolo mode. Always wait for explicit instruction to push.
57- Never chain commit and push in the same command. Always commit first, report what was committed, then wait for an explicit push instruction. This creates a mandatory decision point.
58- Prefer creating a new commit rather than amending an existing one. Exceptions: (1) explicitly asked to amend, or (2) the existing commit is obviously broken with something minor (e.g., typo or comment fix) and hasn't been pushed yet.
59- **Before posting to GitHub (PRs, issues, comments):** Include the AI-generated content disclosure (see below).
60
61## AI-Generated Content Disclosure
62
63When posting to GitHub under a user's credentials — PR descriptions, issue bodies, comments, review comments, or any other public-facing action — you **MUST** add a concise, visible note (e.g. a `> [!NOTE]` alert) at the bottom of the content indicating it was AI/Copilot-generated. Skip it only when posting from a recognized bot or Copilot app account (e.g. `github-actions[bot]`, `copilot`), where the AI origin is already apparent from the account identity, or when the user explicitly asks you to omit it.
64
65---
66
67## Tool Use
68
69Issue independent tool calls together in one response rather than one at a time. Every round trip re-sends the whole conversation as cached input — measured at roughly half the cost of a call before it does any work — so fewer, wider steps beat many narrow ones.
70
71Redirect long-running commands to a log and poll a bounded view — a tail, a grep for errors, or a status sentinel. Re-reading a running command's output re-sends it from the start every time, so repeatedly checking a long build costs far more than the check is worth. Check the outcome, not the process.
72
73```bash
74<cmd> > out.log 2>&1; echo "exit=$?" > out.status # bash
75<cmd> *> out.log; "exit=$LASTEXITCODE" | Out-File out.status # PowerShell -- $? is a [bool] here
76```
77
78Fetch narrowly: `gh run view --log-failed` over `--log`, `--json`/`--jq` to project only the fields needed, `git diff --stat` before the full diff. Quiet what doesn't detect a non-TTY: `curl -sS`, `--quiet` on `git clone`/`fetch`/`checkout`. MSBuild and `dotnet` already detect it — no flags needed.
79
80## Building & Testing
81
82**Before running any build or test command, use the `build-and-test` skill** — don't guess the commands. Under CCA, invoke it **before making any code changes**; a missing or incorrect baseline build costs 20-40 minutes to recover from.
83
dotnet/runtime · .github/instructions/conventions.instructions.md
@@ +1 @@
1---
2applyTo: "src/**"
3---
4
5# General Conventions (all source areas)
6
7Code conventions for any change under `src/`, applied when authoring and when reviewing. Also
8apply the language file for the code in question (`csharp`, `native`), `tests` for test changes,
9and any matching area file (`core-runtime`, `jit`, `system-net-*`, `extensions-*`, `compression`,
10`cdac`). Where a more specific file conflicts with a general one, the more specific file wins.
11
12Pull-request process — scope, benchmark evidence, API approval, backport — is in
13[`copilot-instructions.md`](/.github/copilot-instructions.md). Build and test workflow is in the
14`build-and-test` skill. Review-only criteria are in `.github/skills/code-review/pr-assessment.md`.
15
16## Change Scope & Justification
17
18- **Prefer the simplest solution that works.** The burden of proof is on the more complex approach. Unnecessary abstraction, extra indirection, and elaborate solutions for marginal gains are a cost, not a feature.
19- **Justify each addition.** New code, APIs, abstractions, and flags create a permanent maintenance obligation. If an addition can be avoided without sacrificing correctness or meaningful capability, avoid it.
20- **Fix root cause, not symptoms or workarounds.** Investigate and fix the root cause rather than adding workarounds or suppressing warnings. Revert broken commits before layering fixes.
21- **Don't bundle unrelated changes.** Keep each change to a single concern: no drive-by refactoring, no whitespace noise, no build artifacts. Large refactorings and mechanical renames belong in their own change, separate from logic changes.
22
23## Consistency with Codebase Patterns
24
25### Code Reuse & Deduplication
26
27- **Extract duplicated logic into shared helper methods.** Fix improvements inside shared helpers so all callers benefit.
28- **Move shared code to shared files, not duplicated across runtimes.** When identical code exists across CoreCLR and NativeAOT, move it to the shared partition (using `#if !MONO` if needed).
29- **Use existing APIs instead of creating parallel ones.** Before introducing new types, enums, or helpers, check if existing ones serve the same purpose. Fix existing utilities rather than introducing duplicates.
30- **Delete dead code and unused declarations aggressively.** Remove dead code, unnecessary wrappers, obsolete fields, and unused variables when encountered or when the only caller changes. Also remove helper methods, enum values, function declarations, and resx strings left unused by a removal.
31
32### Established Conventions
33
34- **Store error strings in `.resx`, not inline code.** Reference via the `SR` class. When removing code that uses a resx string, delete the unused string entry.
35- **Preserve existing alphabetical ordering in modified lists.** When a PR adds or reorders entries in an alphabetized list—especially items within a `.csproj` item group, such as `Compile`, `ProjectReference`, and `PackageReference`—verify that the changed entries preserve the surrounding order. Flag only ordering regressions introduced by the PR; do not require unrelated cleanup of pre-existing unsorted entries. This also applies to lists of areas, configuration entries, resx entries, entrypoint/export lists, and ref source members.
36- **Don't modify auto-generated files or `eng/common` manually.** Change the generator or source definition instead. Files in `eng/common` are synced from dotnet/arcade.
37- **Use `DOTNET_` prefix for environment variables, not `COMPlus_`.** New runtime environment variables must use `DOTNET_` exclusively.
38- **Match existing style in modified files.** The existing style in a file takes precedence over general guidelines. Do not change existing code for style alone.
39
40### Runtime-Specific Patterns
41
42- **Consider NativeAOT parity for runtime changes.** When changing CoreCLR behavior, verify whether the same change is needed for NativeAOT. Note: Mono and CoreCLR native code conventions differ significantly — do not assume they share the same rules.
43- **Keep interpreter behavior consistent with the regular JIT.** Follow the same patterns, naming, error codes (`CORJIT_BADCODE`), and macros (`NO_WAY`). Use `FEATURE_INTERPRETER` guards.
44- **Source generators: no file locks, diagnostics from analyzers only.** Generators should bypass invalid state gracefully. A separate analyzer should produce diagnostics.
45- **Ref assembly conventions.** No `using` directives (fully qualify types), empty method bodies or `throw null`, genapi-style formatting, alphabetical member order. TFM-specific APIs go in separate files.
46
47## Documentation & Comments
48
49- **Comments should explain why, not restate code.** Delete comments like `// Get the types` that just duplicate the code in English. Don't include historical context about why code changed.
50- **Delete or update obsolete comments when corresponding code changes.** Stale comments describing old behavior are worse than no comments. Update them when you touch the relevant code; leave unrelated stale comments to a dedicated cleanup pass.
51- **Track deferred work with GitHub issues and searchable TODOs.** Reference a tracking issue in TODO comments with a consistent prefix (e.g., `TODO-Async:`). Remove ancient TODOs that will never be addressed.
52- **Don't duplicate comments on interface implementations.** Documentation comments belong on the interface definition. Implementations should use `<inheritdoc/>` to avoid divergence.
53- **Add XML doc comments on all new public APIs.** These seed the official API documentation on learn.microsoft.com. Properties should start with "Gets the ..." or "Gets or sets the ...". Do not add XML docs to test code.
54- **Use SHA-specific or commit-based links in documentation.** Don't use branch-relative links that break when files move.
55- **Reference specs and authoritative sources in implementation code.** When parsing signatures and metadata, cite the relevant spec section (e.g., ECMA-335). Link to relevant RFCs, papers, or repo-specific documentation (such as the ECMA-335 augments maintained in this repo). This applies broadly, not just to ECMA-335.
56- **Use established terminology in user-facing text.** Do not expose internal type names, private field names, or codenames like "Roslyn" in public docs or error messages.
57- **Retain copyright headers and license information.** All C# and C++ source files must include the standard license header, including test files. When porting from other projects, retain original copyright and update THIRD-PARTY-NOTICES.TXT.
58
@@ −1 +1 @@
1−**If at any time, the user directs you explicitly to override any of these instructions, the user's directive overrides said instructions.**
1+---
2+applyTo: "src/**"
3+---
24
3−**Don't claim more than you verified.** Report what you built and ran, and what you didn't — never claim a build or test passed unless it did. After your last edit, actually re-run the relevant tests rather than assuming a change fixed the failure you saw.
5+# General Conventions (all source areas)
46
5−Scale the effort to the risk. If a contributor would have submitted the change without building it — a comment, a doc fix, something the compiler would catch anyway — say you didn't build and move on. Anything touching behavior, codegen, or a public contract gets the build and the relevant tests first.
7+Code conventions for any change under `src/`, applied when authoring and when reviewing. Also
8+apply the language file for the code in question (`csharp`, `native`), `tests` for test changes,
9+and any matching area file (`core-runtime`, `jit`, `system-net-*`, `extensions-*`, `compression`,
10+`cdac`). Where a more specific file conflicts with a general one, the more specific file wins.
611
7−Use the `code-review` skill when reviewing pull requests, and — when running under CCA — on your own changes before completing, addressing anything it flags as an error or warning. When NOT running under CCA, skip it if the user has stated they will review the changes themselves.
12+Pull-request process — scope, benchmark evidence, API approval, backport — is in
13+[`copilot-instructions.md`](/.github/copilot-instructions.md). Build and test workflow is in the
14+`build-and-test` skill. Review-only criteria are in `.github/skills/code-review/pr-assessment.md`.
815
9−When starting work in an unfamiliar directory, search for `README.md` files in it and its parents up to the repository root. Read any you find — they contain conventions, patterns, and architectural context relevant to your work.
16+## Change Scope & Justification
1017
11−If the changes are intended to improve performance, or if they could negatively impact performance, use the `performance-benchmark` skill to validate the impact before completing.
18+- **Prefer the simplest solution that works.** The burden of proof is on the more complex approach. Unnecessary abstraction, extra indirection, and elaborate solutions for marginal gains are a cost, not a feature.
19+- **Justify each addition.** New code, APIs, abstractions, and flags create a permanent maintenance obligation. If an addition can be avoided without sacrificing correctness or meaningful capability, avoid it.
20+- **Fix root cause, not symptoms or workarounds.** Investigate and fix the root cause rather than adding workarounds or suppressing warnings. Revert broken commits before layering fixes.
21+- **Don't bundle unrelated changes.** Keep each change to a single concern: no drive-by refactoring, no whitespace noise, no build artifacts. Large refactorings and mechanical renames belong in their own change, separate from logic changes.
1222
13−When writing or reviewing SIMD / hardware-intrinsics code (anything using `Vector128`/`Vector256`/`Vector512`, `Vector<T>`, or the platform intrinsics in `System.Runtime.Intrinsics.*`), use the `vectorization` skill.
23+## Consistency with Codebase Patterns
1424
15−You MUST follow all code-formatting and naming conventions defined in [`.editorconfig`](/.editorconfig).
25+### Code Reuse & Deduplication
1626
17−In addition to the rules enforced by `.editorconfig`, when writing C# you SHOULD:
27+- **Extract duplicated logic into shared helper methods.** Fix improvements inside shared helpers so all callers benefit.
28+- **Move shared code to shared files, not duplicated across runtimes.** When identical code exists across CoreCLR and NativeAOT, move it to the shared partition (using `#if !MONO` if needed).
29+- **Use existing APIs instead of creating parallel ones.** Before introducing new types, enums, or helpers, check if existing ones serve the same purpose. Fix existing utilities rather than introducing duplicates.
30+- **Delete dead code and unused declarations aggressively.** Remove dead code, unnecessary wrappers, obsolete fields, and unused variables when encountered or when the only caller changes. Also remove helper methods, enum values, function declarations, and resx strings left unused by a removal.
1831
19−- Prefer file-scoped namespace declarations and single-line using directives.
20−- Ensure that the final return statement of a method is on its own line.
21−- Use pattern matching and switch expressions wherever possible.
22−- Use `nameof` instead of string literals when referring to member names.
23−- Always use `is null` or `is not null` instead of `== null` or `!= null`.
24−- Trust the C# null annotations and don't add null checks when the type system says a value cannot be null.
25−- Prefer `?.` if applicable (e.g. `scope?.Dispose()`).
26−- Use `ObjectDisposedException.ThrowIf` where applicable.
27−- If you add new code files, ensure they are listed in the csproj file (if other files in that folder are listed there) so they build.
28−- When adding XML documentation to APIs, follow the guidelines at [`docs.prompt.md`](/.github/prompts/docs.prompt.md).
32+### Established Conventions
2933
30−When writing or modifying tests, you SHOULD:
34+- **Store error strings in `.resx`, not inline code.** Reference via the `SR` class. When removing code that uses a resx string, delete the unused string entry.
35+- **Preserve existing alphabetical ordering in modified lists.** When a PR adds or reorders entries in an alphabetized list—especially items within a `.csproj` item group, such as `Compile`, `ProjectReference`, and `PackageReference`—verify that the changed entries preserve the surrounding order. Flag only ordering regressions introduced by the PR; do not require unrelated cleanup of pre-existing unsorted entries. This also applies to lists of areas, configuration entries, resx entries, entrypoint/export lists, and ref source members.
36+- **Don't modify auto-generated files or `eng/common` manually.** Change the generator or source definition instead. Files in `eng/common` are synced from dotnet/arcade.
37+- **Use `DOTNET_` prefix for environment variables, not `COMPlus_`.** New runtime environment variables must use `DOTNET_` exclusively.
38+- **Match existing style in modified files.** The existing style in a file takes precedence over general guidelines. Do not change existing code for style alone.
3139
32−- Strongly prefer to add new unit tests to existing test code files rather than creating new code files.
33−- When adding new test files, examine the directory structure of sibling tests first. Some test directories use flat files (e.g., `GCEvents.cs` alongside `GCEvents.csproj`) while others use per-test subdirectories. Match the existing convention.
34−- Avoid adding a regression comment citing a GitHub issue or PR number unless explicitly asked to include such information.
35−- Prefer using `[Theory]` with multiple data sources (like `[InlineData]` or `[MemberData]`) over multiple duplicative `[Fact]` methods. Fewer test methods that validate more inputs are better than many similar test methods.
36−- When running tests, if possible use filters and check test run counts, or look at test logs, to ensure they actually ran.
37−- Do not finish work with any tests commented out or disabled that were not previously commented out or disabled.
38−- Do not emit "Act", "Arrange" or "Assert" comments.
40+### Runtime-Specific Patterns
3941
40−For markdown (`.md`) files, ensure there is no trailing whitespace at the end of any line.
42+- **Consider NativeAOT parity for runtime changes.** When changing CoreCLR behavior, verify whether the same change is needed for NativeAOT. Note: Mono and CoreCLR native code conventions differ significantly — do not assume they share the same rules.
43+- **Keep interpreter behavior consistent with the regular JIT.** Follow the same patterns, naming, error codes (`CORJIT_BADCODE`), and macros (`NO_WAY`). Use `FEATURE_INTERPRETER` guards.
44+- **Source generators: no file locks, diagnostics from analyzers only.** Generators should bypass invalid state gracefully. A separate analyzer should produce diagnostics.
45+- **Ref assembly conventions.** No `using` directives (fully qualify types), empty method bodies or `throw null`, genapi-style formatting, alphabetical member order. TFM-specific APIs go in separate files.
4146
42−## Pull Requests
47+## Documentation & Comments
4348
44−- **One concern per PR.** Split large or mixed changes. Do large refactorings and mechanical renames in their own PR, separate from logic changes.
45−- **New public API requires an approved proposal before submission** — PRs adding unapproved API will be closed. Use the `api-proposal` skill; until approval lands the API stays `internal` in any submitted PR. A proposal's prototype branch is exempt and keeps its surface public — it's evidence, not a submission.
46−- **Core component changes should start with an issue.** Changes to the host, VM, or JIT need a GitHub issue describing the problem and motivation first.
47−- **Put the measurements in the description** for performance changes — BenchmarkDotNet results, or codegen and instruction-count evidence for low-level work.
48−- **Behavioral changes need breaking-change documentation**, even prerelease-to-prerelease. Use the `breaking-change-doc` skill.
49−- **Merge to main first, then `/backport`.** Servicing backports are limited to security bugs, regressions, and reliability issues, and should be small targeted fixes rather than refactorings.
50−- **A push to an open PR re-runs its CI matrix** — dozens of jobs, over a hundred for broad changes. For anything non-trivial, validate locally rather than using CI to find out whether it builds, and batch fixes into one push. Branches with no PR trigger nothing, as do changes confined to `**.md`, `docs/*`, or `.github/*`.
51−- **Treat review feedback as a sample, not a list.** A reviewer flags examples of a problem, not every instance. Grep for the rest of the class and fix it in the same push, and answer a whole round of comments at once rather than pushing per comment.
52−
53−When NOT running under CCA, for commits and pushes:
54−
55−- Never squash and force push unless explicitly instructed. Always push incremental commits on top of previous PR changes.
56−- Never push to an active PR without being explicitly asked, even in autopilot/yolo mode. Always wait for explicit instruction to push.
57−- Never chain commit and push in the same command. Always commit first, report what was committed, then wait for an explicit push instruction. This creates a mandatory decision point.
58−- Prefer creating a new commit rather than amending an existing one. Exceptions: (1) explicitly asked to amend, or (2) the existing commit is obviously broken with something minor (e.g., typo or comment fix) and hasn't been pushed yet.
59−- **Before posting to GitHub (PRs, issues, comments):** Include the AI-generated content disclosure (see below).
60−
61−## AI-Generated Content Disclosure
62−
63−When posting to GitHub under a user's credentials — PR descriptions, issue bodies, comments, review comments, or any other public-facing action — you **MUST** add a concise, visible note (e.g. a `> [!NOTE]` alert) at the bottom of the content indicating it was AI/Copilot-generated. Skip it only when posting from a recognized bot or Copilot app account (e.g. `github-actions[bot]`, `copilot`), where the AI origin is already apparent from the account identity, or when the user explicitly asks you to omit it.
64−
65−---
66−
67−## Tool Use
68−
69−Issue independent tool calls together in one response rather than one at a time. Every round trip re-sends the whole conversation as cached input — measured at roughly half the cost of a call before it does any work — so fewer, wider steps beat many narrow ones.
70−
71−Redirect long-running commands to a log and poll a bounded view — a tail, a grep for errors, or a status sentinel. Re-reading a running command's output re-sends it from the start every time, so repeatedly checking a long build costs far more than the check is worth. Check the outcome, not the process.
72−
73−```bash
74−<cmd> > out.log 2>&1; echo "exit=$?" > out.status # bash
75−<cmd> *> out.log; "exit=$LASTEXITCODE" | Out-File out.status # PowerShell -- $? is a [bool] here
76−```
77−
78−Fetch narrowly: `gh run view --log-failed` over `--log`, `--json`/`--jq` to project only the fields needed, `git diff --stat` before the full diff. Quiet what doesn't detect a non-TTY: `curl -sS`, `--quiet` on `git clone`/`fetch`/`checkout`. MSBuild and `dotnet` already detect it — no flags needed.
79−
80−## Building & Testing
81−
82−**Before running any build or test command, use the `build-and-test` skill** — don't guess the commands. Under CCA, invoke it **before making any code changes**; a missing or incorrect baseline build costs 20-40 minutes to recover from.
49+- **Comments should explain why, not restate code.** Delete comments like `// Get the types` that just duplicate the code in English. Don't include historical context about why code changed.
50+- **Delete or update obsolete comments when corresponding code changes.** Stale comments describing old behavior are worse than no comments. Update them when you touch the relevant code; leave unrelated stale comments to a dedicated cleanup pass.
51+- **Track deferred work with GitHub issues and searchable TODOs.** Reference a tracking issue in TODO comments with a consistent prefix (e.g., `TODO-Async:`). Remove ancient TODOs that will never be addressed.
52+- **Don't duplicate comments on interface implementations.** Documentation comments belong on the interface definition. Implementations should use `<inheritdoc/>` to avoid divergence.
53+- **Add XML doc comments on all new public APIs.** These seed the official API documentation on learn.microsoft.com. Properties should start with "Gets the ..." or "Gets or sets the ...". Do not add XML docs to test code.
54+- **Use SHA-specific or commit-based links in documentation.** Don't use branch-relative links that break when files move.
55+- **Reference specs and authoritative sources in implementation code.** When parsing signatures and metadata, cite the relevant spec section (e.g., ECMA-335). Link to relevant RFCs, papers, or repo-specific documentation (such as the ECMA-335 augments maintained in this repo). This applies broadly, not just to ECMA-335.
56+- **Use established terminology in user-facing text.** Do not expose internal type names, private field names, or codenames like "Roslyn" in public docs or error messages.
57+- **Retain copyright headers and license information.** All C# and C++ source files must include the standard license header, including test files. When porting from other projects, retain original copyright and update THIRD-PARTY-NOTICES.TXT.
8358
