[Storage] Add sdk/storage/AGENTS.md and sdk/storage/azure_storage_blob/AGENTS.md#4708
Open
amnguye wants to merge 5 commits into
Open
[Storage] Add sdk/storage/AGENTS.md and sdk/storage/azure_storage_blob/AGENTS.md#4708amnguye wants to merge 5 commits into
amnguye wants to merge 5 commits into
Conversation
amnguye
requested review from
LarryOsterman,
RickWinter,
heaths,
jalauzon-msft,
jaschrep-msft,
vincenttran-msft and
xirzec
as code owners
July 7, 2026 20:25
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds two documentation-only AGENTS.md files to give AI agents storage-specific guidance: a storage-family-wide file at sdk/storage/AGENTS.md and a Blob Storage crate-specific file at sdk/storage/azure_storage_blob/AGENTS.md. They cover API/design conventions, request construction, auth, testing expectations, common pitfalls, and task playbooks, complementing the repository-root AGENTS.md. No source code, build, or test behavior is affected.
Changes:
- New
sdk/storage/AGENTS.mdwith storage-wide conventions, a "storage family map", error handling, testing strategy, and agent task playbooks. - New
sdk/storage/azure_storage_blob/AGENTS.mdwith blob-specific API/design, request/protocol, testing, and pitfall guidance. - One factual inaccuracy: the storage family map lists a non-existent
azure_storagecrate and omitsazure_storage_common,azure_storage_queue, andazure_storage_sas.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| sdk/storage/AGENTS.md | New storage-wide agent guidance; family map references a non-existent azure_storage crate (should be azure_storage_common). |
| sdk/storage/azure_storage_blob/AGENTS.md | New blob-crate agent guidance; content is accurate and consistent with the crate (which has a src/generated/ tree). |
heaths
reviewed
Jul 8, 2026
heaths
left a comment
heaths
left a comment
Member
There was a problem hiding this comment.
I'll let @vincenttran-msft or @jalauzon-msft sign off or suggest changes, but I highly suggest having Copilot itself - with context including these files:
- Reduce duplication by making sure it understands that the blob one extends the storage one which extends the repo one.
- Be concise to reduce token cost but keep it reviewable by humans (a common instruction I give that seems to work well).
- Ask how to tighten up vague instructions - a couple examples of which I flagged. Depending on the model and other context, you're going to get wildly different - and sometimes problematic - output.
| @@ -0,0 +1,114 @@ | |||
| # AGENTS.md – Blob Storage crate guidance | |||
|
|
|||
| This file provides AI-agent guidance for work under `sdk/storage/azure_storage_blob/*`. | |||
Member
There was a problem hiding this comment.
Should this really be root-relative? Have you tested if it's impactful?
|
|
||
| ## API design conventions | ||
|
|
||
| - Keep public APIs ergonomic and predictable for common blob workflows. |
Member
There was a problem hiding this comment.
Sounds vague. See overall comment for suggestion.
| ## Request construction and protocol details | ||
|
|
||
| - Ensure optional blob request parameters are threaded consistently into headers and query parameters. | ||
| - Be careful with conditional request semantics (`If-Match`, `If-None-Match`, modified-since, lease conditions, etc.). |
Comment on lines
+53
to
+59
| From repo root (or scoped to affected crates as appropriate): | ||
|
|
||
| - `cargo fmt` | ||
| - `cargo clippy -p <crate> --all-targets --all-features` | ||
| - `cargo test -p <crate>` | ||
|
|
||
| When touching multiple crates, run checks for each affected crate. |
Member
There was a problem hiding this comment.
This - and probably other things - are duplicated. Don't waste tokens.
Refactor blob-specific guidance in AGENTS.md to clarify scope, expectations, and testing requirements.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Condensed guidance for storage crates, focusing on consistency and minimalism. Removed redundant sections and clarified instructions for crate-specific details.
Comment on lines
+5
to
+6
| Use this together with: | ||
| - repository root `AGENTS.md` |
Comment on lines
+38
to
+39
| ### Add optional header/query option | ||
| 1. Add to options/builder with default `None`. |
Comment on lines
+44
to
+45
| ### Add pagination option | ||
| 1. Extend options/docs. |
Comment on lines
+50
to
+51
| ### Change response/deserialization | ||
| 1. Prefer additive/backward-compatible changes. |
Comment on lines
+54
to
+55
| ### Add operation | ||
| 1. Follow neighboring storage operation structure and naming. |
Comment on lines
+5
to
+7
| Use this together with: | ||
| - repository root `AGENTS.md` | ||
| - `sdk/storage/AGENTS.md` |
Comment on lines
+38
to
+39
| ### Add optional header/query option | ||
| 1. Add to options/builder with default `None`. |
Comment on lines
+44
to
+45
| ### Add pagination option | ||
| 1. Extend options/docs. |
Comment on lines
+50
to
+51
| ### Change response/deserialization | ||
| 1. Prefer additive/backward-compatible changes. |
Comment on lines
+54
to
+55
| ### Add operation | ||
| 1. Follow neighboring storage operation structure and naming. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR introduces a shared sdk/storage/AGENTS.md for storage-wide conventions and a more specific sdk/storage/azure_storage_blob/AGENTS.md for blob crate guidance, including API consistency, request construction, testing expectations, and common pitfalls.