Last week I wrote about using Claude Code to generate Draw.io architecture diagrams directly from Terraform. The idea was simple: instead of maintaining diagrams by hand which nobody does consistently — let the AI generate them from the source of truth.

The response I got most often was: “That’s great, but you’re still comparing them manually, right? Isn’t that the hard part?”

They’re not wrong. So I kept going.

But before I get into the technical details, I want to be clear about what this is actually for — because it’s easy to frame this as a documentation automation story, and that undersells it.

The real problem: architects can’t review what they can’t see

When a Terraform PR lands for review, the people best placed to assess its architectural implications — the principal engineers, the solutions architects, the team leads — are looking at raw HCL. They’re expected to mentally reconstruct what the infrastructure looks like, what’s changing, and whether those changes introduce risk. For anything beyond a trivial PR, that’s an unreasonable ask.

So what actually happens? The code gets reviewed for syntax and convention. Someone checks the variable names and the resource tags. The architectural implications — the ones that matter — get a cursory glance at best. Problems that should be caught at PR time surface weeks later, in production.

This isn’t a people problem. It’s a tooling problem. Architects can’t review what they can’t see.

What this workflow does

This is a GitHub Actions workflow that automatically updates your AWS architecture diagram and posts a structured risk analysis to every Terraform PR — giving architects the visual context and the flagged risks they need to do a proper review.

Every time a PR touches your Terraform files, the reviewer gets:

• A visual diagram of the updated architecture — what the infrastructure looks like after this PR merges, committed directly to the branch as a Draw.io file and an inline PNG

• A risk analysis with HIGH / MEDIUM / LOW severity flags on the architectural implications of each change

• A resource table showing what changed, the service’s role, and the impact — split by change type (modified, force-replaced, permanently deleted)

The architect’s job isn’t replaced — it’s made possible. This is a task that needs both data processing and contextual understanding, and that’s precisely where AI and human capability complement each other. The workflow handles the data — diffing infrastructure, classifying changes, flagging risks. The architect brings what AI can’t: experience, intuition, and the judgement to understand nuance. One without the other is weaker. Together, they’re more capable than either alone.

What the PR comment looks like

Two real examples from the same system — a Document Management Service running on ECS Fargate with RDS and S3. One PR strengthens the security posture, one weakens it. The difference in what the architect sees is stark.

Example 1: WAF added — security posture strengthened

A PR adds a WAF Web ACL, attaches it to the ALB, and wires up access logging to CloudWatch. Four resources added, zero removed, no risks flagged.

🏗️ AWS Architecture Review

4 resource(s) changed — 4 added/modified, 0 removed

Resources added

📖 View companion guide

The architect can see at a glance that this is a clean security improvement. Every added resource has a clear role, nothing is being removed, and there are no risks to assess. The review is quick and confident.

The companion guide tells the full story — the updated network topology, the new request flow through WAF before the ALB, the CloudWatch log group for threat analysis, and the security implications of each addition. An architect joining the team after this PR can understand the full security model without having to read the Terraform.

If you want to see exactly what change produced this output, the Terraform is in the examples repo — the withwaf folder shows the full infrastructure definition including all four WAF resources. It’s a useful reference for understanding the relationship between the HCL and what the workflow surfaces to the architect.

Example 2: WAF removed — security posture weakened

Now the same WAF resources are deleted in a PR. This time the workflow fires HIGH and MEDIUM severity flags, and the architect has decisions to make before this merges.

🏗️ AWS Architecture Review

4 resource(s) changed — 1 added/modified, 3 removed

⚠️ Architecture Risks

• HIGH — WAF Web ACL deleted (dms-production-waf): All inbound HTTP traffic now reaches the ALB unfiltered. OWASP managed rules (SQLi, XSS, known bad IPs) that were blocking threats at the edge are gone. Any application-layer exploit protection previously handled by WAF must now be handled entirely at the application level.

• MEDIUM — WAF access logs deleted (aws-waf-logs-dms-production): Loss of allow/block decision logs and source IP visibility that was used for threat analysis. Incident response for web-layer attacks will have a significant blind spot.

Resources modified (in-place)

Resources permanently deleted

📖 View companion guide

This is exactly the scenario where the workflow earns its place. Without it, a reviewer looking at the raw Terraform diff sees four resource deletions and has to mentally reconstruct what each one does and what disappears with it. With the workflow, the architect sees two flagged risks in plain English — the ALB is now unfiltered, and threat visibility is gone — before a single approval is clicked.

The companion guide shows the updated architecture without the WAF layer, making the exposure immediately visible. The architect can now make an informed decision: is this intentional? Is there a compensating control? Should this block the merge?

That’s the conversation this workflow is designed to start.

The Terraform for this example is also in the examples repo — the withoutwaf folder shows the same infrastructure with the WAF resources removed. Compare it with the withwaf folder to see precisely what four resource deletions look like in raw HCL versus what they look like to an architect reviewing a PR comment.

