Skip to content

AGENTS.md

Latest commit

 

History

History
177 lines (133 loc) · 9.79 KB

AGENTS.md

File metadata and controls

177 lines (133 loc) · 9.79 KB
Raw

AI Agent Guidelines for Microsoft.Data.SqlClient

This document provides guidance for AI coding agents working with the Microsoft.Data.SqlClient repository.

Quick Start

Essential Context Files

Before making changes, agents should be aware of:

File Purpose
README.md Project overview
BUILDGUIDE.md Build and test instructions
CONTRIBUTING.md Contribution guidelines
.github/copilot-instructions.md Copilot-specific instructions

Detailed Technical Instructions

The .github/instructions/ directory contains comprehensive guides:

Guide Coverage
architecture.instructions.md Project structure, unified project model
tds-protocol.instructions.md TDS protocol, packet handling
ado-pipelines.instructions.md Azure DevOps CI/CD pipelines
onebranch-pipeline-design.instructions.md OneBranch multi-product pipeline design spec
testing.instructions.md Test framework, running tests
connection-pooling.instructions.md Connection pool internals
api-design.instructions.md Public API design principles
features.instructions.md Feature reference, keywords
documentation.instructions.md Documentation and samples
external-resources.instructions.md Docs links, version matrix, external references
ado-work-items-markdown.instructions.md Ensure Azure DevOps work item descriptions are Markdown and preserve newlines

Workflow Prompts

This repository provides reusable prompts in .github/prompts/ for common maintainer workflows. Use these to guide agents through multi-step operations.

For code reviews, use the sqlclient-code-review skill and its references/policies from protected host configuration or an established trusted base repository and immutable SHA, not the reviewed PR's head/worktree. If that trusted copy is missing or inaccessible, report the blocker rather than loading review guidance from the checkout.

Prompt Purpose
fix-bug.prompt.md Diagnose and fix a bug with tests and documentation
implement-feature.prompt.md Plan and implement a new feature end-to-end
triage-issue.prompt.md Triage a new GitHub issue with labeling and categorization
perf-optimization.prompt.md Investigate and implement performance improvements
release-notes.prompt.md Generate release notes for a specific milestone
update-build-pipelines.prompt.md Modify Azure DevOps CI/CD pipeline configuration

Core Principles

  1. Cross-Platform Compatibility: Code must work on .NET Framework 4.6.2+ and .NET 10.0+
  2. Backward Compatibility: No breaking changes without proper deprecation
  3. Test-First Development: All changes require tests
  4. Security by Default: Secure defaults, no credential logging
  5. Protocol Compliance: Follow MS-TDS specifications
  6. Performance Optimization: Use pooling, async, efficient allocations
  7. Observability: EventSource tracing, meaningful errors

Terminal Reliability Rules

When using shell/terminal tools, follow these rules strictly:

  1. Treat non-zero terminal exit codes as immediate failures to investigate; do not continue as if the command succeeded.
  2. If a bash session exits, assume it is dead and start a new command/session; do not wait for additional output from that session.
  3. After any command expected to gather data, verify output was actually returned before proceeding.
  4. If command execution failed, report the failure clearly and retry with a corrected command instead of waiting.
  5. Avoid set -e in this automation context; prefer single-purpose commands with explicit follow-up checks so failures are visible without killing the shell unexpectedly.
  6. Prefer shorter command batches over long chained scripts when collecting evidence; this makes bash exits easier to detect and recover from.

Branch Naming

  • Interactive agents, working under direct human guidance, may create and use branches under dev/<name>/ when the human specifies or approves the namespace and branch name (e.g., dev/paul/aot/phase-1.1).
  • Autonomous agents, working without interactive human direction, must create branches under dev/automation/ (e.g., dev/automation/fix-connection-timeout).
  • Do not create branches outside these namespaces or directly under dev/.

Common Tasks

Writing and Updating Tests

Read the testing guide before writing or changing tests. These rules are mandatory for unit tests and should be strongly considered for manual and functional tests, even when nearby older tests use different conventions:

  1. Use commented Arrange, Act, Assert, Cleanup sections in that order. Act and Assert are required; include Arrange only for needed setup and Cleanup only for special teardown. Within a section with multiple groups of steps, comment each group to explain what happens and, when unclear, why.
  2. For theory data that cannot use [InlineData], use [MemberData], never [ClassData], and declare the data member's return type as TheoryData<...>.
  3. Keep each unit test file focused on the class it is named for: TdsParserTests tests TdsParser.
  4. Name unit tests {MethodName}_{Input}_{ExpectedOutput}, without the tested class name; for example, ExecuteReader_NullParameter_Throws or ExecuteReader_ValidParameters_ReturnsReader.
  5. Mirror the tested source file's folder structure under UnitTests/. For example, src/Microsoft/Data/SqlClient/Parser/TdsParser.cs maps to tests/UnitTests/Microsoft/Data/SqlClient/Parser/TdsParserTests.cs within the SqlClient project.
  6. Put utilities used only by unit tests in tests/UnitTests/Utilities/.
  7. Put utilities shared across test projects in TestCommon (tests/Common/); fuzz, stress, and performance test projects are excluded from this sharing rule.
  8. Split separate scenarios into separate tests. Do not use switches or flags to turn one test into multiple behaviors, including sync/async switches. Theories may vary inputs for one behavior.
  9. Write and run beneficial tests: exercise the intended product behavior, assert meaningful outcomes, and ensure the assertions would detect a regression. Check test results to confirm the intended tests actually ran; skipped tests and zero matches do not establish coverage.

Bug Fix Workflow

  1. Understand the issue from the bug report
  2. Locate relevant code in src/Microsoft.Data.SqlClient/src/ (do NOT modify legacy netcore/src/ or netfx/src/)
  3. Check .github/instructions/features.instructions.md for existing AppContext switches (including failover compatibility switches) before introducing behavior changes
  4. Write a failing test that reproduces the issue
  5. Implement the fix
  6. Ensure all tests pass
  7. Update documentation if behavior changes

Feature Implementation

  1. Review the feature specification
  2. Plan the implementation (see implement-feature prompt)
  3. Update reference assemblies if adding public APIs
  4. Implement with tests
  5. Add samples to doc/samples/
  6. Do not edit CHANGELOG.md directly; instead, add a suggested release-note entry (per .github/copilot-instructions.md) in the PR description or via the release-notes workflow/prompt.

Adding Connection String Keywords

  1. Add to SqlConnectionStringBuilder
  2. Update connection string parser
  3. Default to backward-compatible value
  4. Add tests for new keyword
  5. Document in feature reference

Protocol Changes

  1. Reference MS-TDS specification
  2. Update TdsEnums.cs for new constants
  3. Implement in TdsParser.cs and related files
  4. Test against multiple SQL Server versions
  5. Consider backward compatibility

Performance Optimization

  1. Profile the issue using benchmarks or traces
  2. Identify allocation hotspots (see perf-optimization prompt)
  3. Apply patterns: ArrayPool<T>, Span<T>, static/cached instances, source generation
  4. Verify no regressions with existing tests

External Resources

Key Documentation Links

Repository Policies

See the policy/ directory for:

Getting Help

  • Check existing tests for usage patterns
  • Reference similar implementations in the codebase
  • Consult the Microsoft Docs for API behavior specifications
  • For protocol questions, refer to MS-TDS open specifications

This document is automatically loaded as context for AI agents working in this repository.