If you have a CLAUDE.md in place and Claude no longer needs you to explain your environment at the start of every session. AGENTS.md does something related but distinct: it defines the rules that apply to any AI agent working in your repository, not just Claude, and it does so at a level of detail that meaningfully shortens what you have to type at runtime.
This post focuses on two things: how to structure AGENTS.md to capture the IT-specific context that matters most, and what you can stop saying in your prompts once that context is baked in.
How AGENTS.md and CLAUDE.md differ in practice
The two files are often treated as interchangeable because the format is the same. They are not the same thing. CLAUDE.md is Claude’s personal briefing. You can use Claude Code-specific syntax in it, reference memory files, and set tool permissions. AGENTS.md is the shared contract between the repository and any AI that reads it.
From a prompting perspective, this distinction matters for one reason: AGENTS.md is what you maintain for the team. It lives in source control, it applies to everyone, and it should be written as if you are briefing an AI-capable colleague who knows nothing about your environment. CLAUDE.md is where your own habits and preferences live.
For an IT team running Azure and Microsoft 365, a well-structured AGENTS.md tells any AI agent which subscriptions exist and which ones are production, defines the naming conventions it must follow without being asked, sets the default safety posture, and documents the tools in use so the agent does not guess or suggest alternatives.
The anatomy of a useful AGENTS.md for IT work
A common mistake is writing an AGENTS.md that mirrors what you already have in CLAUDE.md. The more useful approach is to think about what information the agent needs before it can take any action in your environment without risking something. That tends to fall into four areas.
Environment topology is the single most valuable thing to include. Which subscriptions exist, what they contain, which ones are sensitive. Without it, an agent asked to “create a test VM” has to guess which subscription to target.
Naming conventions come next. Azure resource names that violate your convention create confusion in monitoring, break tag-based policies, and are a headache to audit later. An agent that knows the convention does not need reminding every time.
Safety defaults define the actions the agent must not take without explicit confirmation, and what it should do instead: never delete, always WhatIf, always plan before apply. These are the rules you would otherwise type at the start of every session involving infrastructure.
Toolchain context tells the agent which CLI, which module version, and which pattern for authentication. Agents that do not have this information default to whatever they were trained on, which may not match what is installed on your machines or what your pipeline expects.
A practical AGENTS.md for Azure and Microsoft 365
Here is a starting point for an IT team managing Azure infrastructure, Intune, and Entra ID. Adapt the topology section to your actual subscriptions and tenant.
# IT infrastructure: Azure and Microsoft 365
## Environment
- PowerShell 7.4, Azure CLI 2.x, Az module 12.x, Microsoft Graph PowerShell SDK 2.x
- Subscriptions:
- prod: sub-abc-prod (West Europe, owner: [email protected])
- dev: sub-abc-dev (West Europe)
- staging: sub-abc-stg (West Europe)
- Naming: {env}-{region}-{type}-{name} -- example: prod-we-vm-appserver01
- Resource groups follow the same prefix: prod-we-rg-networking, dev-we-rg-compute
## Microsoft 365 and Intune
- Tenant: contoso.onmicrosoft.com
- Intune managed: all Windows 11 24H2+ devices, iOS 26+, Android 13+
- Do not modify compliance policies or conditional access rules without an explicit request
- Use Graph PowerShell for read operations; propose portal-based changes for writes
unless scripting is the explicit goal
## Safety defaults
- Never target the prod subscription unless explicitly specified in the request
- For any Azure write operation, generate and present the -WhatIf or plan output first
- For Intune and Entra ID changes, describe the affected scope before proceeding
- Never delete resources -- use Disable-AzResource, move to a decommission group,
or flag for manual review
- Never hard-code credentials, UPNs, subscription IDs, or tenant IDs
## Code standards
- All PowerShell scripts use [CmdletBinding()] and param() blocks
- -ErrorAction Stop on all Azure CLI and Az module calls in non-interactive scripts
- Write-Verbose for progress, Write-Warning for recoverable issues, throw for fatal errors
- Run PSScriptAnalyzer before treating any .ps1 as complete
- Terraform: always run terraform plan and attach the output before apply;
tag every resource with env, owner, project, cost-center
## What not to do
- Do not suggest Bash alternatives for tasks that can be done in PowerShell
- Do not use deprecated Az module aliases (Get-AzureRm*, Set-AzureRm*)
- Do not add try/catch blocks that swallow errors silently
- Do not create new service principals or app registrations without flagging it explicitlyThis file goes in the project root and commits to source control. Every team member gets it, and every AI tool that supports AGENTS.md reads it.
What you stop having to say in every prompt
The practical payoff from a structured AGENTS.md shows up in how short your prompts can be. Without it, a typical session might start with something like this:
“We use PowerShell 7.4 and the Az module. Never touch the prod subscription, that’s sub-abc-prod. For anything destructive use -WhatIf first. Naming convention is env-region-type-name. Now write a script that checks which VMs in dev have no backup policy assigned.”
With an AGENTS.md in place, that same request becomes:
“Write a script that checks which VMs in dev have no backup policy assigned.”
The agent already knows the subscription, the tooling, the naming convention, and the safety posture. You are only providing what changes per task: the specific thing you want done.
This compounds over a week of work. You stop re-establishing context, the agent stops hedging on things it is not sure about, and the back-and-forth shortens. For IT technicians running multiple sessions a day across different projects, that reduction is noticeable.
The boundary to maintain is this: AGENTS.md is for things that are always true. Anything that varies by task, by ticket, or by day belongs in the prompt. The moment you start adding task-specific instructions to AGENTS.md, it gets noisy and the static context starts working against you.
Structuring AGENTS.md for Intune and Entra work specifically
Microsoft 365 work has a few characteristics that benefit from explicit coverage in AGENTS.md, more so than pure infrastructure work.
The blast radius of Entra ID changes is often opaque to an agent that does not know your tenant. A conditional access policy change, a group membership modification, or a license assignment can affect thousands of users or just five. Telling the agent upfront that it must state the affected scope before any write operation turns this into a consistent behavior rather than something you have to request case by case.
For Intune, the equivalent is device scope and compliance policy ownership. If the agent knows which compliance profiles apply to which device types and which groups own them, it stops treating every policy as an independent object and starts reasoning about dependencies correctly.
Add a section like this to your AGENTS.md for Microsoft 365 coverage:
## Entra ID and conditional access
- Before modifying any group, conditional access policy, or role assignment,
state which users or devices are in scope
- Dynamic group membership queries must be validated against current membership
before submission
- Do not add guests to groups with access to production resources without flagging it
## Intune
- Device compliance profiles: Windows (windows-compliance-prod),
iOS (ios-compliance-prod), Android (android-compliance-prod)
- Do not modify compliance policies -- propose the change and wait for confirmation
- When targeting devices by group, always confirm the group membership count firstKeeping AGENTS.md useful over time
An AGENTS.md that nobody updates becomes a liability. Stale topology information is worse than no information because the agent uses it confidently. Treat the file like a runbook: review it when your environment changes, when you onboard a new tool, or when you notice the agent consistently making the same avoidable mistake.
Version it deliberately. When you change a safety default or rename a subscription, commit the AGENTS.md update in the same pull request as the infrastructure change. That way the history is auditable and a new team member reading the git log gets both the change and the updated context together.
The agents that make IT work faster are the ones that know your environment well enough to ask fewer clarifying questions and make fewer assumptions. AGENTS.md is how you teach them that, once, and have it hold across every tool on the team.