How it works

When a PR is opened against any file under infra/terraform/aws/:

1. A Python script diffs the branch against main and produces a diff.json of added, modified, and deleted AWS resources

2. Claude Code runs the aws-architecture-sync skill, which orchestrates the aws-architecture-diagram skill to update the diagram and regenerate the companion guide

3. The updated files are committed back to the PR branch

4. A PR comment is posted with the risk analysis, resource tables, diagram PNG, and links

Two Claude Code skills power this under the hood. The aws-architecture-sync skill analyses the Terraform diff, determines which nodes and edges need adding or removing, and produces the risk summary that lands in the PR comment. The aws-architecture-diagram skill owns all the Draw.io XML generation — looking up accurate AWS service icons, applying layout rules, writing the .drawio file, and generating the companion guide. Both skills live as Markdown files in .claude/skills/ inside the cloudaifusion/sdlc-automation repo, which is public and forkable. The Python diff script and a full example workflow are also in the repo.

Setting it up

Prerequisites

• A GitHub repository with Terraform files

• One of the following for Claude AI access:

  • Anthropic API key — individuals or small teams getting started; pay-as-you-go with no subscription required

  • Claude.ai OAuth token — teams already on a Claude.ai Pro or Team subscription who want to get more value from it beyond the chat interface

  • AWS Bedrock — organisations that need data to stay within a specific AWS region (data residency requirements), want Claude usage billed through their existing AWS account rather than a separate Anthropic account, or need to integrate with IAM, VPCs, or AWS-native security controls. More setup overhead, but the right choice for enterprise environments where the primary focus is enterprise-grade security, compliance, and integration within an existing AWS ecosystem.

Step 1 — Create a docs folder

Create an empty docs/ folder in your repo so the workflow has somewhere to write the diagram:

mkdir docs
touch docs/.gitkeep
git add docs/.gitkeep
git commit -m "Add docs folder for architecture diagrams"

Step 2 — Fork the repo and create the workflow file

First, fork cloudaifusion/sdlc-automation to your own GitHub org. This gives you full control — you own the skills, the workflow, and the scripts, and can customise them to match your own conventions without depending on this repo being maintained.

Then create .github/workflows/aws-architecture-sync.yml in your infrastructure repo, pointing the uses line at your fork:

name: AWS Architecture Sync

on:
  pull_request:
    paths:
      - 'infra/terraform/aws/**'   # adjust to match your Terraform path
  workflow_dispatch:

jobs:
  architecture-review:
    uses: your-org/sdlc-automation/.github/workflows/aws-architecture-sync.yml@main
    permissions:
      contents: write
      pull-requests: write
      id-token: write
    with:
      terraform_path: infra/terraform/aws   # adjust to your Terraform path
      docs_path: docs
      diagram_name: architecture
      pr_number: ${{ github.event.pull_request.number }}
    secrets:
      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
      CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

Replace your-org with your GitHub org or username. Adjust terraform_path to wherever your .tf files live. The workflow accepts these inputs if your repo structure differs from the defaults:

• terraform_path (default: infra/terraform/aws): Path to your .tf files

• docs_path (default: docs): Where to write the diagram and guide

• diagram_name (default: architecture): Base filename for the outputs

Step 3 — Add your secret

Go to your GitHub repo → Settings → Secrets and variables → Actions → New repository secret

Add one of:

• ANTHROPIC_API_KEY: Your key from console.anthropic.com

• CLAUDE_CODE_OAUTH_TOKEN: Your Claude.ai OAuth token

The workflow will use whichever is available. The OAuth token takes priority.

Step 4 — Trigger it

Make any change to a file under your terraform_path and open a PR. The workflow will:

• Diff the Terraform changes against main

• Generate or update docs/architecture.drawio, docs/architecture.md, and docs/architecture.png

• Commit those files back to your PR branch

• Post a comment on the PR with the diagram and a summary of what changed

The first time it runs with no existing diagram, it generates one from scratch from all your current Terraform files. On every subsequent PR it updates incrementally based on the diff.

Step 5 — View the diagram locally

Install the Draw.io Integration extension in VS Code, pull the branch, and open docs/architecture.drawio. It renders as a fully interactive diagram, useful for deeper review sessions where the architect wants to explore the full picture rather than just the diff.

A note on prompt injection

The workflow passes your Terraform files and existing diagram XML directly into the Claude prompt. Any text in those files is treated as data, not instructions — the prompt wraps each input in explicit BEGIN DATA / END DATA delimiters and opens with a system directive telling Claude to ignore any commands embedded in data sections. If you’re running this against a repo with external contributors, this is the relevant threat model to be aware of.

A note on CI errors you can safely ignore

You may see these messages in the workflow logs:

Failed to connect to the bus: Could not parse server address...
Exiting GPU process due to errors during initialization

