docs(AGENTS): test-parametrization, serialization-test & architecture conventions

[polyglotAI-bot]

Summary

Adds three sets of conventions to AGENTS.md that maintainers have asked for repeatedly in recent PR reviews, so every agent (and human contributor) applies them up front instead of during review round-trips.

Testing expectations

• Use a TestNG @DataProvider (one parametrized test) instead of several near-identical test methods.
• Keep issue/PR-number references and narrative comments out of test code.
• For serialization/round-trip tests, place the field under test mid-schema with a trailing fixed-width column and assert the whole row, so a byte misalignment is actually detected.
• Prefer integration tests over unit-only tests for read/deserialization behavior that flows through the runtime path.

Architecture conventions (new section)

• Value/parameter conversion belongs on the value-converter classes as reusable instance methods (no static formatters); transport code receives already-formatted values.
• Prefer an explicit ArrayDeque stack over recursion for arbitrarily nested containers.
• Read-path (DateTime/timezone) fixes belong in client-v2 BinaryStreamReader, not clickhouse-data ClickHouseColumn.

Why

These mirror concrete review feedback on recent PRs (e.g. #2886, #2898, #2877): data-provider tests, "we do not reference issues or comment tests much", the mid-row serialization-test technique, converting unit tests to integration tests, the value-converter/transport separation, using a stack instead of recursion, and fixing the read path in BinaryStreamReader.

Docs-only change — no code or test behavior affected.

🤖 Generated with Claude Code

[github-actions]

Repository collaborators can run the JMH benchmark suite against this PR by commenting:

/benchmark

Optional regression threshold override (Δ% on Time or Alloc/op; defaults to 10%):

/benchmark threshold=15

Only one benchmark run per PR is active at a time — issuing a new /benchmark comment cancels the previous run. After the run finishes a separate comment will be posted comparing it against the latest scheduled run on main; the PR check fails if any benchmark regresses by more than the threshold.