Cline rules

1# C# Development Guidelines
2 
3These guidelines define how to write and modify C# code in this repo.
4They apply to both humans and coding agents.
5 
6> Note: Some rules are repeated intentionally (Quick rules + Detailed rules) to reduce “agent drift”
7> and prevent hallucinated changes. The Detailed rules are the source of truth.
8 
9## Quick rules (read first)
10 
11- Use the C# language version configured by the repo/tooling. Do not “upgrade” language features by editing build files.
12- Keep changes minimal and scoped to the request. Avoid drive-by refactors and style-only churn.
13- Never change these unless explicitly asked to:
14  - `global.json`
15  - `package.json` / `package-lock.json`
16  - `NuGet.config`
17- **No reflection in product code** (`/src`). (See “Reflection” section.)
18- Follow `.editorconfig` formatting.
19- Static fields must be `s_camelCase`. (Match local style for other fields.)
20- Prefer ordinal string comparisons for protocol/host/cache keys.
21- Nullability: prefer non-nullable, validate at boundaries, use `is null` / `is not null`.
22- Tests: MSTest SDK v3 + AAA comments + NSubstitute.
23 
24---
25 
26## General (Detailed rules)
27 
28### Language / tooling
29- Prefer modern C# features **when supported by the repo’s configured language version**.
30- Do not change `global.json` unless explicitly asked to.
31- Do not change repo/tooling versions or build configuration unless explicitly asked.
32 
33### File / dependency hygiene
34- Never change these unless explicitly asked to:
35  - `global.json`
36  - `package.json` / `package-lock.json`
37  - `NuGet.config`
38- Avoid adding/removing dependencies unless the task explicitly requires it.
39- Do not commit build/test artifacts:
40  - `bin/`, `obj/`, `TestResults/`, coverage outputs, temporary logs/dumps.
41 
42### “Don’t hallucinate” guardrails (for agents)
43- Do not invent new repo conventions. If unsure, follow nearby code patterns.
44- Do not introduce new abstractions/helpers unless there is an existing pattern in the repo.
45- Prefer small, reviewable commits and changes.
46 
47---
48 
49## Formatting
50 
51- Apply code-formatting style defined in `.editorconfig`.
52- Prefer file-scoped namespace declarations (when consistent with the file/project).
53- Prefer single-line using directives (when consistent with the file/project).
54- Insert a newline before the opening curly brace of any code block:
55  - `if`, `for`, `while`, `foreach`, `using`, `try`, `catch`, `finally`, etc.
56- Ensure that the final return statement of a method is on its own line.
57- Use pattern matching and switch expressions when they improve clarity (do not refactor solely to use them).
58- Use `nameof` instead of string literals when referring to member names.
59 
60---
61 
62## Naming & Style
63 
64- Follow naming conventions used in the same file/folder unless explicitly overridden here.
65 
66### Fields
67- **Private static fields must be `s_camelCase`** (including `static readonly`).
68  - Example: `private static readonly IDictionary<string, string> s_knownHosts = ...;`
69- Private instance fields: follow local style (commonly `_camelCase`).
70 
71### Constants
72- Use `PascalCase` for constants (unless the file uses a different established convention).
73 
74---
75 
76## Reflection & dynamic code (Product code)
77 
78**Do not use reflection in product code (`/src`)** unless explicitly requested or there is an established existing pattern in the same area that requires it.
79 
80Avoid introducing any of the following in product code:
81- `System.Reflection` APIs (e.g., `GetMethod`, `GetProperty`, `Invoke`, `BindingFlags`, etc.)
82- `Activator.CreateInstance(...)`
83- `Assembly.Load(...)` / dynamic assembly loading
84- `dynamic` dispatch used as a substitute for strong typing
85- `System.Reflection.Emit` / runtime IL generation
86 
87If an exception is unavoidable (rare):
88- Prefer a compile-time alternative first (generics, interfaces, explicit mappings).
89- Add a short comment explaining why reflection is required and what alternatives were rejected.
90- Keep reflection usage localized and test-covered.
91 
92Reflection is acceptable in:
93- Tests, tooling, benchmarks, or dev apps (unless those areas have their own constraints).
94 
95---
96 
97## Nullable Reference Types
98 
99- Declare variables non-nullable by default, and validate `null` at entry points.
100- Always use `is null` or `is not null` instead of `== null` or `!= null`.
101- Trust C# null annotations and avoid redundant null checks when the type system guarantees non-null.
102 
103---
104 
105## Exceptions & error handling
106 
107- Validate inputs at method boundaries (fail fast).
108- Throw the most specific exception type possible:
109  - `ArgumentNullException`, `ArgumentException`, `InvalidOperationException`, etc.
110- Do not swallow exceptions unless the behavior is expected and documented.
111- Do not include secrets/tokens/PII in exception messages or logs.
112 
113---
114 
115## Strings, comparisons, and culture
116 
117- Prefer ordinal comparisons for protocol values, identifiers, hostnames, headers, and cache keys:
118  - `StringComparison.Ordinal` / `StringComparison.OrdinalIgnoreCase`
119  - `StringComparer.Ordinal` / `StringComparer.OrdinalIgnoreCase`
120- Avoid culture-sensitive comparisons unless the string is user-facing (rare in libraries).
121 
122---
123 
124## Documentation
125 
126- Ensure that XML doc comments are created for any public APIs.
127  - When applicable, include `<example>` and `<code>` documentation in the comments.
128- Public API tracking rules exist in a separate guideline doc—follow that doc when public surface area changes.
129 
130---
131 
132## Testing
133 
134- We use MSTest SDK v3 for tests.
135- Emit `// Arrange`, `// Act`, `// Assert` comments.
136- Use NSubstitute for mocking in tests.
137- Copy existing style in nearby files for test method names and capitalization.
138- Prefer deterministic tests (avoid timing flakiness, environment dependence).
139 
140---
141 
142## Running tests
143 
144- To build and run tests in the repo, run `dotnet test`.
145  - You need one solution open, or specify the solution explicitly.
146- If the repo uses solution-specific or `msbuild` workflows for official validation, follow those.
147