These come from Draw.io (an Electron app) running headlessly in CI without a desktop session. They don’t affect the output — as long as you see PNG export succeeded at the end, everything worked.

Optional: AWS Bedrock instead of direct API

If you want the full step-by-step guide to configuring Bedrock access from GitHub Actions, I've covered that in detail in Calling AWS Bedrock from GitHub Actions Without Storing Credentials. The summary below covers the key variables you'll need once that's set up.

If you want to use AWS Bedrock to call Claude — for data residency or cost billing reasons — add these GitHub repository variables:

• AWS_ROLE_ARN: e.g. arn:aws:iam::123456789:role/github-actions-role

• AWS_REGION: e.g. eu-west-2

• BEDROCK_MODEL_ID: e.g. eu.anthropic.claude-sonnet-4-6

• USE_BEDROCK: true

Configuring GitHub OIDC trust for AWS Bedrock

GitHub Actions can assume an AWS IAM role without storing long-lived credentials, using OpenID Connect (OIDC). Here’s how to set it up.

1 — Add GitHub as an OIDC identity provider in AWS

• Open the AWS IAM console → Identity providers → Add provider

• Select OpenID Connect and set:

  • Provider URL: https://token.actions.githubusercontent.com

  • Audience: sts.amazonaws.com

• Click Add provider — AWS now handles the thumbprint automatically

2 — Create the IAM role

• Go to IAM → Roles → Create role

• Select Web identity as the trusted entity type

• Set the following fields:

  • Identity provider: token.actions.githubusercontent.com

  • Audience: sts.amazonaws.com

  • GitHub organization: Your GitHub org or username

  • GitHub repository: The repo where your Terraform lives and your workflow runs, or * for all repos in the org

  • GitHub branch: Leave as * to allow any branch, or specify a branch to restrict further

Important: the GitHub repository field should be the repo that contains your Terraform files and your workflow file — not the sdlc-automation repo you forked. The trust policy needs to match the repo that is actually making the AWS API calls. If you're using a reusable workflow defined in another repo, the trust policy still needs to reference your infrastructure repo, not the one where the reusable workflow lives.

AWS will generate the trust policy condition automatically from these fields.

• Click Next — AWS will take you to the Add permissions screen

• On the Add permissions screen, click Next again without selecting anything — you’ll add the Bedrock policy as an inline policy after the role is created

• On the Name, review, and create screen, verify the auto-generated trust policy contains sts:AssumeRoleWithWebIdentity and the correct repo condition

• Give the role a name (e.g. github-actions-bedrock) and click Create role

3 — Add the Bedrock permission policy

Once the role is created, open it and go to the Permissions tab → Add permissions → Create inline policy, switch to the JSON editor and paste the following:

json

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowBedrockInvoke",
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ],
      "Resource": [
        "arn:aws:bedrock:*::foundation-model/anthropic.claude-*",
        "arn:aws:bedrock:*:*:inference-profile/*"
      ]
    }
  ]
}

The inference-profile resource is needed if you use cross-region inference profiles (e.g. eu.anthropic.claude-sonnet-4-6). If you want to allow invocation of any Bedrock model rather than restricting to Claude, you can simplify the resource to “Resource”: “*”.

Click Next, give the policy a name (e.g. github-actions-bedrock-policy), and click Create policy.

4 — Verify the trust policy

On the role’s Trust relationships tab, confirm it contains sts:AssumeRoleWithWebIdentity with a condition scoped to your repo. If it doesn’t look right, edit it directly in the console before proceeding.

5 — Copy the role ARN and add it to GitHub

• On the role summary page, copy the ARN (e.g. arn:aws:iam::123456789012:role/github-actions-bedrock)

• Go to your GitHub repo → Settings → Secrets and variables → Actions → Variables tab → New repository variable

• Add the following repository variables:

  • AWS_ROLE_ARN: The ARN you just copied

  • AWS_REGION: e.g. eu-west-2

  • BEDROCK_MODEL_ID: e.g. eu.anthropic.claude-sonnet-4-6

  • USE_BEDROCK: true

These are repository variables (referenced in workflows as vars.AWS_ROLE_ARN), not environment variables. GitHub Actions environment variables are scoped to specific deployment environments like production or staging — repository variables are available to all workflows in the repo.

6 — Complete the Anthropic first-time use form

AWS has retired the Model Access page — serverless foundation models are now automatically available without manual enablement. However, Anthropic models still require a one-time use case form before first invocation:

• Open the Amazon Bedrock console → Model catalog

• Select any Anthropic Claude model

• Complete the first-time use form and submit — access is granted immediately

This only needs to be done once per AWS account. If you are using AWS Organizations, completing it at the management account level covers all child accounts.

Once this is done, the workflow will authenticate to AWS via OIDC on each run, assume the role, and call Bedrock — no stored credentials required.

Cost

