AGENTS.md

Modification Guidelines

These guidelines apply to all changes made in this repository.

Documentation

• Fully document all API surface areas affected by a change, including both external and internal APIs.
• Treat documentation as part of the feature, not as optional follow-up work.
• Include reference content that explains the API shape, behavior, defaults, constraints, and expected usage.
• Include decision content that explains why an API exists, when it should be used, and when a different approach is the better choice.
• Include pitfall content that calls out sharp edges, ordering requirements, surprising behavior, and common mistakes.
• Update package-level and repository-level documentation when a change affects discoverability or adoption, not just inline XML comments.

Tests

• Aim for nearly 100% branch verification coverage, especially in changed code and critical execution paths.
• Test both success paths and failure or edge-case branches.
• Test behavior through public APIs and internal APIs that are intentionally exposed for testing.
• Do not use reflection in tests to access private members.
• If code is difficult to verify without reflection, improve the design or add an appropriate test seam instead of breaking encapsulation.
• Add regression tests for bug fixes.
• When practical, verify solution-level coverage with ./scripts/coverage-solution.sh.

Code Quality

• Run code formatting before pushing changes.
• Follow the repository .editorconfig and established formatting conventions rather than personal preferences.
• Resolve all compiler, analyzer, and documentation warnings introduced by a change before pushing.
• Prefer changes that reduce existing warnings in touched areas instead of working around them or suppressing them without strong justification.
• Follow current C# and .NET best practices so code is clear, idiomatic, and maintainable.