[Storage] Add AGENTS.md guidance files for shared, blobs, datalake, and file shares

sdk/storage/AGENTS.md

@@ -0,0 +1,144 @@
+# AGENTS.md
+
+This file provides guidance for AI agents working in `sdk/storage` of the Azure SDK for C++ repository.
+
+## Scope
+
+This AGENTS file applies to:
+
+- `sdk/storage/**`
+- Cross-cutting storage concepts shared across blobs, file shares, datalake, queues, and storage common.
+
+This file supplements the repository-root guidance in `/AGENTS.md`.  
+Agents working in `sdk/storage` must follow both files: apply root repository-wide policies first, then apply storage-specific guidance from this file.
+
+For service-specific guidance, prefer the local AGENTS files:
+
+- `sdk/storage/azure-storage-blobs/AGENTS.md`
+- `sdk/storage/azure-storage-files-datalake/AGENTS.md`
+- `sdk/storage/azure-storage-files-shares/AGENTS.md`
+
+If guidance conflicts, the most local AGENTS file takes precedence.
+
+---
+
+## Storage Architecture Basics (C++ SDK)
+
+Azure Storage packages in this repo generally follow this layering:
+
+1. **azure-core**  
+   HTTP pipeline, credentials, retries, diagnostics, policies, transport abstractions.
+
+2. **azure-storage-common**  
+   Shared storage primitives (SAS helpers, shared key auth policy integrations, common request/response helpers, shared models).
+
+3. **Service libraries**
+   - `azure-storage-blobs`
+   - `azure-storage-files-datalake`
+   - `azure-storage-files-shares`
+   - `azure-storage-queues`
+
+### Typical client structure
+
+Storage libraries commonly expose:
+
+- **Service clients** (account/service-level operations)
+- **Container/share/filesystem clients** (scope-level operations)
+- **Item clients** (blob/file/path/message operations)
+- **Options/Models** for API inputs and outputs
+
+Maintain consistency with existing naming, API style, and option-object patterns.
+
+---
+
+## Agent Priorities
+
+When making changes, prioritize:
+
+1. **API consistency** with surrounding storage clients.
+2. **Minimal diff** and surgical edits.
+3. **Backward compatibility** for public APIs.
+4. **Tests first/with changes** (unit + live/recording updates as needed).
+5. **Documentation and changelog updates** where required.
+
+---
+
+## Do / Don't
+
+### Do
+
+- Follow existing patterns in neighboring storage packages before introducing new abstractions.
+- Reuse shared helpers in `azure-storage-common` when appropriate.
+- Keep error handling aligned with azure-core and existing storage behavior.
+- Preserve ABI/API compatibility unless explicitly requested and reviewed.
+- Add or update tests for every functional change.
+- Keep generated code and hand-written code boundaries intact.
+
+### Don't
+
+- Don't introduce breaking public API changes without explicit review.
+- Don't duplicate common logic that belongs in storage common.
+- Don't hardcode secrets, account keys, SAS tokens, or connection strings.
+- Don't manually edit generated assets when source-generation workflow is expected.
+- Don't broaden scope into unrelated storage services in one change.
+
+---
+
+## Key Concepts Agents Should Understand
+
+- **Authentication modes:** Shared Key, SAS, TokenCredential (Microsoft Entra ID via azure-identity).
+- **SAS types:** account SAS, service SAS, user delegation SAS.
+- **Conditional requests:** ETag / match conditions.
+- **Data integrity:** transactional hashes/validation where supported.
+- **Paging:** continuation tokens and pageable responses.
+- **Retries/timeouts:** pipeline retry policies and per-call options.
+- **Service-version-sensitive behavior:** preserve compatibility and existing defaults.
+
+---
+
+## Testing Guidance
+
+Before finalizing changes:
+
+1. Build impacted storage package(s).
+2. Run targeted tests for the modified package.
+3. If request/response wire behavior changes, ensure playback/recording compatibility strategy is considered.
+4. Prefer narrowly scoped tests over broad suite expansion unless needed.
+
+Use PLAYBACK mode for fast validation where applicable, and only require LIVE/RECORD updates when behavior actually changed.
+
+---
+
+## Expected Change Hygiene
+
+For non-trivial changes:
+
+- Update package `CHANGELOG.md`.
+- Ensure samples/docs remain accurate.
+- Keep includes, namespaces, and public headers aligned with package conventions.
+- Validate CMake updates are minimal and correctly scoped to the package.
+
+---
+
+## Escalation / Human Review Triggers
+
+Flag for maintainer review if change involves:
+
+- Public API shape changes.
+- Authentication/signing logic.
+- Retry/pipeline policy semantics.
+- Cross-package refactors in multiple storage libraries.
+- Service-version default changes.
+- Test proxy / recording sanitization policy adjustments.
+
+---
+
+## Quick Checklist for Agents
+
+- [ ] Scope confirmed to correct storage package.
+- [ ] Followed nearest existing code pattern.
+- [ ] Added/updated tests.
+- [ ] No secrets introduced.
+- [ ] No unintended public API break.
+- [ ] Changelog/docs updated (if applicable).
+- [ ] Build and targeted tests pass locally/CI.