Each PR run makes one Claude API call using claude-sonnet-4-6. The cost per run is low — a few cents at most for a typical Terraform diff — and a fraction of what an architectural issue caught in production rather than at review would cost. Your actual cost will vary depending on diagram size and the number of resources changed.

Customising for your own conventions

The skills are just Markdown files — fork cloudaifusion/sdlc-automation, edit the aws-architecture-sync/SKILL.md or aws-architecture-diagram/SKILL.md files in .claude/skills/ to match your conventions, then point your workflow at your fork:

yaml

uses: your-org/sdlc-automation/.github/workflows/aws-architecture-sync.yml@main

The broader point

Good architectural governance doesn’t fail because architects don’t care. It fails because the feedback loop is too slow and the context too hard to assemble. By the time an architectural concern surfaces through the usual channels, the code has shipped, the infrastructure is running, and the cost of change is an order of magnitude higher.

Putting a visual architecture review directly in the PR — at the moment the change is being made, with risks already flagged and explained — closes that loop. It gives architects the right information at the right time, and it makes proper architectural review a natural part of the PR process rather than an afterthought.

The full source is at github.com/cloudaifusion/sdlc-automation.

If you’re running Claude in GitHub Actions via the Anthropic API, the setup is straightforward — add an API key as a GitHub secret and you’re done. But in enterprise environments that’s often not an option. Your security policy requires AWS. Your compliance framework mandates data residency. Your billing needs to flow through a single AWS account. Or you simply want Claude to live inside the same security perimeter as the rest of your infrastructure.

That’s where AWS Bedrock comes in. And the right way to connect GitHub Actions to Bedrock isn’t to store AWS credentials as secrets — it’s to use OpenID Connect (OIDC) so your workflows can assume an IAM role directly, with no long-lived credentials anywhere.

I’ll use Claude as the example throughout, but the pattern works for any model you’re invoking through Bedrock.

Why OIDC and not stored credentials

The traditional approach — creating an IAM user, generating an access key, and storing it as a GitHub secret — works, but it has real problems:

• Long-lived credentials that need rotating

• Credentials that exist outside AWS, in GitHub’s secret store

• No straightforward way to scope them to a specific repo or workflow

• An audit trail that doesn’t cleanly tie API calls back to individual workflow runs

OIDC solves all of this. GitHub acts as an identity provider, and each workflow run gets a short-lived token that it exchanges for temporary AWS credentials. The credentials are scoped to the role, the role is scoped to the repo, and nothing sensitive is stored anywhere. When the workflow finishes, the credentials expire.

It’s the same pattern AWS recommends for any CI/CD system, and it’s what you should be using if you’re running anything production-grade through GitHub Actions.

What you’re building

By the end of this post you’ll have:

• GitHub Actions workflows that can call AWS Bedrock without any stored AWS credentials

• An IAM role scoped to your specific repo, assumable only by GitHub Actions

• A Bedrock permission policy that follows least privilege

• Claude (or any Bedrock model) callable from any workflow in your repo

Step 1 — Add GitHub as an OIDC identity provider in AWS

This tells AWS to trust tokens issued by GitHub Actions. You only need to do this once per AWS account.

• Open the AWS IAM console → Identity providers → Add provider

• Select OpenID Connect and set:

  • Provider URL: https://token.actions.githubusercontent.com

• • Audience: sts.amazonaws.com

• Click Add provider — AWS now handles the thumbprint automatically

Once this is done, any GitHub Actions workflow can potentially request AWS credentials — but only if an IAM role explicitly trusts it, which is what the next step controls.

Step 2 — Create the IAM role

This role is what your GitHub Actions workflow will assume. The trust policy restricts it to your specific repo.

• Go to IAM → Roles → Create role

• Select Web identity as the trusted entity type

• Set the following fields:

  • Identity provider: token.actions.githubusercontent.com

  • Audience: sts.amazonaws.com

  • GitHub organization: Your GitHub org or username (e.g. cloudaifusion)

  • GitHub repository: The repo where your Terraform lives and your workflow runs (e.g. my-infrastructure-repo), or * for all repos in the org

  • GitHub branch: Leave as * to allow any branch, or specify a branch to restrict further

Important: this should be the repo that contains your Terraform files and your workflow file — the repo that is actually making the AWS API calls. If you’re using a reusable workflow from another repo, the trust policy still needs to reference your repo, not the one where the reusable workflow is defined.

AWS will generate the trust policy condition automatically from these fields — you no longer need to add it manually.

• Click Next — AWS will take you to the Add permissions screen

• On the Add permissions screen, click Next again without selecting anything — you’ll add the Bedrock policy as an inline policy after the role is created

• AWS will show you a Name, review, and create screen. Before creating the role:

  • Enter a role name (e.g. github-actions-bedrock)

  • Review the auto-generated trust policy under Step 1: Select trusted entities — confirm it contains sts:AssumeRoleWithWebIdentity and the correct repo condition

  • Optionally add tags under Step 3: Add tags

