Add storage-specific AGENTS.md for sdk/storage subtree by Copilot · Pull Request #49714 · Azure/azure-sdk-for-java

Copilot · 2026-07-02T23:07:51Z

Adds sdk/storage/AGENTS.md to give AI agents (Copilot Coding Agent, etc.) storage-specific context that is too narrow for the root AGENTS.md.

What's in the file

Module table — maps each azure-storage-* module to its Azure service
4 agent rules:
- Do not edit generated code in implementation/ or models/ paths — fix upstream in TypeSpec/OpenAPI
- Preserve API consistency (parameter names, types, option bag names, return types) across Blob, Queue, File, and Data Lake clients
- Prefer existing patterns (RequestRetryOptions, ParallelTransferOptions, PagedIterable/PagedFlux, Reactor async) over new abstractions
- No magic strings — use HttpHeaderName, service-specific *Constants classes, and *ServiceVersion enums
Storage service semantics — per-service behavioral notes (AppendBlob overwrite safety, BlockBlob commit flow, Queue visibility timeout, File share hierarchy)
Build/test commands — including Azurite startup and live-test invocation

Co-authored-by: amnguye <48961492+amnguye@users.noreply.github.com>

amnguye · 2026-07-06T20:39:30Z

@browndav-msft @ibrandes @kyleknap Feel free to add any comments or new suggested sections for the AGENTS.md file

Copilot

Pull request overview

Adds a storage-specific sdk/storage/AGENTS.md to provide AI agents with Azure Storage SDK context and contribution constraints that are narrower than the repo-root AGENTS.md.

Changes:

Introduces a module-to-service mapping table for sdk/storage.
Documents storage-specific agent rules (generated code boundaries, API consistency expectations, preferred patterns, and avoiding magic strings).
Adds storage build/test commands and references storage-local contribution guidance.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

…remove duplication Co-authored-by: amnguye <48961492+amnguye@users.noreply.github.com>

ibrandes

thanks for setting all this up! i had a couple of questions / suggestions, feel free to ping me if anything was unclear :)

ibrandes · 2026-07-13T17:11:58Z

+| Module | Service |
+|---|---|
+| `azure-storage-blob` | Azure Blob Storage |
+| `azure-storage-blob-batch` | Blob batch operations |
+| `azure-storage-blob-changefeed` | Blob Change Feed |
+| `azure-storage-blob-cryptography` | Client-side encryption for Blobs |
+| `azure-storage-blob-nio` | `java.nio.file` provider backed by Blob Storage |
+| `azure-storage-file-share` | Azure Files (SMB/REST) |
+| `azure-storage-file-datalake` | Azure Data Lake Storage Gen2 |
+| `azure-storage-queue` | Azure Queue Storage |
+| `azure-storage-common` | Shared primitives used by all storage libraries |
+| `azure-storage-internal-avro` | Internal Avro support (not public API) |


should we expand this list to include packages that aren't shipped, like the stress / perf packages? it may be possible for an agent to perceive this list as "incomplete" after listing directories in the overall storage package and may wander into the unlisted ones without instruction. we could also consider adding the stress / perf packages to the end of the list and adding a note that they're not shipped / out of scope.

ibrandes · 2026-07-13T17:15:05Z

@@ -0,0 +1,58 @@
+# AGENTS.md — Azure Storage Blob SDK for Java


i noticed that queues didn't get an agents.md file - how do we determine what packages to add them to? would it be overkill to add them to every package?

I left out queues because compared to the other services, Queues is pretty simple and straightforward, and doesn't receive a lot of updates and can rely on the sdk/storage/AGENTS.md file.

It wouldn't be overkill to add one for every package. I can add one for queues (and blob batch).

Though for things like NIO and cryptography, where I don't have a lot of experience on, is something I would trust yall to add in the next iteration. But seeing as those also don't get touched very often, it might be fine not to have one for those.

ibrandes · 2026-07-13T17:19:10Z

