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:

Detailed Technical Instructions

The .github/instructions/ directory contains comprehensive guides:

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.

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

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

• Microsoft.Data.SqlClient on Microsoft Learn
• MS-TDS Protocol Specification
• SQL Server Documentation

Repository Policies

See the policy/ directory for:

• coding-best-practices.md - Programming standards
• coding-style.md - Code formatting guidelines
• review-process.md - PR review requirements

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.