docs(agents): self-documenting code + <summary>/<remarks> guidance

[LukaszRozmej]

Changes

• Add a "self-documenting code" rule to AGENTS.md: emit comments only when they capture context that isn't obvious from the code (the why, invariants, workarounds, EIP/Yellow-Paper refs, subtle edge cases). Comments that merely restate the code are noise.
• Prefer XML doc comments over in-line comments when the explanation applies to the method as a whole, with a clear split:
  • <summary> — one or two sentences describing the method's contract from the caller's perspective; short enough for IntelliSense; no implementation, no rationale.
  • <remarks> — the longer-form: algorithm, design rationale, invariants, thread-safety, performance, side effects, edge cases, EIP/spec references, caveats.
  • Use <param>, <returns>, <exception>, <typeparam> for their respective concerns rather than stuffing into <summary> / <remarks>.
• Reserve in-line comments for implementation-specific details that can't reasonably live on the method header (why a branch is taken, why a value is computed this way at this exact spot, local workarounds).

This complements the existing coding-style.md rule "comments explain why, not what" by giving agents concrete guidance on where to put the explanation.

Types of changes

• Documentation update

Testing

Requires testing

• No

Documentation

Requires documentation update

• No

Requires explanation in Release Notes

• No

[claude]

Claude finished @LukaszRozmej's task in 1m 14s —— View job

---

Review

• Gather context
• Read changed files and rule files
• Review for correctness and consistency
• Post findings

---

The changes are clear, well-written, and correct. The <summary> / <remarks> split is the idiomatic C# pattern, and the "self-documenting code first, comment only the why" principle is consistent with coding-style.md line 19 (Code comments explain _why_, not _what_) and line 20 (EIP/Yellow-Paper references). No critical, high, or medium issues.

Two low-severity observations worth considering (neither blocks merge):

Low — Scope is method-only, but properties/constructors/classes also benefit

The bullet says "method-level documentation", but the same <summary>/<remarks>/<param>/<returns> discipline applies equally to constructors, properties, and type declarations. coding-style.md line 21 already mandates XML docs on config property keys. Widening the framing to "member-level" or adding a brief note about properties would close this gap. Fix this →

Low — No mention of <inheritdoc>

When a class implements an interface or overrides a base, /// <inheritdoc/> is the idiomatic way to propagate the contract doc without duplication. A one-liner noting it as the preferred approach for implementing members would complement the new guidance.

Minor consistency note (out of scope for this PR)

coding-style.md line 12 lists only <summary>, <param>, <returns> as the canonical tags for public APIs. A follow-up to add <remarks> and <exception> there would keep both files in sync.

---

Overall: clean, well-scoped documentation improvement. The guidance is actionable and fills a real gap for agents writing or reviewing C# doc comments.

[LukaszRozmej]

@claude review

[claude]

Claude finished @LukaszRozmej's task in 1m 0s —— View job

---

Review

• Gather context
• Read changed files and rule files
• Review for correctness and consistency
• Post findings

---

The three commits in this PR progressively build out documentation guidance — the latest state of AGENTS.md (lines 18–24) is well-structured, internally consistent, and aligns cleanly with the existing rules.

What the previous review flagged → now resolved:

• "member-level" scope — commit 1eb8efb widened the framing from "method-level" to "member-level (methods, constructors, properties, types)". Done.
• <inheritdoc/> — same commit added the bullet on interface implementations and overrides. Done.

Remaining observations (all Low — do not block merge):

Low — coding-style.md line 12 is now narrower than AGENTS.md

coding-style.md:12 lists <summary>, <param>, <returns> as the canonical tags for public APIs. The new AGENTS.md guidance additionally covers <remarks>, <exception>, and <typeparam>. There is no contradiction — AGENTS.md is a superset — but a follow-up to add <remarks> and <exception> to line 12 of coding-style.md would keep both files in sync and avoid agents applying a narrower tag set when reading only coding-style.md. Not urgent given the rule files cross-reference each other, but worth a small follow-up PR.

No Critical, High, or Medium findings. Clear to merge.

[LukaszRozmej]

@claude re-review

[claude]

Claude finished @LukaszRozmej's task in 1m 7s —— View job

---

Re-review

• Gather context
• Read changed files and rule files
• Review for correctness and consistency
• Post findings

---

Current state of AGENTS.md lines 18–24 is accurate, internally consistent, and correctly addresses all issues flagged in prior reviews:

What previous reviews flagged → resolved:

• "member-level" scope (commit 1eb8efb) — Done.
• <inheritdoc/> guidance (commit 1eb8efb) — Done.

Remaining observation (Low — does not block merge):

Low — coding-style.md line 12 is still narrower than AGENTS.md

coding-style.md:12 lists <summary>, <param>, <returns> as the canonical tags for public APIs. The new AGENTS.md guidance covers <remarks>, <exception>, and <typeparam> as well. No contradiction exists — AGENTS.md is a superset — but an agent reading only coding-style.md would apply a narrower tag set. A small follow-up to coding-style.md:12 would close the gap. Fix this →

---

No Critical, High, or Medium findings. Clear to merge.