• Click Create role

Step 3 — Add the Bedrock permission policy

Once the role is created, open it and add an inline policy:

• Go to the Permissions tab → Add permissions → Create inline policy

• Switch to the JSON editor and paste the following:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowBedrockInvoke",
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ],
      "Resource": [
        "arn:aws:bedrock:*::foundation-model/anthropic.claude-*",
        "arn:aws:bedrock:*:*:inference-profile/*"
      ]
    }
  ]
}

• Click Next, give the policy a name (e.g. github-actions-bedrock-policy), and click Create policy

A few things worth noting here:

• bedrock:InvokeModel covers standard synchronous calls; bedrock:InvokeModelWithResponseStream covers streaming responses — include both unless you’re certain you won’t need streaming

• The foundation-model ARN pattern scopes access to Anthropic Claude models only. Tighten to a specific model ARN if you want to restrict further (e.g. arn:aws:bedrock:eu-west-2::foundation-model/anthropic.claude-sonnet-4-6)

• The inference-profile resource is required if you’re using cross-region inference profiles (e.g. eu.anthropic.claude-sonnet-4-6) — these route requests across regions for resilience and Bedrock requires the profile ARN to be explicitly permitted

If you want to allow invocation of any Bedrock model rather than restricting to Claude, you can simplify the resource to "Resource": "*". This is less restrictive but easier to maintain if your model requirements change over time.

Step 4 — Verify the trust policy

On the role’s Trust relationships tab, confirm it looks like this:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::YOUR_ACCOUNT_ID:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
        },
        "StringLike": {
          "token.actions.githubusercontent.com:sub": "repo:YOUR_ORG/YOUR_REPO:*"
        }
      }
    }
  ]
}

If it doesn’t match this structure, edit it directly in the console before proceeding.

Step 5 — Complete the Anthropic first-time use form

AWS has retired the Model Access page — serverless foundation models are now automatically available in your account without any manual enablement step.

However, Anthropic models are an exception. Before you can invoke any Claude model via Bedrock, Anthropic requires a one-time use case form to be completed. This only needs to be done once per AWS account (or once at the organisation management account level, which then covers all child accounts).

To complete it:

• Open the Amazon Bedrock console

• Go to Model catalog and select any Anthropic Claude model

• You will be prompted to submit use case details — fill in the form and submit

• Access is granted immediately once the form is successfully submitted

If you are using AWS Organizations, completing the form at the management account level via the API covers all child accounts automatically — you won’t need to repeat it per account.

Step 6 — Add the role ARN to GitHub

• On the role summary page in IAM, copy the ARN (e.g. arn:aws:iam::123456789012:role/github-actions-bedrock)

• Go to your GitHub repo → Settings → Secrets and variables → Actions → Variables tab → New repository variable

• Add the following repository variables:

  • AWS_ROLE_ARN: The ARN you just copied

  • AWS_REGION: The region your Bedrock models are in, e.g. eu-west-2

  • BEDROCK_MODEL_ID: The model you want to invoke, e.g. eu.anthropic.claude-sonnet-4-6

These are repository variables (referenced in workflows as vars.AWS_ROLE_ARN), not environment variables. GitHub Actions environment variables are scoped to specific deployment environments like production or staging — repository variables are available to all workflows in the repo.

Step 7 — Configure your workflow

Create the file .github/workflows/my-workflow.yml in your repo. If the .github/workflows/ directory doesn’t exist yet, create it:

mkdir -p .github/workflows
touch .github/workflows/my-workflow.yml

Then add the following to the file:

name: My Workflow

on:
  pull_request:

jobs:
  my-job:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write   # required for OIDC

    steps:
      - uses: actions/checkout@v4

      - name: Configure AWS credentials via OIDC
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ vars.AWS_ROLE_ARN }}
          aws-region: ${{ vars.AWS_REGION }}

      - name: Call Bedrock
        env:
          BEDROCK_MODEL_ID: ${{ vars.BEDROCK_MODEL_ID }}
          AWS_REGION: ${{ vars.AWS_REGION }}
        run: |
          pip install boto3
          python scripts/call_bedrock.py

Commit and push the file to your repo:

git add .github/workflows/my-workflow.yml
git commit -m "Add Bedrock workflow"
git push

The workflow will trigger on every pull request. If you want to test it manually before opening a PR, add workflow_dispatch: to the on: block — this adds a Run workflow button in the GitHub Actions tab.

The id-token: write permission is what allows the workflow to request an OIDC token from GitHub. Without it, the configure-aws-credentials action will fail. The rest is handled automatically — the action exchanges the OIDC token for temporary AWS credentials and sets them as environment variables for subsequent steps.

