[Storage] Add sdk/storage/AGENTS.md and sdk/storage/azure_storage_blob/AGENTS.md

sdk/storage/AGENTS.md

@@ -0,0 +1,61 @@
+# AGENTS.md – Storage crates guidance (minimal)
+
+Storage-specific guidance for `sdk/storage/*`.
+
+Root `AGENTS.md` is authoritative for repo-wide rules (generated code, compatibility, security, lint/test/CI, and general coding standards). Do not repeat those rules here.
+
+## Scope
+
+- Applies to all crates under `sdk/storage/*`.
+- Put crate-specific details in each crate’s local `AGENTS.md`.
+
+## Storage consistency requirements
+
+- Keep API shape consistent across storage crates:
+  - Similar operations should use similar option/builder patterns.
+  - Use consistent naming for equivalent concepts.
+  - Keep pagination behavior/ergonomics consistent.
+
+- Reuse shared request-construction helpers where possible; avoid copy/paste request logic.
+
+- Preserve storage auth semantics across crates (AAD, SAS, connection string, shared key where supported), including correct header/query threading and signing behavior.
+
+## Tests (storage-focused)
+
+- Add unit tests for request construction and option threading.
+- Add/maintain recorded or live tests for service behavior when expected by crate patterns.
+- Guard pagination/continuation behavior with tests.
+
+## Common storage pitfalls
+
+- Option naming drift across crates.
+- Behavior drift for equivalent operations in different crates.
+- Missing tests for newly added headers/query params.
+- Pagination regressions (continuation tokens / next-page behavior).
+
+## Minimal playbooks
+
+### Add optional header/query option
+1. Add to options/builder with default `None`.
+2. Thread into request construction once (single canonical path).
+3. Add request-construction tests.
+4. Confirm no behavior change when unset.
+
+### Add pagination option
+1. Extend options/docs.
+2. Apply in query construction.
+3. Verify continuation behavior unchanged.
+4. Add first-page + continuation tests.
+
+### Change response/deserialization
+1. Prefer additive/backward-compatible changes.
+2. Add regression tests for compatibility edge cases.
+
+### Add operation
+1. Follow neighboring storage operation structure and naming.
+2. Keep request/options/response style aligned with adjacent operations.
+3. Add unit + service-level tests per crate conventions.
+
+## When unsure
+
+Prefer existing patterns in adjacent storage crates and document any service-specific deviations.

sdk/storage/azure_storage_blob/AGENTS.md

@@ -0,0 +1,51 @@
+# AGENTS.md – Blob Storage crate guidance
+
+This file provides blob-specific guidance for work under `sdk/storage/azure_storage_blob/*`.
+
+Use this together with:
+- repository root `AGENTS.md`
+- `sdk/storage/AGENTS.md`
+
+If guidance conflicts, follow the more specific instructions in this directory.
+
+## Scope
+
+- Applies only to the `azure_storage_blob` crate.
+- Do not repeat storage-wide guidance here; keep shared conventions in `sdk/storage/AGENTS.md`.
+
+## Blob-specific focus areas
+
+- Keep behavior aligned with Blob Storage concepts: containers, blobs, snapshots, versions, leases, tags, ranges, block operations, and listing semantics.
+- Prefer consistency with neighboring blob/container operations over introducing one-off patterns.
+
+## Protocol-sensitive areas
+
+Be especially careful with:
+
+- conditional request semantics (lease conditions)
+- snapshot and version handling
+- range requests and content headers
+- metadata and tags
+- continuation tokens for listing operations
+- container-scope vs blob-scope behavior
+
+## Blob-specific expectations
+
+- Start from the closest existing blob or container operation and mirror its API, request construction, and tests.
+- Reuse shared helpers and existing request-building patterns before introducing new abstractions.
+- Keep public model changes additive unless a breaking change is explicitly intended.
+
+## Blob-specific pitfalls
+
+- Mixing up container-level and blob-level semantics
+- Missing propagation of optional headers or query parameters
+- Incorrect continuation token handling in listing flows
+- Inconsistent behavior across similar blob operations
+- Insufficient coverage for lease, conditional, range, snapshot, version, metadata, or tag behavior
+
+## Suggested workflow for changes
+
+1. Find the most similar existing blob/container operation.
+2. Reuse its options, request construction, and response patterns where possible.
+3. Add focused regression tests for the blob-specific protocol behavior being changed.
+4. If guidance is broadly applicable to all storage crates, move it to `sdk/storage/AGENTS.md` instead of duplicating it here.