This guide covers setting up Claude Code CLI and VS Code extension with Microsoft Foundry, configuring CLAUDE.md for project context, integrating Spec Kit for structured development, and running Claude Code in GitHub Actions.

Prerequisites

• Azure subscription with Foundry access
• Node.js 18+ (for Claude Code CLI)
• Optional: Azure CLI installed (az login completed)

Step 1: Deploy Claude Models in Foundry

In Microsoft Foundry:

1. Go to Discover → Models and search “Claude”
2. Select your model (Opus 4.5, Sonnet 4.5, or Haiku 4.5)
3. Click Deploy → choose Default settings
4. Click on the Details tab and note your Target URI and Key

Step 2: Install Claude Code CLI

npm install -g @anthropic-ai/claude-code

Verify installation:

claude --version

For more advanced installation options, visit Claude Code Docs.

Step 3: Configure for Foundry

Set these environment variables:

Bash / WSL:

# Required
export CLAUDE_CODE_USE_FOUNDRY=1

# Azure resource name (replace {resource} with your resource name)
export ANTHROPIC_FOUNDRY_RESOURCE={resource}
# Or provide the full base URL:
# export ANTHROPIC_FOUNDRY_BASE_URL=https://{resource}.services.ai.azure.com

# Optional: specify model deployment names, matching the deployment names in Foundry
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-5"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4-5"
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-5"

PowerShell:

# Required
$env:CLAUDE_CODE_USE_FOUNDRY = "1"

# Azure resource name (replace {resource} with your resource name)
$env:ANTHROPIC_FOUNDRY_RESOURCE = "{resource}"
# Or provide the full base URL:
# $env:ANTHROPIC_FOUNDRY_BASE_URL = "https://{resource}.services.ai.azure.com"

# Optional: specify model deployment names, matching the deployment names in Foundry
$env:ANTHROPIC_DEFAULT_SONNET_MODEL = "claude-sonnet-4-5"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "claude-haiku-4-5"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL = "claude-opus-4-5"

Authentication

Option A: Entra ID (recommended)

az login

Claude Code uses your Azure CLI credentials automatically.

Option B: API Key

Bash / WSL:

export ANTHROPIC_FOUNDRY_API_KEY="your-foundry-api-key"

PowerShell:

$env:ANTHROPIC_FOUNDRY_API_KEY = "your-foundry-api-key"

VS Code Extension

Install the Claude Code extension, then add to your VS Code settings:

{
  "Claude Code: Environment Variables": {
    "CLAUDE_CODE_USE_FOUNDRY": "1",
    "ANTHROPIC_FOUNDRY_RESOURCE": "https://your-resource.services.ai.azure.com",
    "ANTHROPIC_FOUNDRY_API_KEY": "<optional-for-non-entra-auth>"
  }
}

Step 4: Validate Configuration

Verify that Claude Code is correctly configured to use Microsoft Foundry. Open a terminal, launch Claude Code, and run the /status command:

claude
> /status

Confirm that:

• API provider shows “Microsoft Foundry”
• Microsoft Foundry resource points to your Foundry project
• Model matches your deployed model (e.g., claude-sonnet-4-5)

Step 5: CLAUDE.md Project Memory

Claude Code reads CLAUDE.md files for project context. Files are loaded in order (later files override earlier):

1. ~/.claude/CLAUDE.md – global defaults
2. ./CLAUDE.md – repo root
3. ./current-dir/CLAUDE.md – current directory

Example CLAUDE.md for a Microsoft Agent Framework project in Python:

# Project: Customer Service Agent

## Overview
Multi-agent system using Microsoft Agent Framework with Foundry Agent Service.

## Tech Stack
- Python 3.11+
- agent-framework (Microsoft Agent Framework Python SDK)
- Microsoft Foundry for hosted agents
- MCP tools for enterprise data access

## Architecture
- `src/agents/` - Agent definitions (triage, specialist, escalation)
- `src/tools/` - MCP tool implementations
- `src/workflows/` - Multi-agent orchestration
- `tests/` - pytest with async fixtures