+- **Retry**: `RequestRetryOptions` / `RequestRetryPolicy` from `azure-storage-common`
+- **Parallel transfer**: `ParallelTransferOptions`
+- **Paging**: `PagedIterable` / `PagedFlux` from `azure-core`
+- **Async clients**: mirror sync APIs with Reactor (`Mono`, `Flux`)
+- **Client builders**: follow existing `*ClientBuilder` patterns and storage utility conventions


nit: we might want to consider listing any references with their fully qualified names - e.g com.azure.storage.common.policy.RequestRetryOptions to prevent agents from greping a package blindly

ibrandes · 2026-07-13T17:20:41Z

+
+Before assuming `src/main/java/**/models/` is generated, check the file header; many public model types are hand-written.
+
+If a bug exists in generated code, the fix must be made upstream (in the TypeSpec/OpenAPI spec or the AutoRest/TypeSpec-Java emitter configuration), not in the generated file itself.


we should add a reference to the swagger/README.md here, and we'll make a note to edit this when the typespec implementation is released

ibrandes · 2026-07-13T17:23:02Z

+# Run live tests (requires Azure resources)
+AZURE_TEST_MODE=LIVE mvn -f sdk/storage/azure-storage-blob/pom.xml test
+
+# Start Azurite (local storage emulator) for tests


would be useful to point to tests-install-azurite.yml here too

I added a line to reference tests-install-azurite.yml on line 120. Is that the right place to put that, or did you mean we should call it before "npx azurite"

ibrandes · 2026-07-13T17:27:29Z

+For shared storage rules (generated code, magic strings, cross-service consistency, common patterns), see [../AGENTS.md](../AGENTS.md).
+For repo-wide guidance, see the [root AGENTS.md](../../../AGENTS.md).
+
+## Blob SDK Overview


could be useful to add a "related modules" section here with batch, changefeed, crypto, and nio, so agents know to check for downstream impact after modifying an api

ibrandes · 2026-07-13T17:30:16Z

+
+## Data Lake Service Semantics
+
+- Requires hierarchical namespace (HNS)-enabled accounts; this library does not support HNS-disabled accounts.


Suggested change

- Requires hierarchical namespace (HNS)-enabled accounts; this library does not support HNS-disabled accounts.

- Requires hierarchical namespace (HNS)-enabled accounts; this library is designed for and is only fully supported for HNS-enabled accounts.

nit: soften this to avoid an agent removing a code path thinking something is dead code, since we do have some stuff regarding a few operations that work against non-hns accounts

ibrandes · 2026-07-13T17:32:57Z

+- `DataLakeFileClient` / `DataLakeFileAsyncClient`
+- `DataLakeDirectoryClient` / `DataLakeDirectoryAsyncClient`
+
+This module targets hierarchical namespace (HNS)-enabled accounts and uses the `dfs.core.windows.net` endpoint shape.


nit: since the sdk handles blob / dfs endpoint conversions internally, we should add a small sentence here about this dual endpoint behavior to prevent agents from simplifying things

ibrandes · 2026-07-13T17:34:21Z

+- `ShareClient` / `ShareAsyncClient`
+- `ShareDirectoryClient` / `ShareDirectoryAsyncClient`
+- `ShareFileClient` / `ShareFileAsyncClient`
+


we should add a short bullet about nfs / smb protocol distinctions so agents don't blend the two together and help them recognize that APIs may behave differently based on this.

ibrandes · 2026-07-13T17:37:05Z

+  - Hierarchical directory semantics differ from blobs.
+
+## Build and Test
+


we should add a note here that any changes to the sync/async client surfaces require separate sync and async tests

Clarified endpoint usage for the Azure Data Lake SDK, specifying that both DFS and Blob endpoints are utilized for compatibility and performance.

Clarified support for hierarchical namespace (HNS) accounts and updated build command

Updated documentation to clarify protocol-specific behavior and modified build command.

Added related modules section to AGENTS.md to outline dependencies on azure-storage-blob.

Added guidelines for stress and performance testing of storage modules, including module-specific semantics and code generation documentation.

Clarify usage of ParallelTransferOptions for blob operations.

Co-authored-by: amnguye <48961492+amnguye@users.noreply.github.com>

Updated the Maven command to skip tests during build.

Initial plan