Using a reusable workflow? If you’re calling a reusable workflow (e.g. one shared across repos via uses: your-org/your-repo/.github/workflows/my-workflow.yml@main), the aws-actions/configure-aws-credentials step is likely already handled inside the reusable workflow itself. In that case you don’t need to add it here — just pass the aws_role_arn, aws_region, and any other Bedrock inputs as with parameters to the reusable workflow and let it handle the rest. Check the reusable workflow’s documentation to confirm.

Creating the script

Create scripts/call_bedrock.py in your repo — this is the script the workflow calls:

import boto3
import json
import os

bedrock = boto3.client("bedrock-runtime", region_name=os.environ["AWS_REGION"])

response = bedrock.invoke_model(
    modelId=os.environ["BEDROCK_MODEL_ID"],
    body=json.dumps({
        "anthropic_version": "bedrock-2023-05-31",
        "max_tokens": 1000,
        "messages": [
            {"role": "user", "content": "who was the last person to walk on the moon"}
        ]
    })
)

result = json.loads(response["body"].read())
print(result["content"][0]["text"])

No API keys. No secrets. The boto3 client picks up the temporary credentials that configure-aws-credentials set as environment variables, and Bedrock handles the rest. Replace "who was the last person to walk on the moon" with whatever you want Claude to do.

Your repo structure should look like this:

your-repo/
├── scripts/
│   └── call_bedrock.py
└── .github/
    └── workflows/
        └── my-workflow.yml

Using Claude Code CLI instead of boto3? If you’re running agentic tasks with the claude CLI rather than making direct API calls, the approach is slightly different. After the configure-aws-credentials step, set CLAUDE_CODE_USE_BEDROCK=1 as an environment variable and pass --model with your Bedrock model ID:

export CLAUDE_CODE_USE_BEDROCK=1
claude -p "who was the last person to walk on the moon" --model eu.anthropic.claude-sonnet-4-6

The CLI picks up the AWS credentials from the environment automatically — no script needed.

Step 8 — Trigger it with a PR

Make a small change on a new branch and open a PR to trigger the workflow:

git checkout -b test/bedrock-oidc
echo "# test" >> README.md
git add README.md
git commit -m "Test Bedrock OIDC workflow"
git push -u origin test/bedrock-oidc

Then open a PR from test/bedrock-oidc into main on GitHub. The workflow will trigger automatically.

To watch it run:

• Go to your repo → Actions tab

• Select My Workflow from the left sidebar

• Click the running workflow to see the live logs

A successful run will show the Configure AWS credentials via OIDC step completing without errors, followed by the Call Bedrock step printing Claude’s response to the logs.

If something goes wrong, the logs will tell you which step failed — check the troubleshooting section below for the most common errors.

How this compares to storing credentials

The one-time setup cost of OIDC pays for itself immediately in reduced credential management overhead and a significantly better security posture.

Troubleshooting

Error assuming role: Not authorized to perform sts:AssumeRoleWithWebIdentity The trust policy condition doesn’t match the workflow’s subject claim. Check that the GitHub organization and repository in the trust policy exactly match your repo name, including case.

id-token: write permission missing The workflow job must include id-token: write in its permissions block. If you’ve set top-level permissions in the workflow, make sure id-token: write is included there too.

Could not load credentials from any providers The configure-aws-credentials step didn’t run, failed silently, or the credentials expired before the Bedrock call. Check that the step ran successfully and that your Bedrock call happens in the same job.

You don't have access to the model with the specified model ID The Anthropic first-time use form hasn’t been completed for this AWS account. Go back to Step 5 and complete the form via the Bedrock model catalog — access is granted immediately on submission.

not available on your bedrock (Claude Code CLI) The model ID specified via --model isn’t available in the region you’re using. Check that the cross-region inference profile ID matches your AWS_REGION prefix (e.g. eu.anthropic.claude-sonnet-4-6 for eu-west-2) and that the Anthropic FTU form has been completed.

The broader point

Storing credentials is the path of least resistance, but it’s also the path of most risk. OIDC gives you a cleaner security model, a better audit trail, and no credentials to rotate or accidentally expose — with a setup cost that’s a few hours at most.

If you’re running Claude or any other model through Bedrock in a production environment, this is the setup you should have. The pattern is the same regardless of which model you’re invoking or what your workflow is doing with it.

This is the first in a series exploring how AI is changing the Software Development Lifecycle — from requirements and design through to deployment and operations. My focus is practical and production-grounded: tools and patterns that actually work, not just ones that look good in a demo.

There’s a version of your infrastructure that lives in a diagram. Clean boxes, neat arrows, everything labelled the way you intended it. And then there’s the version that actually exists in your Terraform — the one that’s been through six sprints, two engineers, a production incident, and a cost-optimisation review.

These two versions start the same. They rarely stay that way.

The Problem: Architecture Drift Is Invisible Until It Isn’t

When I hand off an architecture diagram to a DevOps team, I’m communicating intent. This is what we’re building. Here’s how the components relate. Here’s the security boundary. The Terraform that comes back usually reflects that intent - at least initially.