sdk/storage/azure-storage-blobs/AGENTS.md

@@ -0,0 +1,103 @@
+# AGENTS.md
+
+Guidance for AI agents working in `sdk/storage/azure-storage-blobs`.
+
+## Scope
+
+This file applies to:
+
+- `sdk/storage/azure-storage-blobs/**`
+
+It extends `sdk/storage/AGENTS.md` with blob-specific guidance.
+
+---
+
+## Blob Domain Model (mental map)
+
+Primary client hierarchy typically includes:
+
+- **BlobServiceClient** (account-level blob service operations)
+- **BlobContainerClient** (container-level operations)
+- **Blob clients** (blob-level operations), including specializations such as:
+  - Block blob
+  - Append blob
+  - Page blob
+
+Keep API behavior and naming consistent with this hierarchy.
+
+---
+
+## Blob-Specific Concepts to Preserve
+
+- **Blob types:** block / append / page have distinct semantics.
+- **Upload semantics:** single-shot vs staged/block uploads.
+- **Download/range behavior:** partial reads and offset/length options.
+- **Leases:** acquire/renew/change/release/break behavior.
+- **Snapshots and versions:** immutable references and operation targeting.
+- **Soft delete / undelete** and retention interactions.
+- **Metadata vs tags:** separate concerns and APIs.
+- **Access tiers / rehydration** behavior and option constraints.
+- **Copy operations:** sync/async copy patterns and polling/status behavior.
+
+---
+
+## Common Pitfalls (avoid)
+
+- Mixing block/blob/page operation constraints.
+- Breaking conditional header behavior (If-Match, If-None-Match, etc.).
+- Inconsistent treatment of empty payloads and zero-length blobs.
+- Changing defaults that affect transfer performance or memory behavior.
+- Regressing large-transfer chunking/parallel upload logic without benchmarks/tests.
+
+---
+
+## Implementation Guidance
+
+- Reuse existing upload/download helper logic rather than introducing alternative pathways unless required.
+- Keep transfer option parsing and defaults centralized and consistent.
+- Maintain compatibility of public models/options and response types.
+- Prefer additive changes over replacing established abstractions.
+
+---
+
+## Testing Focus Areas
+
+When touching blob code, ensure tests cover impacted areas:
+
+1. Upload/download happy path.
+2. Conditional request behavior.
+3. Paging/listing continuation flows.
+4. Error-path mapping for key service responses.
+5. Blob-type-specific behavior (where relevant).
+6. Lease/version/snapshot semantics (if modified).
+
+If behavior changes at protocol level, ensure recording/playback implications are addressed.
+
+---
+
+## API & Compatibility Guardrails
+
+- Avoid renaming or removing public methods/types without approved breaking-change process.
+- Keep overload patterns and option structs aligned with existing blob client style.
+- Preserve expected exception/error surfaces unless explicitly justified.
+
+---
+
+## Performance & Reliability Expectations
+
+- Be cautious with memory allocations for large transfers.
+- Keep retry-friendly behavior for transient failures.
+- Avoid introducing extra network calls on hot paths.
+- Preserve streaming behavior where expected.
+
+---
+
+## Review Triggers
+
+Explicit human review recommended for:
+
+- Transfer engine/chunking changes
+- Lease logic changes
+- Copy/polling workflow changes
+- Version/snapshot targeting semantics
+- Public API additions/changes