5ccfba1

Copilot AI assigned Copilot and amnguye Jul 2, 2026

Copilot started work on behalf of amnguye July 2, 2026 23:08 View session

Add AGENTS.md for Azure Storage SDK subtree

8e375bf

Co-authored-by: amnguye <48961492+amnguye@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Add AGENTS.md for Azure Storage SDK guidance~~ Add storage-specific AGENTS.md for sdk/storage subtree Jul 2, 2026

Copilot AI requested a review from amnguye July 2, 2026 23:10

Copilot finished work on behalf of amnguye July 2, 2026 23:10

Merge branch 'main' into copilot/create-agents-md-file

82c95e1

amnguye marked this pull request as ready for review July 6, 2026 20:38

Copilot AI review requested due to automatic review settings July 6, 2026 20:38

amnguye requested review from a team, alzimmermsft, browndav-msft, gunjansingh-msft, ibrandes, kyleknap and seanmcc-msft as code owners July 6, 2026 20:38

Copilot started reviewing on behalf of amnguye July 6, 2026 20:38 View session

Copilot AI reviewed Jul 6, 2026

View reviewed changes

Comment thread sdk/storage/AGENTS.md Outdated

Specifying specific folders where generated code lives

507836a

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot started work on behalf of amnguye July 8, 2026 19:34 View session

Copilot finished work on behalf of amnguye July 8, 2026 19:40

Copilot started work on behalf of amnguye July 8, 2026 19:43 View session

Copilot finished work on behalf of amnguye July 8, 2026 19:48

Copilot started work on behalf of amnguye July 8, 2026 19:50 View session

Add service-module AGENTS.md files and refactor storage AGENTS.md to …

df50f77

…remove duplication Co-authored-by: amnguye <48961492+amnguye@users.noreply.github.com>

Copilot finished work on behalf of amnguye July 8, 2026 19:57

ibrandes reviewed Jul 13, 2026

View reviewed changes

amnguye added 6 commits July 13, 2026 13:57

Update AGENTS.md to clarify endpoint usage

5bf5bbd

Clarified endpoint usage for the Azure Data Lake SDK, specifying that both DFS and Blob endpoints are utilized for compatibility and performance.

Update AGENTS.md for HNS support and build command

666771b

Clarified support for hierarchical namespace (HNS) accounts and updated build command

Clarify protocol behavior and update build command

eb0eda5

Updated documentation to clarify protocol-specific behavior and modified build command.

Update AGENTS.md with related modules information

7640ec1

Added related modules section to AGENTS.md to outline dependencies on azure-storage-blob.

Update AGENTS.md with testing and codegen guidelines

b7d4a56

Added guidelines for stress and performance testing of storage modules, including module-specific semantics and code generation documentation.

Update AGENTS.md with blob ParallelTransferOptions guidance

80350c6

Clarify usage of ParallelTransferOptions for blob operations.

Copilot started work on behalf of amnguye July 13, 2026 22:38 View session

Add AGENTS.md for azure-storage-queue and azure-storage-blob-batch

fba032b

Co-authored-by: amnguye <48961492+amnguye@users.noreply.github.com>

Copilot finished work on behalf of amnguye July 13, 2026 22:43

Modify build command to skip tests

fc430b6

Updated the Maven command to skip tests during build.

		@@ -0,0 +1,58 @@
		# AGENTS.md — Azure Storage Blob SDK for Java


		Before assuming `src/main/java/**/models/` is generated, check the file header; many public model types are hand-written.

		If a bug exists in generated code, the fix must be made upstream (in the TypeSpec/OpenAPI spec or the AutoRest/TypeSpec-Java emitter configuration), not in the generated file itself.


		## Data Lake Service Semantics

		- Requires hierarchical namespace (HNS)-enabled accounts; this library does not support HNS-disabled accounts.

		- Hierarchical directory semantics differ from blobs.

		## Build and Test

Uh oh!

Conversation

Copilot AI commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What's in the file

Uh oh!

amnguye commented Jul 6, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

ibrandes left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Copilot AI commented Jul 2, 2026 •

edited

Loading