But Terraform evolves. It has to. Requirements change, new services get added, existing resources get refactored or replaced. And crucially, these changes don’t automatically flow back into the architecture diagram. The diagram sits in a Confluence page or a Draw.io file somewhere, quietly becoming fiction.

This matters more than it might seem. Architecture diagrams aren’t just documentation artefacts - they’re the shared mental model that engineers, architects, and technical stakeholders use to reason about a system. When they diverge from reality, decisions get made on false assumptions. Security reviews miss components that have been added. Onboarding takes longer. Incident response gets harder.

The technical term for this is infrastructure drift, but the diagram problem is subtler than the classic “drift from desired state” that tools like terraform plan catch. No tool natively tells you: your diagram no longer reflects your code. You have to figure that out yourself — and typically you only discover it when it matters most.

I’ve been looking for a practical way to close this loop for a while. The approach I’ve landed on — using a Claude Code skill to reverse-engineer Draw.io diagrams directly from Terraform — is the most useful solution I’ve found.

The Tool: A Claude Code Skill for AWS Architecture Diagrams

The skill is open source, published here: 🔗 https://github.com/oharu121/oharu-commands-skills-gems/tree/main/skills/aws-architecture-diagram

The reference article that explains the thinking behind it is worth reading too: 🔗 https://dev.classmethod.jp/en/articles/claude-code-skill-aws-architecture-diagram/

What it does is straightforward but genuinely useful: it teaches Claude Code to produce two outputs - a Draw.io-compatible XML diagram using accurate AWS service icons, and a markdown file describing the architecture. The markdown alone is useful as a living summary of what your infrastructure actually contains.

Installing it on Windows takes about two minutes:

1. Clone the repository:

   git clone https://github.com/oharu121/oharu-commands-skills-gems.git

2. Copy the skills/aws-architecture-diagram folder into your %USERPROFILE%\.claude\skills folder

   xcopy /E /I oharu-commands-skills-gems\skills\aws-architecture-diagram "%USERPROFILE%\.claude\skills\aws-architecture-diagram"

3. Give Claude Code permission to read all of the files in its skills folder to prevent it from asking permission to read reference files every time you use the skill. This is done by editing Claudes settings.json file:

   notepad %USERPROFILE%\.claude\settings.json

   and adding the line:

   "Read(~/.claude/skills/**)"

   For example:

   {
   
     "permissions": {
       "allow": [
         "Read(~/.claude/skills/**)"
       ]
     }
   }

Using it is straightforward: Prompt claude to generate an AWS architecture diagram by pointing it at a folder of Terraform files:

create an aws architecture diagram from the files in the terraform folder

That’s it.

A Real Example: Two Audiences, One Codebase

I ran this against a set of Terraform files to test something specific: whether the skill could adapt its output for different audiences. I asked for two versions of the diagram using only a small prompt change.

Prompt 1 - non technical audience:

create an aws architecture diagram from the files in the terraform/aws folder for a non technical audience

Prompt 2 - technical audience:

create an aws architecture diagram from the files in the terraform/aws folder for a technical audience

The difference is striking. The non-technical version strips away ARNs, resource identifiers, and implementation detail - leaving a clean, readable view of the system’s shape. The technical version exposes the detail that an engineer needs: resource names, relationships, configuration specifics. Same infrastructure, two genuinely different perspectives, generated from the same prompt pattern with a single word changed.

This matters in practice. One of the friction points in architecture work is producing documentation at the right level for the right audience. Generating both from code - rather than maintaining them separately - removes a real overhead.

How I’m Incorporating This Into My Workflow

The most immediate use case for me is architecture verification. Before a significant release, or when onboarding to a codebase I haven’t touched in a while, I’ll run this against the current Terraform and compare the output against the original design. It’s not a binary pass/fail check — it’s a conversation starter. What changed? Was that intentional? Does the current state still reflect the system we meant to build?

I’m also planning to use it as part of design reviews. When a DevOps engineer proposes infrastructure changes, generating a diagram from their Terraform branch gives me something concrete to review - not just code, but a visual representation of the architectural impact of those changes. That’s a much richer review surface.

Longer term, I think there’s something interesting in running this on a cadence - generating a diagram from Terraform on every merge to main and storing it alongside the code. Not as a replacement for maintained architecture documentation, but as an automatically-updated snapshot that at least answers the question: what does this infrastructure look like right now?

Where It Falls Short

In the spirit of being practical rather than promotional: this tool isn’t magic, and it has real limits.

It works from what Terraform can see. If your architecture involves manual resources, console-configured components, or multi-repo infrastructure that isn’t referenced in the folder you point it at, those won’t appear. The diagram reflects the code, not necessarily the full system.

The quality of output also depends on how well-structured your Terraform is. Highly modular, well-named code produces clearer diagrams. Sprawling, inconsistently named legacy Terraform produces noisier output. Garbage in, garbage out - but that’s also a useful signal in itself.