sdk/storage/azure-storage-files-datalake/AGENTS.md

@@ -0,0 +1,103 @@
+# AGENTS.md
+
+Guidance for AI agents working in `sdk/storage/azure-storage-files-datalake`.
+
+## Scope
+
+This file applies to:
+
+- `sdk/storage/azure-storage-files-datalake/**`
+
+It extends `sdk/storage/AGENTS.md` with datalake-specific guidance.
+
+---
+
+## Naming and Package Note
+
+The Data Lake client code lives under `azure-storage-files-datalake` in this repository. When making changes, ensure paths, includes, namespaces, and conventions target this package.
+
+---
+
+## Data Lake Domain Model (mental map)
+
+Typical hierarchy includes:
+
+- **DataLakeServiceClient** (account/service scope)
+- **FileSystemClient** (filesystem/container scope)
+- **Path clients** (file or directory scope), often with dedicated file/directory operations
+
+Data Lake builds on Blob Storage primitives; maintain alignment where behavior intentionally overlaps.
+
+---
+
+## Data Lake-Specific Concepts to Preserve
+
+- **Hierarchical namespace semantics** (directories and path operations).
+- **Path operations:** create, rename, move, delete.
+- **File operations:** append + flush workflow (ordering and position semantics matter).
+- **Directory semantics:** recursive operations and path traversal/listing.
+- **Access control:** ACLs, permissions, owner/group where applicable.
+- **Lease/conditions** behavior when exposed through datalake APIs.
+- **SAS/authorization** parity with storage-common/blob foundations where applicable.
+
+---
+
+## Common Pitfalls (avoid)
+
+- Treating datalake path behavior as identical to flat blob behavior.
+- Breaking rename/move atomicity assumptions or destination-conditions handling.
+- Mis-handling append/flush offsets and finalization semantics.
+- Regressing recursive delete/list behavior with deep trees.
+- Inconsistent URL/path encoding treatment for special characters.
+
+---
+
+## Implementation Guidance
+
+- Follow existing path client patterns for request construction and response parsing.
+- Reuse shared storage/common mechanisms for auth/pipeline/retries.
+- Keep distinctions between directory and file operations clear and explicit.
+- Ensure datalake behavior remains coherent with underlying blob constraints.
+
+---
+
+## Testing Focus Areas
+
+When modifying datalake code, prioritize tests for:
+
+1. Path create/delete/list operations (including continuation/paging).
+2. Rename/move behavior and conflict/condition handling.
+3. Append/flush positional correctness.
+4. ACL/permission operations (where touched).
+5. Deep directory recursive scenarios (if applicable).
+6. Error mapping and exception behavior for common service failures.
+
+Include edge cases for path encoding and unusual path names when relevant.
+
+---
+
+## API & Compatibility Guardrails
+
+- Preserve public path/file/directory client API shape and naming conventions.
+- Avoid behavioral changes that silently diverge from documented datalake semantics.
+- Keep option structs backward compatible and additive when possible.
+
+---
+
+## Reliability Expectations
+
+- Preserve idempotency where expected.
+- Keep retry behavior safe for multi-step operations (append/flush, rename flows).
+- Avoid partial-state changes in client abstractions when operations fail mid-flow.
+
+---
+
+## Review Triggers
+
+Require/flag maintainer review for:
+
+- Rename/move semantic changes
+- Append/flush logic changes
+- ACL/permission handling changes
+- Public API changes across path clients
+- Any cross-library behavior divergence vs blobs/common