## Commands
```bash
# Run locally
python -m src.main

# Test
pytest tests/ -v

# Deploy to Foundry Agent Service
az ai agent deploy --config deploy.yaml
```

## Code Patterns
Use `AzureAIAgentClient` with `AzureCliCredential`:
```python
async with AzureAIAgentClient(async_credential=AzureCliCredential()) as client:
    agent = client.create_agent(instructions="...", tools=[...])
```

## Current Sprint
- Implementing RAG grounding with Foundry IQ
- Adding Fabric connector for sales data

Step 6: Initialize and Explore

# Start Claude Code in your project
cd your-project
claude

# Or run a one-off command
claude "explain the agent orchestration in src/workflows/"

Claude Code will read your CLAUDE.md and understand your project context.

Step 7: Spec Kit Integration

Spec Kit provides structured commands for turning requirements into implementation. Install globally or for one-time use.

Workflow

Example: Building an Agent Framework Tool

# 1. Set project principles
claude /speckit.constitution
# Creates .speckit/constitution.md with coding standards, patterns

# 2. Define the feature
claude /speckit.specify
> "Add a SharePoint MCP tool that retrieves documents for RAG grounding"
# Creates .speckit/spec.md with requirements

# 3. Plan implementation  
claude /speckit.plan
# Creates .speckit/plan.md with architecture, dependencies

# 4. Generate tasks
claude /speckit.tasks
# Creates .speckit/tasks.md with ordered task list

# 5. Implement
claude /speckit.implement
# Executes tasks, creates files, runs tests

Step 8: GitHub Actions

Unit Test Generation for Agent Framework

name: Generate Agent Tests
on:
  pull_request:
    paths:
      - 'src/agents/**'
      - 'src/tools/**'

jobs:
  generate-tests:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      
      - name: Run Claude Code
        uses: anthropic-ai/claude-code-action@v1
        with:
          prompt: |
            Review the changed agent files and generate pytest tests.
            Use async fixtures for AzureAIAgentClient mocking.
            Follow patterns in tests/conftest.py.
          allowed_tools: "edit,write,bash"
        env:
          CLAUDE_CODE_USE_FOUNDRY: "1"
          ANTHROPIC_FOUNDRY_RESOURCE: ${{ secrets.AZURE_FOUNDRY_RESOURCE }}
          ANTHROPIC_FOUNDRY_API_KEY: ${{ secrets.AZURE_FOUNDRY_API_KEY }}

PR Review with @claude

name: Claude PR Assistant
on:
  issue_comment:
    types: [created]

jobs:
  respond:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      
      - name: Claude Review
        uses: anthropic-ai/claude-code-action@v1
        with:
          prompt: ${{ github.event.comment.body }}
          context: "PR #${{ github.event.issue.number }}"
        env:
          CLAUDE_CODE_USE_FOUNDRY: "1"
          ANTHROPIC_FOUNDRY_RESOURCE: ${{ secrets.AZURE_FOUNDRY_RESOURCE }}
          ANTHROPIC_FOUNDRY_API_KEY: ${{ secrets.AZURE_FOUNDRY_API_KEY }}

Step 9: Agent HQ

GitHub Agent HQ provides unified management for agents across your organization. Once your Agent Framework agents are deployed to Foundry Agent Service, you can manage them alongside other AI agents in Agent HQ:

• Unified dashboard for all agents (Foundry, Copilot, custom)
• Policy management across agent fleet
• Observability with traces and metrics
• One-click deployment from GitHub repos to Foundry

Access Agent HQ from your GitHub organization settings or the Foundry portal.

Step 10: Monitor Usage in Foundry Control Center

In Foundry portal → Operate:

• Token consumption by model
• Request latency
• Error rates and rate limit hits

Set token limits in Claude Code or from Foundry Control Center:

Bash / WSL:

export ANTHROPIC_MAX_TOKENS=100000  # per request

PowerShell:

$env:ANTHROPIC_MAX_TOKENS = "100000"  # per request

Troubleshooting

Resources

• Claude Code Documentation
• Microsoft Foundry Docs
• Microsoft Agent Framework
• Spec Kit on GitHub