And Draw.io is not everyone’s preferred diagramming tool. If your team lives in Lucidchart or Miro, you’ll need to export and convert. That’s a friction point worth noting.

The Bigger Picture

What I find genuinely exciting about this approach isn’t just the specific tool — it’s what it represents. The idea that infrastructure code can be a source of truth for architecture diagrams, rather than the other way around, is a meaningful shift. For too long, diagrams have been upstream artefacts that drift from reality. Turning Terraform into the source and generating the diagram from it inverts that relationship in a useful way.

Claude Code skills are still relatively new territory. But this use case - using an AI coding agent to bridge the gap between code and visual architecture understanding - is exactly the kind of workflow augmentation I’ll be returning to throughout this series.

If you work with AWS infrastructure and Terraform, it’s worth twenty minutes to try it. The install is trivial, the prompt is simple, and the output is immediately useful.

The Terraform files used in this example are available here: https://github.com/cloudaifusion/sdlc-automation

f you found this useful, subscribe to catch the next one.

I recently completed Claude Code: Software Engineering with Generative AI Agents on Coursera — a five-hour course that turned out to be one of the more practically useful things I’ve done this year. I went in as someone already working with AI workflows. I came out genuinely rethinking what a single developer or small team can realistically build.

The course doesn’t dwell on theory — it’s hands-on from the start: setting up projects, delegating to agents, iterating, debugging, and managing increasingly complex systems.

What struck me first: code quality

Not just “working” code, but well-structured, readable, and aligned with the standards I’d normally expect from experienced engineers. The technical depth is where the course earns its credibility.

Using claude.md to define project context and standards, driving consistent behaviour with Claude commands, integrating directly into a Git-based workflow. The section on parallel development with Git worktrees was particularly striking — multiple agents working simultaneously on different features or fixes, without stepping on each other.

From impressive demo to something I rely on

Since finishing the course, I’ve been using Claude Code to explore and evolve architectural patterns — clean architecture, modular monolith, vertical slice — and it’s been remarkably effective at maintaining boundaries, generating consistent modules, and staying coherent as complexity increases.

That’s the part that moved it from “impressive demo” to something I am now starting to rely on.

Claude isn’t better autocomplete. It behaves more like a collaborative engineer — reasoning about architecture, writing meaningful tests, refactoring codebases, contributing to design decisions. The experience is closer to orchestrating a group of capable junior-to-mid engineers than using an AI assistant.

Who this is for

For anyone familiar with AI tools but unsure how to bring them into real engineering practice: this course is a good place to start. Not because it promises some future where AI writes all your code, but because it shows — concretely, right now — how to work alongside it in ways that actually shift what’s possible.

The team-of-12 question isn’t rhetorical. I’m still working through what it means — for how teams are structured, how work gets scoped, and what “senior engineering judgement” looks like when the execution layer becomes this capable.

The next post in this series goes deeper into the architectural patterns I’ve been testing with Claude Code — what held up, what didn’t, and what surprised me.

After 21+ years building and architecting software systems, one pattern keeps showing up in security reviews: OAuth is implemented incorrectly more often than correctly — and almost always because the wrong flow was chosen at the start.

Not because developers don’t understand OAuth. Because there are too many flows, most documentation assumes context you don’t have, and the wrong choice isn’t obvious until something breaks in production.

Here’s the decision guide I use. Two questions. That’s it.

Question 1: Is a user signing in?

→ No → Client Credentials flow. Your app authenticates as itself. No redirect, no user consent, no browser. Use this for service-to-service and machine-to-machine calls.

→ Yes → Go to Question 2.

Question 2: What type of application is calling the API?

→ Web app with a backend → Authorization Code flow. The client secret never leaves your server. The code exchange happens server-to-server.

→ SPA with no secret-holding backend → Authorization Code + PKCE. No long-lived secret required. This replaces the deprecated Implicit flow — don’t use Implicit.

→ Native mobile or desktop app → Authorization Code + PKCE. No embedded secrets in the app package. Redirects are handled by the OS.

→ CLI or headless device → Device Code flow. Users visit a short URL and enter a code while the device polls for authentication. Purpose-built for no-browser environments.

One thing most OAuth guides quietly skip:

Your API doesn’t choose the flow. It validates Bearer tokens (RFC 6750). The flow is chosen by whoever calls the API. This matters architecturally — it means your API is flow-agnostic by design.

The fundamental split behind all of this is simple: confidential clients (web apps with a backend) can store a secret securely. Public clients (SPAs, native apps, CLIs) cannot. PKCE exists precisely because of that gap — it prevents authorization code interception attacks without requiring a stored secret.

OAuth isn’t conceptually hard. It gets complicated when the wrong flow is chosen upfront. Run the two questions before writing a line of auth code and you’ll eliminate most of the bugs before they’re possible.