Forem: Aj

AWS EBS explained: volume types, snapshots, and when NOT to use it

Aj — Fri, 10 Apr 2026 13:29:43 +0000

Most AWS tutorials treat EBS like it's just a cloud hard drive you attach to EC2. Plug it in, store your files, done.

That mental model is why developers end up with the wrong volume type for their workload, surprise bills from forgotten snapshots, and architecture decisions that are hard to reverse six months later.

This is the guide that actually explains how EBS works — the volume types, when to use each, when to use something else entirely, and what the common expensive mistakes look like.

What AWS EBS actually is

EBS (Elastic Block Store) is persistent block storage for EC2 instances. The two words that matter: persistent and block.

Persistent means your data survives instance stop and termination. This is different from instance store (ephemeral storage that disappears when the instance stops). If you stop an EC2 instance and start it again tomorrow, EBS data is still there. Instance store data is gone.

Block storage means the OS sees it as a raw disk — a device like /dev/xvda or /dev/nvme0n1. You format it with a filesystem (ext4, xfs), mount it, and use it like any disk. This is different from S3 (object storage, accessed via API) or EFS (file storage, accessed via NFS protocol).

The key operational fact: Each EBS volume lives in one Availability Zone and can only be attached to instances in the same AZ. If your instance is in us-east-1a, your EBS volume must also be in us-east-1a.

EBS volume types: which one do you actually need?

AWS offers six EBS volume types. Most workloads need one of two. Here is the complete breakdown:

gp3 — General Purpose SSD (the default, and usually the right choice)

IOPS: 3,000 baseline, up to 16,000 provisioned independently
Throughput: 125 MB/s baseline, up to 1,000 MB/s independently
Cost: ~$0.08/GB-month
Use for: Boot volumes, development environments, small to medium databases, web servers, almost everything

The important upgrade from gp2: on gp3, IOPS and throughput are independent of storage size. On gp2, you got 3 IOPS per GB (so a 100GB volume had 300 IOPS). On gp3, you always get 3,000 IOPS regardless of size, and you can add more without buying more storage.

If you have gp2 volumes today, migrate them to gp3. Same performance, 20% cheaper.

gp2 — General Purpose SSD (legacy, stop using this)

IOPS: 3 IOPS/GB, minimum 100, maximum 16,000
Cost: ~$0.10/GB-month
Use for: Nothing new. Migrate existing gp2 to gp3.

io2 Block Express — Provisioned IOPS SSD (when you need extreme performance)

IOPS: Up to 256,000
Throughput: Up to 4,000 MB/s
Cost: ~$0.125/GB-month + $0.065/provisioned IOPS-month
Use for: Large critical databases (Oracle, SQL Server, SAP HANA), workloads requiring sub-millisecond latency with consistent performance

io2 Block Express is expensive. A 1TB io2 volume with 32,000 IOPS costs roughly $180/month vs $80/month for the same size gp3. The performance difference is real — if your database latency is the bottleneck, io2 is worth it. If it's not your bottleneck, it's waste.

io1 — Provisioned IOPS SSD (legacy io2, skip this)

Use io2 instead. Better durability (99.999% vs 99.8%), same price or cheaper per IOPS.

st1 — Throughput Optimized HDD (big sequential reads)

Throughput: Up to 500 MB/s
IOPS: Low (not the right metric for HDDs)
Cost: ~$0.045/GB-month
Use for: Big data, data warehouses, log processing — workloads that read/write large files sequentially
Cannot be used as boot volume

st1 is significantly cheaper than SSDs. If your workload reads Kafka log files, Hadoop data, or large sequential datasets where throughput matters but IOPS don't, st1 saves significant money.

sc1 — Cold HDD (infrequently accessed archives)

Throughput: Up to 250 MB/s
Cost: ~$0.015/GB-month (cheapest EBS option)
Use for: Infrequently accessed data that still needs block storage
Cannot be used as boot volume

sc1 is basically archival storage. If you're storing data you access rarely and can tolerate slow access, sc1 is the cheapest block storage available on AWS.

The decision framework

Is this a boot volume?
  → Yes: gp3 (required — st1/sc1 can't boot)

Does your workload need >16,000 IOPS or consistent sub-ms latency?
  → Yes: io2 Block Express
  → No: Continue

Is your workload sequential large reads/writes (logs, Hadoop, analytics)?
  → Yes: st1 (throughput optimized)

Is the data infrequently accessed?
  → Yes: sc1 (cheapest)

Everything else: gp3

Nine out of ten workloads should be on gp3. The other one is a large database that needs io2.

EBS vs EFS vs S3: choosing the right storage

This is where most architecture decisions go wrong. Block, file, and object storage serve fundamentally different purposes.

	EBS	EFS	S3
Storage type	Block	File (NFS)	Object
Access pattern	Single EC2 instance	Multiple EC2 instances	Any client via API
Protocol	OS disk (mounted)	NFS	HTTP REST API
Persistence	Until deleted	Until deleted	Until deleted
Latency	Sub-millisecond	Low milliseconds	Milliseconds to seconds
Availability Zone	Single AZ	Multi-AZ	Global
Price (storage)	From $0.015/GB	From $0.30/GB	From $0.023/GB
Best for	Databases, boot volumes	Shared file systems, CMS	Media, backups, static assets

Use EBS when: You need a disk that one EC2 instance treats as its own — databases, application servers, boot volumes, anything requiring filesystem-level access.

Use EFS when: Multiple EC2 instances need to read/write the same files simultaneously — shared CMS uploads, distributed application configs, dev environments shared across instances.

Use S3 when: You're storing objects via API — static website assets, images, videos, backups, data lake files, anything accessed via URL or SDK rather than a mounted filesystem.

The most common wrong decision: using EBS for something that should be S3 (backups, logs, static files). S3 is cheaper, more durable (99.999999999%), and globally accessible. EBS is more expensive, tied to one AZ, and appropriate only when your application needs a real disk.

Snapshots: what they are and how to not forget them

An EBS snapshot is a point-in-time backup of a volume stored in S3. Snapshots are incremental — the first one copies everything, subsequent ones only copy what changed.

Create a snapshot:

aws ec2 create-snapshot \
  --volume-id vol-0123456789abcdef0 \
  --description "Production DB backup $(date +%Y-%m-%d)"

Restore a volume from snapshot:

aws ec2 create-volume \
  --snapshot-id snap-0123456789abcdef0 \
  --availability-zone us-east-1a \
  --volume-type gp3

The expensive mistake: Creating snapshots and never deleting old ones. Snapshots cost $0.05/GB-month for the data stored. A 500GB production database with daily snapshots and no retention policy generates 500GB × 30 days × $0.05 = $750/month in snapshot storage — more than the EC2 instance itself.

Set a lifecycle policy immediately:

# Create a Data Lifecycle Manager policy
aws dlm create-lifecycle-policy \
  --description "Daily snapshots, keep 7 days" \
  --state ENABLED \
  --execution-role-arn arn:aws:iam::123456789012:role/AWSDataLifecycleManagerDefaultRole \
  --policy-details '{
    "PolicyType": "EBS_SNAPSHOT_MANAGEMENT",
    "ResourceTypes": ["VOLUME"],
    "TargetTags": [{"Key": "Backup", "Value": "daily"}],
    "Schedules": [{
      "Name": "Daily",
      "CreateRule": {"Interval": 24, "IntervalUnit": "HOURS", "Times": ["03:00"]},
      "RetainRule": {"Count": 7},
      "CopyTags": true
    }]
  }'

Tag your volumes with Backup: daily, and this policy automatically creates and expires snapshots. No manual management, no forgotten snapshots accumulating cost.

EBS encryption with KMS

Encrypt EBS volumes using AWS KMS. Two ways:

1. Enable default encryption for all new volumes (recommended — set this once):

aws ec2 enable-ebs-encryption-by-default --region us-east-1

After running this, every new EBS volume in us-east-1 is automatically encrypted using your default KMS key. No per-volume configuration needed.

2. Encrypt a specific volume:

aws ec2 create-volume \
  --availability-zone us-east-1a \
  --size 100 \
  --volume-type gp3 \
  --encrypted \
  --kms-key-id arn:aws:kms:us-east-1:123456789012:key/your-key-id

Encryption adds zero latency overhead. There is no reason not to encrypt. Enable default encryption by default in every region you use.

EBS cost optimization: where teams overpay

1. Unattached volumes

When you terminate an EC2 instance, the root EBS volume is deleted (by default). But additional data volumes are not. They keep charging until explicitly deleted.

# Find all unattached volumes
aws ec2 describe-volumes \
  --filters Name=status,Values=available \
  --query 'Volumes[*].[VolumeId,Size,VolumeType,CreateTime]' \
  --output table

Run this monthly. Delete volumes you don't need. An unused 100GB gp3 volume is $8/month, quietly.

2. gp2 volumes that haven't been migrated to gp3

# Find all gp2 volumes
aws ec2 describe-volumes \
  --filters Name=volume-type,Values=gp2 \
  --query 'Volumes[*].[VolumeId,Size]' \
  --output table

Migrate each to gp3 for an instant 20% cost reduction with no performance loss.

3. Over-provisioned io2 volumes

io2 charges per provisioned IOPS regardless of usage. If you provisioned 16,000 IOPS but your CloudWatch VolumeReadOps and VolumeWriteOps show average usage of 2,000 IOPS, you're paying for 14,000 idle IOPS.

Check your EBS volume metrics in CloudWatch. Right-size io2 to match actual usage.

4. Snapshots with no retention policy

Use Data Lifecycle Manager (shown above). One-time setup, saves money indefinitely.

EC2 instance store vs EBS: the critical difference

Instance store is temporary storage physically attached to the EC2 host. It is not EBS. Key differences:

	EBS	Instance Store
Persistence	Survives stop/start/reboot	Gone on stop, termination, failure
Speed	Very fast (NVMe gp3/io2)	Fastest (direct physical attach)
Cost	Charged separately	Included in instance price
Size	Any size up to 64TB	Fixed to instance type

Instance store is appropriate for: cache data you can regenerate, Hadoop temporary files, database buffer pools that can be rebuilt. Never use instance store for data you cannot regenerate from another source.

If your EC2 instance is stopped for any reason — scheduled maintenance, capacity issue, failure — instance store data is gone with no recovery path.

Frequently asked questions

Can I attach one EBS volume to multiple EC2 instances?

io1 and io2 volumes support Multi-Attach, allowing up to 16 instances in the same AZ to attach the same volume simultaneously. This requires careful application-level coordination to prevent data corruption — your application must handle concurrent writes. gp2 and gp3 do not support Multi-Attach.

What happens to my EBS volume if the EC2 instance fails?

The EBS volume is unaffected. You can detach it and attach it to a new instance. This is one of EBS's core advantages over instance store.

Can I move an EBS volume to a different Availability Zone?

Not directly. Create a snapshot, then create a new volume from that snapshot in the target AZ. The snapshot → new volume path is the standard way to move EBS storage across AZs or regions.

How much does EBS cost?

gp3: $0.08/GB-month. io2: $0.125/GB-month + $0.065/provisioned IOPS-month. st1: $0.045/GB-month. sc1: $0.015/GB-month. Snapshots: $0.05/GB-month for changed data stored.

Is EBS encrypted at rest by default?

Not by default, but you can enable account-level default encryption with one command (aws ec2 enable-ebs-encryption-by-default). After that, every new volume is encrypted automatically.

Practice this in a real AWS environment

Understanding EBS volume types is one thing. Knowing which type your workload actually needs — and what happens when you get it wrong — requires working with real volumes, real IOPS metrics, and real cost dashboards.

The Core AWS Foundations track on Cloud Edventures includes hands-on labs covering EBS volume creation, snapshot lifecycle management, KMS encryption, and cost optimization — in isolated real AWS sandboxes with automated validation. No AWS account needed.

👉 cloudedventures.com/labs/track/aws-cloud-foundations

What EBS scenario are you trying to solve? Drop a comment.

I built an MCP server on AWS Bedrock in 30 minutes. Here's the exact code.

Aj — Thu, 09 Apr 2026 11:13:10 +0000

MCP (Model Context Protocol) is the most important AI infrastructure pattern of 2026. Anthropic built it, the Linux Foundation now owns it, and AWS just made it a first-class citizen in Bedrock AgentCore.

97 million SDK downloads. 13,000+ servers built by the community. And as of this month, AWS is deploying them as managed services inside your existing cloud infrastructure.

This is the tutorial I wish existed when I started. Not theory. Actual working code that deploys a real MCP server connected to AWS services in under 30 minutes.

What MCP Actually Is (In One Paragraph)

MCP is the protocol that lets AI agents use external tools reliably. Without it, your agent either hardcodes tool integrations (brittle, unmaintainable) or hallucinates function calls that don't exist.

With MCP, you define tools once as a server. Any agent — Claude, Cursor, your own custom Bedrock agent — can discover and use those tools via a standardized interface. Think USB-C for AI tools. Build once, plug in anywhere.

Your Agent (Claude / Bedrock)
        ↓
   MCP Client (asks: what tools are available?)
        ↓
   MCP Server (returns: tool schemas + executes calls)
        ↓
   Your actual APIs, databases, AWS services

What We're Building

A working MCP server that exposes two AWS tools:

query_dynamodb — lets Claude query a DynamoDB table using natural language
get_s3_summary — lets Claude list and summarize files in an S3 bucket

Then we'll connect it to a Bedrock agent and watch Claude use both tools autonomously.

Prerequisites: Python 3.11+, AWS credentials configured, boto3 installed.

Step 1 — Install the MCP SDK

pip install mcp boto3 fastmcp

FastMCP is the Python framework that makes building MCP servers significantly less painful than raw MCP. It handles the protocol layer so you write tools, not JSON-RPC boilerplate.

Step 2 — Build the MCP Server

Create aws_mcp_server.py:

import boto3
import json
from fastmcp import FastMCP

# Initialize FastMCP server
mcp = FastMCP("AWS Tools Server")

# AWS clients
dynamodb = boto3.resource("dynamodb", region_name="us-east-1")
s3_client = boto3.client("s3", region_name="us-east-1")


@mcp.tool()
def query_dynamodb(table_name: str, key_name: str, key_value: str) -> str:
    """
    Query a DynamoDB table by primary key.
    Use this when the user wants to look up specific records from a database.

    Args:
        table_name: The DynamoDB table to query
        key_name: The primary key attribute name
        key_value: The value to look up
    """
    try:
        table = dynamodb.Table(table_name)
        response = table.get_item(
            Key={key_name: key_value}
        )

        item = response.get("Item")
        if not item:
            return json.dumps({
                "found": False,
                "message": f"No record found for {key_name}={key_value} in {table_name}"
            })

        return json.dumps({
            "found": True,
            "table": table_name,
            "record": item
        }, default=str)

    except Exception as e:
        return json.dumps({"error": str(e), "table": table_name})


@mcp.tool()
def get_s3_summary(bucket_name: str, prefix: str = "") -> str:
    """
    List and summarize files in an S3 bucket.
    Use this when the user asks about files, documents, or data stored in S3.

    Args:
        bucket_name: The S3 bucket to inspect
        prefix: Optional folder prefix to filter results (e.g., 'reports/' or 'data/2026/')
    """
    try:
        paginator = s3_client.get_paginator("list_objects_v2")
        pages = paginator.paginate(
            Bucket=bucket_name,
            Prefix=prefix,
            PaginationConfig={"MaxItems": 50}
        )

        files = []
        total_size = 0

        for page in pages:
            for obj in page.get("Contents", []):
                files.append({
                    "key": obj["Key"],
                    "size_kb": round(obj["Size"] / 1024, 2),
                    "last_modified": obj["LastModified"].isoformat()
                })
                total_size += obj["Size"]

        return json.dumps({
            "bucket": bucket_name,
            "prefix": prefix or "(root)",
            "file_count": len(files),
            "total_size_kb": round(total_size / 1024, 2),
            "files": files[:20],  # Return first 20 for context window efficiency
            "note": f"Showing {min(20, len(files))} of {len(files)} files"
        }, default=str)

    except Exception as e:
        return json.dumps({"error": str(e), "bucket": bucket_name})


if __name__ == "__main__":
    # Run as stdio MCP server (for local testing with Claude Desktop / Claude Code)
    mcp.run()

The @mcp.tool() decorator does the heavy lifting — it generates the JSON schema from your Python type hints and docstring. Claude uses the docstring to decide when to call each tool. Write it from Claude's perspective: "Use this when the user wants to..."

Step 3 — Test Locally With Claude Code

Before deploying to Bedrock, test the MCP server locally. Add it to your Claude Code MCP config:

# Add to Claude Code's MCP servers
claude mcp add aws-tools -- python /path/to/aws_mcp_server.py

Restart Claude Code, then ask:

How many files are in my logs-bucket-prod S3 bucket?

You should see Claude invoke get_s3_summary automatically. If it works locally, it'll work on Bedrock.

Step 4 — Deploy to Bedrock AgentCore Runtime

AWS Bedrock AgentCore Runtime lets you deploy MCP servers as managed services — serverless, auto-scaling, with session isolation handled for you. This is the new way to run MCP in production.

4a — Create a Dockerfile

FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY aws_mcp_server.py .

# AgentCore expects MCP servers to run on port 8080
EXPOSE 8080

# Run as HTTP MCP server for AgentCore
CMD ["python", "aws_mcp_server.py", "--transport", "http", "--port", "8080"]

requirements.txt:

fastmcp==0.9.0
boto3==1.35.0

4b — Push to ECR

# Create ECR repo
aws ecr create-repository --repository-name aws-tools-mcp-server

# Get ECR login
aws ecr get-login-password --region us-east-1 | \
  docker login --username AWS \
  --password-stdin 123456789.dkr.ecr.us-east-1.amazonaws.com

# Build and push
docker build -t aws-tools-mcp-server .
docker tag aws-tools-mcp-server:latest \
  123456789.dkr.ecr.us-east-1.amazonaws.com/aws-tools-mcp-server:latest
docker push 123456789.dkr.ecr.us-east-1.amazonaws.com/aws-tools-mcp-server:latest

4c — Deploy to AgentCore Runtime

import boto3

agentcore = boto3.client("bedrock-agentcore", region_name="us-east-1")

response = agentcore.create_agent_runtime(
    agentRuntimeName="aws-tools-mcp",
    agentRuntimeArtifact={
        "containerConfiguration": {
            "containerUri": "123456789.dkr.ecr.us-east-1.amazonaws.com/aws-tools-mcp-server:latest"
        }
    },
    networkConfiguration={
        "networkMode": "PUBLIC"
    }
)

print("AgentCore Runtime ARN:", response["agentRuntimeArn"])
print("Endpoint:", response["agentRuntimeEndpoint"])

AgentCore handles: session isolation (each user gets their own MCP session in a dedicated microVM), automatic scaling, authentication, and 8-hour maximum session support for long-running operations.

Step 5 — Connect to a Bedrock Agent

Now wire the deployed MCP server into a Bedrock agent:

import boto3
import json

bedrock_runtime = boto3.client("bedrock-runtime", region_name="us-east-1")

# Your MCP server endpoint from Step 4c
MCP_ENDPOINT = "https://your-agentcore-endpoint.bedrock-agentcore.us-east-1.amazonaws.com"

def run_agent_with_mcp(user_message: str) -> str:
    """
    Bedrock agent that uses your deployed MCP server as its tool provider.
    """
    messages = [
        {"role": "user", "content": [{"text": user_message}]}
    ]

    system = [{
        "text": f"""You are an AWS assistant with access to DynamoDB and S3 tools.
        Use your tools to answer questions about the user's AWS data.
        Always use tools to get real data — never guess or make up values.
        MCP Server: {MCP_ENDPOINT}"""
    }]

    # Tool config pointing to your MCP server
    tool_config = {
        "tools": [{
            "toolSpec": {
                "name": "query_dynamodb",
                "description": "Query a DynamoDB table by primary key",
                "inputSchema": {
                    "json": {
                        "type": "object",
                        "properties": {
                            "table_name": {"type": "string"},
                            "key_name": {"type": "string"},
                            "key_value": {"type": "string"}
                        },
                        "required": ["table_name", "key_name", "key_value"]
                    }
                }
            }
        }, {
            "toolSpec": {
                "name": "get_s3_summary",
                "description": "List and summarize files in an S3 bucket",
                "inputSchema": {
                    "json": {
                        "type": "object",
                        "properties": {
                            "bucket_name": {"type": "string"},
                            "prefix": {"type": "string"}
                        },
                        "required": ["bucket_name"]
                    }
                }
            }
        }]
    }

    # Agentic loop
    for _ in range(10):
        response = bedrock_runtime.converse(
            modelId="anthropic.claude-3-sonnet-20240229-v1:0",
            system=system,
            messages=messages,
            toolConfig=tool_config
        )

        stop_reason = response["stopReason"]
        output = response["output"]["message"]
        messages.append(output)

        if stop_reason == "end_turn":
            for block in output["content"]:
                if "text" in block:
                    return block["text"]

        elif stop_reason == "tool_use":
            tool_results = []
            for block in output["content"]:
                if "toolUse" not in block:
                    continue

                tool = block["toolUse"]
                tool_name = tool["name"]
                tool_input = tool["input"]

                # Route to correct tool
                if tool_name == "query_dynamodb":
                    result = query_dynamodb(**tool_input)
                elif tool_name == "get_s3_summary":
                    result = get_s3_summary(**tool_input)
                else:
                    result = json.dumps({"error": f"Unknown tool: {tool_name}"})

                tool_results.append({
                    "toolResult": {
                        "toolUseId": tool["toolUseId"],
                        "content": [{"text": result}]
                    }
                })

            messages.append({"role": "user", "content": tool_results})

    return "Agent reached iteration limit"


# Test it
response = run_agent_with_mcp(
    "How many files are in my data-lake-prod bucket? "
    "And look up user ID 'user_123' in my Users table."
)
print(response)

The Three Things That Break MCP in Production

1 — Vague tool descriptions

Claude decides which tool to call based entirely on the description field. If your description is vague, Claude either skips the tool or calls it when it shouldn't.

# Weak — Claude might not call this when it should
@mcp.tool()
def get_data(table: str, key: str) -> str:
    """Get data from a table."""

# Strong — Claude knows exactly when to use this
@mcp.tool()
def query_dynamodb(table_name: str, key_name: str, key_value: str) -> str:
    """
    Query a DynamoDB table by primary key.
    Use this when the user wants to look up specific records,
    find customer data, retrieve order information, or access
    any structured data stored in DynamoDB.
    """

2 — Returning too much data

MCP tool results flow back into the agent's context window. A tool that returns 10,000 rows from DynamoDB will burn your context window in one call.

Always limit your returns: paginate aggressively, return summaries not raw dumps, use limit parameters in every database query.

3 — Not handling tool failures

If your tool raises an exception, the entire agentic loop breaks. Every tool should return structured JSON even on failure:

try:
    result = do_the_thing()
    return json.dumps({"success": True, "data": result})
except Exception as e:
    return json.dumps({"success": False, "error": str(e), "tool": "tool_name"})

The agent can read the error message and respond gracefully. An uncaught exception just crashes.

Stateful MCP: AWS's New Feature (March 2026)

AWS just shipped stateful MCP server support in AgentCore Runtime. This is significant.

Previously, each MCP call was stateless — the server had no memory between tool invocations. Now, each user session gets a dedicated microVM with session context preserved using an Mcp-Session-Id header.

This enables:

Elicitation — the server can ask the user follow-up questions mid-tool execution
Sampling — the server can request Claude to generate content as part of a tool's operation
Progress notifications — real-time updates for long-running operations

For long-running tasks (ML training jobs, large data exports, multi-hour simulations), this changes the architecture completely. The server can now maintain state across a multi-hour operation without requiring the agent session to stay open.

What to Build Next

With this foundation working, the natural next steps:

Add more AWS tools — CloudWatch metrics querier, RDS query executor, Lambda invoker, Step Functions status checker. Each becomes a tool your agent can use.

Add Bedrock Guardrails — wrap your MCP server with content filtering and PII detection that operates outside the agent's reasoning loop.

Multi-agent coordination — one coordinator agent that routes requests to specialist subagents, each with their own focused MCP server and tool set.

AgentCore Gateway — instead of embedding tool schemas in your agent, register your MCP server with AgentCore Gateway and let multiple agents discover the same tools via a central registry.

The full production version of this architecture — agentic loops, multi-agent systems, MCP server builds, Bedrock Guardrails, CloudWatch observability — is covered hands-on in the CCA-001: Claude Certified Architect track. Real Bedrock sandboxes, automated validation, no AWS account needed.

If you want to build the architecture in this article in a real environment without worrying about AWS billing, that's the path.

👉 cloudedventures.com/labs/track/claude-certified-architect-cca-001

What are you building with MCP? Drop a comment — especially if you hit a specific architecture problem I can help with.

Claude Code Power User Guide: /ghost, OODA, L99, KAIROS and Every Hidden Feature From the Source Code Leak

Aj — Wed, 08 Apr 2026 18:09:35 +0000

If you're using Claude Code the same way you use ChatGPT — typing conversational prompts and hoping for the best — you're leaving 80% of its power on the table.

I've been deep in Claude Code for 90+ days building a production AWS learning platform. What I've learned: the difference between average and power-user results comes down to knowing what's under the hood.

The March 2026 source code leak gave us that knowledge. Here's the complete, tested guide.

What Got Leaked (Quick Summary)

On March 31, 2026, Anthropic published Claude Code version 2.1.88 to npm with a .map source file included by accident. 512,000 lines of TypeScript. 1,900 files. 44 feature flags. The complete system prompt. Everything.

The key takeaways for power users:

Claude Code has 40+ built-in tools — most people use 3-4
The system prompt explicitly tells Claude to be direct — conversational prompts work against this
Parallel tool execution is built-in but only triggers with properly structured prompts
CLAUDE.md is a first-class feature that loads automatically every session
20+ unreleased features are built and tested but flagged off in public builds

Let's turn each of these into actionable techniques.

1. The Prompt Frameworks

`/ghost` — Kill the AI Voice

Use /ghost when Claude Code's output will be read by humans (docs, READMEs, PR descriptions, emails).

# Without /ghost
/ghost rewrite this README to sound like a senior engineer wrote it, not an AI

The output drops the hedging ("It's worth noting that..."), the filler ("In order to..."), and the corporate tone. You get clean, direct prose.

When to use: Documentation, blog posts, commit messages, Slack messages, code comments.

`OODA` — Force a Decision

OODA (Observe-Orient-Decide-Act) is a military decision framework. In Claude Code, it prevents the "here are the pros and cons" non-answer.

OODA: Our API currently uses REST. We're adding real-time features. 
Should we add WebSockets, use SSE, or switch to GraphQL subscriptions? 
We have 3 engineers and ship weekly.

Claude will observe your constraints, orient around your team size and shipping cadence, decide on one approach, and act by providing the implementation plan.

No more "it depends." You get a decision with reasoning.

`L99` — Expert Depth

L99: Design a DynamoDB single-table schema for a multi-tenant SaaS 
with per-tenant billing, usage metering, and team permissions

Without L99, you get a tutorial answer. With L99, you get GSI overloading patterns, composite sort keys for time-series queries, TTL-based cleanup strategies, and the exact access patterns with their key conditions.

`SCAFFOLD` — Full Project Setup

SCAFFOLD: Production Next.js 15 app
- Prisma + PostgreSQL
- NextAuth with GitHub + Google
- Tailwind CSS
- Vitest + Playwright
- GitHub Actions CI/CD
- Vercel deployment

Claude generates the full directory structure, all config files, and boilerplate before touching business logic.

`PERSONA` — Domain Expert Mode

PERSONA: Senior AWS Solutions Architect with 10 years experience. 
Review this CloudFormation template for production readiness.

This frames Claude's entire response through that expertise lens.

2. System Prompt Insights You Can Exploit

Be Terse

The system prompt tells Claude Code to be direct. Mirror that:

# ❌ This triggers verbose mode
"Hey Claude, could you take a look at this function and let me know 
if there's anything that might be improved? Thanks!"

# ✅ This gets the system prompt working for you
"What's wrong with this function? Fix it."

Parallel Execution

Claude Code can run tools simultaneously, but only when you make independence explicit:

# ❌ Sequential — Claude plays it safe
"Check the frontend components and then run the API tests"

# ✅ Parallel — both fire at once  
"Two independent tasks:
1. Audit src/components/ for React anti-patterns
2. Run and fix failing tests in src/api/__tests__/"

On large codebases, this cuts response time significantly.

The Bash Tool is King

The leaked tool definitions show bash is Claude Code's most capable tool. It can install packages, run tests, check git status, read files, and execute arbitrary commands.

Power users lean into this:

"Run the test suite. If anything fails, read the failing test file, 
understand what it expects, then fix the source code. Repeat until green."

This creates an autonomous debugging loop.

3. CLAUDE.md — Your Project's AI Memory

The source confirms CLAUDE.md is loaded automatically. Here's a battle-tested template:

# Project: [Name]

## Stack
- [Framework] + [Database] + [Deploy target]
- Key deps: [list the non-obvious ones]

## Architecture Decisions
- [Decision 1]: [Why]
- [Decision 2]: [Why]

## Code Conventions  
- [Pattern]: [Where to use]
- [Anti-pattern]: [What to avoid]

## Current Context
- Working on: [Current feature/sprint]
- Recent changes: [What changed this week]
- Known issues: [Active bugs]

## Testing
- Framework: [Vitest/Jest/Playwright]
- Run: [exact command]
- Coverage: [current %]

## Deploy
- Staging: [command]
- Production: [command + checklist]

This replaces 10 minutes of context-setting at the start of every session.

4. Unreleased Features (From the Leak)

These are built, tested, and hidden behind compile-time flags:

KAIROS — Background Agent Mode

Referenced 150+ times in the source. An autonomous daemon that runs memory consolidation while you're idle. It can plan tasks, execute them in the background, and surface results when you return. Think: "Fix all the lint warnings while I'm at lunch."

BUDDY — AI Coding Companion

A Tamagotchi-style pet that lives in your terminal. Species deterministically generated from your userId hash (salt: friend-2026-401). Cosmetic hats. Speech bubbles. Claude generates its name and "soul description" on first hatch.

Leaked internal notes suggest an April 1-7 teaser with full launch in May 2026. The /buddy command did activate on April 1 as predicted.

Voice Mode

Talk to Claude Code. Useful for pair programming. In the source but not shipped.

ULTRAPLAN

Extended planning mode with multi-step task decomposition.

Undercover Mode

Details sparse, but it's referenced in the feature flags.

5. My Daily Workflow

After 90 days, here's my exact process:

Morning:
  claude --resume          # pick up where I left off
  /init                    # if new project, generate CLAUDE.md

Planning:
  Shift+Tab → plan mode    # architecture first
  OODA for decisions       # no "it depends"
  L99 for deep dives       # principal-engineer answers

Building:
  Parallel task prompts    # 2x speed on independent work
  SCAFFOLD for new modules # structure before code
  Autonomous bash loops    # "fix until green"

Shipping:
  /ghost for PR descriptions
  /ghost for changelog entries
  Review with PERSONA: "Senior reviewer focused on security"

Hands-On Practice

If you want to practice these techniques with real AWS infrastructure, I've been building Cloud Edventures — guided missions in sandbox environments with automated validation. The AI Navigator path specifically covers Claude + Bedrock integration where you'll use a lot of these patterns.

The /ghost and OODA frameworks work in any AI tool though — start there.

What's Your Power-User Trick?

I'm collecting Claude Code techniques for a follow-up post. If you've found something that changed your workflow, drop it in the comments.

The gap between "using Claude Code" and "being a Claude Code power user" is wider than most people think. These frameworks close it.

Why creating an AWS account is harder than it should be — especially in India

Aj — Tue, 07 Apr 2026 11:57:19 +0000

You decided to learn AWS. You went to aws.amazon.com, clicked "Create a Free Account," and ran straight into a wall.

Credit card required. Phone verification that never calls back. A mysterious ₹2 charge on your card. Documents that don't match. An account suspended before you ever deployed anything.

This is one of the most complained-about onboarding experiences in cloud computing — and if you are in India, there is an entire extra layer of complexity that most guides completely skip.

Here's everything AWS requires, why each hurdle exists, what breaks, and how to get past all of it.

What AWS Requires Globally

1. A unique email address

Cannot be tied to an existing Amazon account. If you shop on Amazon.in, that email is already taken. Use a different one.

2. A valid payment method

AWS requires a credit or debit card even for the free tier — used for identity verification and fraud prevention.

What happens: AWS places a $1 USD temporary authorization hold (or ₹2 for AISPL accounts in India). This is not a charge. It disappears in 3-5 business days. Your bank may show it as a pending transaction — this is normal.

Cards that work: Visa or Mastercard credit/debit cards enabled for international online transactions, American Express.

Cards that commonly fail:

Prepaid or gift cards
Cards not enabled for international transactions
Cards with strict fraud settings blocking new merchant authorizations
Cards with zero balance (can't hold even a small authorization)

Fix for card declines: Call your bank, say "I'm making a ₹2 authorization attempt from Amazon Web Services, please whitelist this merchant." This resolves most card issues in 5 minutes.

3. Phone verification

AWS calls or texts your number with a PIN.

Numbers that fail: VoIP numbers (Google Voice, Skype, most internet calling apps), numbers blocked for international calls.

If the call doesn't come: Switch from voice to SMS, wait 10 minutes between attempts. Too many failed attempts locks you out — contact AWS Support to reset.

4. Account activation (up to 24 hours)

Usually 15-60 minutes in practice. Some services like Bedrock stay locked until full activation — wait and retry before contacting support.

The India-Specific Layer: AISPL + KYC Documents

This is where Indian users hit a completely different set of walls that global guides never cover.

What is AISPL?

When you create an AWS account with an Indian address, you are contracting with AISPL — Amazon Internet Services Private Limited, not AWS Inc. globally. AISPL is AWS's local Indian legal entity and your billing, verification, and payment rules are all different.

The ₹2 temporary hold (instead of $1) comes from AISPL. Your invoices are in INR. RBI payment regulations apply to your account.

KYC Document Verification in India

At some point after account creation — either immediately or when AWS flags your account for identity verification — you will be asked to submit a government-issued ID document.

Documents AWS India (AISPL) accepts:

✅ PAN Card
✅ Voter ID (EPIC Card)
✅ Driving License
✅ Passport

What AWS India does NOT currently accept:

❌ Aadhaar card alone

This surprises many Indian developers because Aadhaar is widely accepted for financial KYC across banks, telecom, and fintech platforms in India. But AWS's verification system does not list Aadhaar as a selectable document type. If Aadhaar is the only government ID you have, you need to contact AWS Support directly and explain your situation — there is no standard workaround through the normal interface.

Why Aadhaar is not enough for AWS (the practical reason): AWS uses the PAN/Voter ID/Passport/Driving License for identity linkage in ways that Aadhaar's current integration doesn't support in their system. It's a platform limitation, not a legal one — Aadhaar is a perfectly valid government ID under Indian law, just not yet integrated into AWS's verification flow.

The PAN Card + Aadhaar Linkage (Important from 2025)

From July 2025, applying for a new PAN card requires Aadhaar authentication, and existing PAN cards must be linked to Aadhaar. If your PAN is not linked to your Aadhaar, it became inoperative from January 2026 — which would also make it invalid for AWS verification.

Before using your PAN for AWS verification:

Confirm your PAN is active at incometax.gov.in
Confirm PAN-Aadhaar linking is complete
An inoperative PAN will fail AWS verification even though the number itself is valid

RBI Payment Regulations Affecting AISPL Accounts

The Reserve Bank of India regulates how payment data can be stored, which creates friction for Indian AWS users that global accounts don't experience.

Key things to know:

AWS Marketplace contract products can no longer use stored credit/debit cards for AISPL accounts due to RBI regulations — you need to manually enter card details or switch to Pay By Invoice
For pay-as-you-go Marketplace products, you must manually input card details for each payment
If you use AWS for business and volume is significant, switching to Pay By Invoice is smoother than repeated manual card entry

The Billing Anxiety Problem (India-Specific Too)

Even after successfully getting through all the above, there is a second wall: billing anxiety.

You are finally in the AWS console. Ready to practice Lambda, S3, or Bedrock. And then you pause.

What if I forget to stop this instance? What if I accidentally go over free tier? What if I get a ₹5,000 bill next month?

This is rational. AWS billing is opaque, and horror stories are real — developers leaving an EC2 instance running over a long weekend, data transfer costs from misconfigured S3 buckets, NAT Gateways charging quietly in the background.

For Indian developers, the anxiety is often sharper. Currency conversion means a $50 bill is ₹4,000+. The free tier limits are the same globally but the consequences of mistakes feel more significant.

The result: most developers watch tutorials instead of building. They read documentation instead of deploying. When interviews arrive, they can describe AWS services but can't walk through something they actually built.

Three Options for Hands-On Practice

Option 1 — Your own AWS account with guardrails

Create a billing budget alert at ₹400/month immediately after account setup. Use IAM users (never root) for daily practice. Stick to free tier services and instance types. Stop all resources at end of every session.

The anxiety doesn't disappear but a billing alert means the worst case is an email warning before ₹400 is spent.

Option 2 — AWS Educate / AWS Academy

For students and educators, AWS Educate provides sandbox credits. Good if you qualify — the limitation is expiry dates and service restrictions that make comprehensive practice harder.

Option 3 — Pre-built isolated sandbox environments

The option that removes both the account setup friction and the billing anxiety completely: practicing in real AWS environments where someone else handles the account, compliance, and resource cleanup.

Cloud Edventures runs exactly this model. Real AWS sandboxes — actual Lambda functions, actual S3 buckets, actual IAM roles, actual Bedrock environments — without needing to go through AISPL verification, PAN card submission, RBI-compliant payment setup, or any of the above. The billing isolation is handled at the platform level.

Built specifically for developers who want to build real cloud skills without the account setup friction — which is a genuine problem in India that most global platforms don't address.

No AWS account needed. No ₹2 holds. No KYC document submission. No billing surprises.

👉 cloudedventures.com

India AWS Account Checklist

Before you start:

Unique email not tied to Amazon.in account
Active PAN card linked to Aadhaar (verify at incometax.gov.in)
Debit/credit card enabled for international transactions
Call your bank to whitelist ₹2 authorization from Amazon Internet Services

During setup:

Choose SMS over voice for phone verification (more reliable)
Have your PAN Card, Voter ID, Driving License, or Passport ready for KYC
If asked for identity verification, Aadhaar alone won't work — use PAN or Passport

After account is active:

Set billing alert at ₹400/month immediately
Enable MFA on root account
Create IAM user — practice as IAM, not root
Check AISPL payment settings if using AWS Marketplace

If stuck:

AWS Support → Account and Billing → Activation category (free support)
Only have Aadhaar and no other ID? Contact AWS Support directly — explain and request manual review
Card issues → bank whitelist of "Amazon Internet Services Private Limited" usually fixes it

Stuck on a specific step? Drop it in the comments — especially if you hit an India-specific issue.

Cloud engineer in 2026: the honest roadmap that actually gets you hired

Aj — Mon, 06 Apr 2026 12:46:16 +0000

Most cloud engineer roadmaps give you a list of services to learn and certifications to collect.

What actually gets you hired is different. Here is that roadmap.

What the job actually requires

Cloud engineers design, build, and maintain cloud infrastructure. On any given week that means:

Writing Terraform or CloudFormation to provision infrastructure as code
Building CI/CD pipelines that deploy code automatically
Setting up monitoring so teams know when things break before users do
Debugging why a Lambda function is timing out or two services can not communicate

The common thread: building systems that run reliably without you watching. That requires hands-on experience with real AWS — not just knowing what the services are.

The real skill stack (in priority order)

1. Linux fundamentals — do not skip this

Every cloud environment runs Linux. If you cannot navigate a file system, read logs, manage permissions, and write shell scripts, you will struggle with everything else.

Start here before AWS. One week of real Linux practice saves months of confusion later.

2. Networking basics

VPCs, subnets, security groups, route tables, NAT gateways. You do not need to be a network engineer. You need to understand how data flows between services and why a connection might fail.

The most common junior cloud engineer interview failure: they can configure services but cannot debug why two services cannot communicate. Networking is usually the answer.

3. Core AWS services — hands-on, not watched

Compute: Lambda and EC2. Build a Lambda function that does something real — reads from S3, writes to DynamoDB, calls an external API. Understand when to use each.

Storage: S3 for files, DynamoDB for NoSQL, RDS for relational. Know how IAM roles grant access between them.

Networking: VPC setup, security groups, Application Load Balancers. Deploy something behind a load balancer with proper security.

Monitoring: CloudWatch dashboards and alarms. Know how to detect problems before users report them.

4. Infrastructure as Code

Terraform is the industry standard. CloudFormation is AWS-native. Know at least one deeply.

The goal is understanding why IaC matters: every manual console click is a change that cannot be tracked, reviewed, or reproduced. Good cloud engineers automate everything.

5. CI/CD pipelines

GitHub Actions, AWS CodePipeline, or Jenkins. Build a pipeline that automatically tests and deploys code when you push to a branch. Table stakes for any cloud role.

The certification question (honest answer)

AWS Solutions Architect Associate (SAA-C03) is worth getting. It validates broad AWS knowledge and passes ATS filters.

Cloud Practitioner is useful for complete beginners but provides weak signal to hiring managers.

The honest truth: a certification without projects is weak evidence. A portfolio without a cert gets ignored by automated screening. You need both — but projects matter more in the interview room.

The three portfolio projects that get interviews

Build these. They cover the full cloud engineer skill stack and give you specific things to discuss in technical interviews.

Project 1: Serverless REST API

Lambda + API Gateway + DynamoDB + IAM + CloudWatch. Build a working API that does something real — a URL shortener, a task manager, a simple inventory system. Use IAM least privilege. Add monitoring.

Demonstrates: Lambda, API Gateway, DynamoDB, IAM, CloudWatch, serverless architecture.

Project 2: Infrastructure as Code

Reproduce Project 1 entirely with Terraform or CloudFormation. No console clicks. Everything version-controlled in GitHub, deployable with one command.

Demonstrates: IaC, version control, infrastructure design, reproducibility.

Project 3: CI/CD pipeline

Add GitHub Actions that automatically runs tests and deploys infrastructure on push to main. Include staging with a manual approval gate before production.

Demonstrates: CI/CD, environment management, deployment automation, testing.

These three projects together cover everything a cloud engineer job description asks for.

The practice problem nobody talks about

Most people hit the same wall: practicing on real AWS costs money and one mistake causes a surprise bill. That anxiety makes people hesitant to experiment freely.

Hesitant experimentation does not build intuition. Cloud engineers develop intuition by breaking things and fixing them.

The solution is isolated sandbox environments. Cloud Edventures provides real AWS environments for hands-on labs — Lambda, S3, IAM, DynamoDB, CloudFormation, CodePipeline, Auto Scaling, Terraform, GitHub Actions OIDC — with automated validation and no billing risk. The Core AWS Foundations track goes from your first Lambda function through event-driven architectures and Step Functions.

Start free at cloudedventures.com/labs/track/aws-cloud-foundations — no AWS account needed.

The timeline that works

Weeks 1–2: Linux + basic networking. Do not skip.
Weeks 3–6: Core AWS hands-on. Build things, do not just read.
Weeks 7–10: SAA-C03 study alongside building. When you read about a service, deploy it.
Weeks 11–14: Terraform + CI/CD. Build the three portfolio projects.
Week 15+: Apply. Document projects in GitHub with READMEs and architecture diagrams.

3–4 months of focused hands-on work. Not 6 months of course watching.

The one thing that separates hires from rejections

"I know AWS" does not get you hired.

"I built a serverless event processing pipeline using Lambda, SQS, and DynamoDB with CloudWatch monitoring and Terraform IaC" does.

Build specific things. Document them specifically. Talk about them specifically.

The certification proves you studied. The portfolio proves you can build.

What part of the cloud engineer roadmap are you working on right now? Drop it in the comments.

AWS Bedrock in 2026: what it actually is and how to build your first AI agent on it

Aj — Sun, 05 Apr 2026 16:47:42 +0000

Most AWS Bedrock content is either marketing copy or academic papers. Neither is useful if you're trying to actually build something.

This is the architecture, the real code patterns, and the things that actually trip people up in production.

What AWS Bedrock actually is

AWS Bedrock is Amazon's managed AI inference platform. It gives you API access to foundation models — Claude, Llama, Titan, Mistral — without managing the infrastructure those models run on.

The reason it's become the foundation of most enterprise AI deployments is simple: it sits inside your existing AWS infrastructure. Your IAM roles, VPCs, CloudWatch, Lambda functions — they all work with Bedrock the same way they work with S3 or DynamoDB.

Four primitives make it powerful beyond raw model access:

Knowledge Bases — managed RAG. Connect an S3 bucket of documents, Bedrock handles embedding, vector storage, and retrieval automatically.
Agents — managed agentic orchestration. Define tools (Lambda functions) the model can call, Bedrock manages conversation history and the agentic loop.
Guardrails — content filtering, PII detection, topic restrictions at the platform level, not in your application code.
Prompt Management — versioned, managed prompts. Test variants, roll back bad changes, maintain consistency across environments.

The core pattern: how a Bedrock agent works

Every Bedrock agent follows the same underlying pattern:

User sends message
    ↓
Model receives message + tool definitions + conversation history
    ↓
Model returns: stopReason = "tool_use" OR "end_turn"
    ↓
If tool_use: execute the Lambda, append result, loop again
If end_turn: return response to user

The model does not execute tools — it requests them. Your code executes them and feeds the result back.

Here is the full implementation:

import boto3
import json

client = boto3.client("bedrock-runtime", region_name="us-east-1")

tools = [
    {
        "toolSpec": {
            "name": "get_s3_file_list",
            "description": "List files in an S3 bucket. Use when the user asks about files or data stored in S3.",
            "inputSchema": {
                "json": {
                    "type": "object",
                    "properties": {
                        "bucket_name": {
                            "type": "string",
                            "description": "The S3 bucket name to list"
                        },
                        "prefix": {
                            "type": "string",
                            "description": "Optional prefix to filter results"
                        }
                    },
                    "required": ["bucket_name"]
                }
            }
        }
    }
]


def execute_tool(tool_name: str, tool_input: dict) -> str:
    if tool_name == "get_s3_file_list":
        s3 = boto3.client("s3")
        response = s3.list_objects_v2(
            Bucket=tool_input["bucket_name"],
            Prefix=tool_input.get("prefix", "")
        )
        files = [obj["Key"] for obj in response.get("Contents", [])]
        return json.dumps({"files": files, "count": len(files)})
    return json.dumps({"error": f"Unknown tool: {tool_name}"})


def run_bedrock_agent(user_message: str) -> str:
    messages = [{"role": "user", "content": [{"text": user_message}]}]
    system = [{"text": "You are an AWS assistant. Use tools to get real data rather than guessing."}]

    for _ in range(10):
        response = client.converse(
            modelId="anthropic.claude-3-sonnet-20240229-v1:0",
            system=system,
            messages=messages,
            toolConfig={"tools": tools}
        )

        stop_reason = response["stopReason"]
        output = response["output"]["message"]
        messages.append(output)

        if stop_reason == "end_turn":
            for block in output["content"]:
                if "text" in block:
                    return block["text"]

        elif stop_reason == "tool_use":
            tool_results = []
            for block in output["content"]:
                if "toolUse" not in block:
                    continue
                tool = block["toolUse"]
                result = execute_tool(tool["name"], tool["input"])
                tool_results.append({
                    "toolResult": {
                        "toolUseId": tool["toolUseId"],
                        "content": [{"text": result}]
                    }
                })
            messages.append({"role": "user", "content": tool_results})

    return "Agent reached iteration limit"


print(run_bedrock_agent("How many files are in my data-lake-prod bucket?"))

stopReason is your only control signal. "tool_use" means keep looping. "end_turn" means stop. Everything else is implementation detail.

What Bedrock adds over raw API access

If you are already calling Claude's API directly, three things matter in production:

IAM-native access control — Use IAM roles instead of API keys. No secrets to rotate, no credential leaks. Your Lambda gets a role, that role gets a Bedrock policy.

Built-in observability — Every Bedrock call shows up in CloudWatch automatically. Latency, token usage, error rates, throttling — zero instrumentation required from you.

VPC isolation — Model calls can run inside your VPC. For healthcare, finance, or regulated workloads this is the difference between a viable architecture and a compliance non-starter.

The three bugs that break Bedrock agents in production

Bug 1 — Checking content type instead of stopReason

# This breaks silently on complex tasks
if response["output"]["message"]["content"][0]["type"] == "text":
    return  # Agent stops before the tool ever runs

# This is correct
if response["stopReason"] == "end_turn":
    return

Claude returns explanatory text alongside tool_use blocks. If you check content type to detect completion, you terminate the loop before the tool executes.

Bug 2 — Missing assistant message before tool results

# Missing a critical step
messages.append(tool_result_message)

# Correct — append assistant response first, then the tool result
messages.append(output)               # The assistant's tool_use request
messages.append(tool_result_message)  # Then the result

Without the assistant message in history, the model cannot connect the tool result back to its own request. You get confused or looping responses.

Bug 3 — Using the iteration cap as your primary stop

The for _ in range(10) is a safety net against runaway loops — not your stopping condition. stopReason is how the model signals it is finished. Cap is a ceiling, not a controller.

What comes next after the basics

Once the core loop works, the natural Bedrock progression is:

Knowledge Bases — connect documents, let the model ground answers in your actual data
Bedrock Guardrails — content filters and PII detection the model cannot be prompted around
Multi-agent coordination — coordinator agent delegating to specialist subagents via tool calls, each with an isolated context window
CloudWatch observability — latency distribution, token cost, tool call frequency, error rates per agent

Getting hands-on

Understanding the architecture is step one. Building intuition for what breaks in production — failed tools, bad tool inputs, sessions that run longer than expected — requires actually running the system.

If you want to work through these patterns in a real AWS Bedrock sandbox — agentic loops, tool sequencing, Guardrails, CloudWatch dashboards — Cloud Edventures has a hands-on track covering exactly this. The CCA-001: Claude Certified Architect track runs in isolated AWS sandboxes with automated validation. No AWS account needed.

👉 cloudedventures.com/labs/track/claude-certified-architect-cca-001

What is the most confusing part of Bedrock for you? Drop a comment — happy to go deeper on any section.

5 tools that turn Claude Code from good to unstoppable (exact install commands)

Aj — Thu, 26 Mar 2026 11:17:03 +0000

Most developers use Claude Code the same way they used Stack Overflow. Ask a question, get an answer, move on.

The developers shipping fastest in 2026 use a specific stack around it. Five tools. Each one fixes a specific failure mode. Here they are with exact install commands.

The three things that break Claude Code

Context rot — Quality drops at ~50% context usage, not at the limit. Most developers don't notice until Claude writes duplicate code it wrote 20 messages ago.

Hallucinated APIs — Training data is 6–12 months behind. Claude confidently suggests functions that were renamed, deprecated, or never existed in your version.

No planning phase — Claude dives into code on your first vague prompt. No spec. No architecture. Three hours later you're rewriting everything.

Each tool below attacks one of these.

Tool 1 — cc-statusline

Fixes: Context rot — you can't manage what you can't see

npx cc-statusline@latest

Adds a status bar to your terminal showing model, context%, session cost, and git branch in real time.

Configure your lines:

Line 1: model | context% | session_cost | session_clock  
Line 2: git_branch | git_worktree

The rule: When context hits 50%, stop and /clear. Don't use /compact — it's lossy compression that keeps context poisoning. /clear reloads your CLAUDE.md and starts completely fresh with zero information loss.

Built-in alternative: type /statusline directly in Claude Code and it generates a script for you.

Tool 2 — Superpowers plugin

Fixes: Vague prompts → vague code. No planning phase.

Stats: 99,000+ GitHub stars. Official Anthropic marketplace.

/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

Restart. Skills activate automatically — no manual triggers needed.

The three-step workflow it enforces:

Brainstorm — Claude asks clarifying questions, proposes 2–3 approaches, produces a design doc you approve. Code doesn't start until you sign off.

Write Plan — Breaks your spec into 2–5 minute tasks with exact file paths and complete code. A proper plan is 300–500 lines. Not a vague outline.

Execute Plan — Dispatches subagents, each in their own isolated context window. Main instance only gets small update summaries. Context never bloats.

This is spec-driven development. The biggest tech companies use it. Now you can with two install commands.

Tool 3 — Context7 MCP

Fixes: Hallucinated APIs from stale training data

claude mcp add context7 -- npx -y @upstash/context7-mcp@latest

Or add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    }
  }
}

How to use: Append "use context7" to any library-related prompt.

Build a Next.js 15 server component that fetches from Supabase. use context7

Context7 fetches current documentation from the official source and injects it before Claude generates code. Claude then uses actual APIs instead of guessing from 12-month-old training data.

Works with React, Next.js, Supabase, Tailwind, Prisma, and thousands of other libraries.

Tool 4 — Warp terminal

Fixes: Claude is a black box — you can't see what it's building while it builds

Free at warp.dev (macOS and Linux)

Three features that matter:

Side panel — Open your file tree alongside Claude. Review generated code as it's written, not after.

Split terminals (Cmd+D) — Run multiple Claude Code instances in parallel. One building, one reviewing, one testing.

Tabs (Ctrl+T) — Multiple projects open simultaneously without losing session state.

Core habit: keep your file tree open in the side panel while Claude executes a plan. Review each file as it's generated. Catch bad decisions before they compound.

Tool 5 — Sequential Thinking MCP

Fixes: Claude jumping to solutions before reasoning through the problem

Tell Claude: "Please install the sequential thinking MCP server"

Claude finds the package, installs it, and configures everything. Restart when done.

Forces chain-of-thought reasoning before Claude produces an answer. Pairs especially well with Superpowers brainstorming — design doc quality improves noticeably.

Use for: architecture decisions, complex debugging, designing systems that will be hard to change later.

Skip for: simple tasks, variable renames, quick fixes. Adds latency and tokens — match it to the complexity.

The full stack in action

1. Open Warp → start Claude Code
2. Status bar shows context% (cc-statusline)
3. Describe the feature
4. Superpowers brainstorm activates automatically
5. Claude reasons through approaches (sequential thinking)
6. Mention a library → Context7 fetches live docs
7. Approve spec → Superpowers writes detailed plan
8. Review plan in Warp side panel
9. Execute → subagents build in isolated context windows
10. Context% stays low (subagents handle heavy lifting)
11. Main context hits 50% → /clear and reload

Production-quality code. No hallucinated APIs. Documented plan you can review and hand off.

Install priority if you have 10 minutes

cc-statusline — visibility first, 2 min
Context7 — eliminates the most common failure mode, 2 min
Superpowers — biggest quality improvement, 3 min
Warp — quality of life, 5 min
Sequential Thinking — just ask Claude, 1 min

For hands-on labs building the agentic patterns these tools enable — coordinator-subagent systems, MCP servers, production Claude/Bedrock architectures — Cloud Edventures CCA-001 track, 22 labs, real AWS sandboxes.

Search: Cloud Edventures CCA-001

Which tool made the biggest difference in your setup? Drop a comment.

Your CLAUDE.md is probably broken — 5 silent failure patterns and how to fix them

Aj — Wed, 25 Mar 2026 18:27:00 +0000

CLAUDE.md is the most important file in your Claude Code setup. It's also the easiest to get silently wrong.

Here's the uncomfortable truth: Claude actively filters what it follows from your CLAUDE.md — it doesn't treat everything as a permanent command. Most production CLAUDE.md files are broken and developers don't know it.

TL;DR

Claude has an instruction budget of ~100–150 slots after its own system prompt
Files over 60 lines cause Claude to silently ignore rules mid-session
"Never do X" rules without alternatives cause Claude to freeze and ask permission
@file embeds burn context on every session — reference instead
CLAUDE.md is advisory (80% compliance) — hooks are deterministic (100%)

The budget problem nobody talks about

Claude Code injects a system reminder above your instructions: "This context may or may not be relevant to your tasks." Claude actively decides which rules to follow per turn.

Frontier models follow roughly 150–200 instructions before compliance drops. Claude Code's own system prompt uses ~50 of those slots. That leaves you about 100–150 slots.

If your CLAUDE.md has 60+ rules, Claude is silently ignoring some. You just don't know which ones.

Failure 1 — The kitchen sink file

# TOO LONG — Claude starts ignoring rules mid-session
- Use TypeScript strict mode
- Prefer functional components  
- Use arrow functions
- Destructure props
- Use const over let
- Avoid any type
- Use interface over type
- Always handle errors
- Use async/await not .then()
- Add JSDoc to public functions
... (30 more rules)

When context fills, Claude weights early rules heavily and discards later ones. The rules you care most about are usually at the bottom.

Fix: Keep it under 60 lines. For each rule ask: "Would removing this cause Claude to make a mistake?" If not, cut it.

Failure 2 — Prohibitions without alternatives

# BAD — Claude freezes every time
- Never use console.log
- Never use var
- Never commit to main

# GOOD — Claude has a path forward
- Never use console.log; use src/utils/logger.ts
- Never use var; use const, or let for reassigned variables
- Never commit to main; create feature/description branch

Every "never" needs an "instead, do this." Without it, Claude pauses and asks permission every time it hits the rule, breaking flow.

Failure 3 — @file embeds killing your context

# BAD — embeds entire files on every session start
@src/utils/api-client.ts
@docs/architecture.md
@docs/design-system.md

# GOOD — reference, don't embed
- For API patterns, see src/utils/api-client.ts
- For architecture decisions, see docs/architecture.md
- For design system, see docs/design-system.md

@file embeds the full file content into every conversation. A 500-line architecture doc loaded every session burns context before you've typed a word.

Failure 4 — Missing bash commands

The most commonly skipped section. The most valuable one.

## Commands
- Build: npm run build
- Test (single file): npm run test -- --testPathPattern=
- Type check: npm run typecheck
- Lint + fix: npm run lint:fix
- Dev: npm run dev

Three things matter here: the single-test command (Claude should never run your full suite for one file), typecheck (Claude should run this after every change), and your deployment scripts (Claude cannot guess them).

Failure 5 — Sprint context in a permanent file

# BAD — this gets forgotten when context rotates
## Current Sprint
- Working on payment flow redesign
- UserCard component is being deprecated
- Don't touch legacy auth module this sprint

CLAUDE.md loads every session. Sprint context belongs in dev-docs/current-sprint.md, loaded explicitly when needed.

CLAUDE.md is for permanent project truth. Current state goes in session-specific files.

What a production CLAUDE.md actually looks like

# Project: [Name]
[One sentence. What it does.]

## Commands
- Build: npm run build
- Test (single): npm run test -- --testPathPattern=
- Type check: npm run typecheck
- Lint: npm run lint:fix
- Dev: npm run dev

## Stack
- TypeScript strict mode
- React 18 hooks only — no class components
- Tailwind — no custom CSS unless unavoidable
- Zustand for state — see src/stores/

## Rules
- ES modules only — never require()
- Always handle errors explicitly — no silent catches
- Never use console.log; use src/utils/logger.ts instead
- No implicit any, no type assertions without explanatory comment

## Architecture
- API calls only through src/queries/ — never direct fetch in components
- Shared utilities in src/utils/
- Colocate tests with components

## What Claude gets wrong here
- Adds index.ts barrel exports — don't, breaks tree shaking
- Forgets typecheck after changes — always run npm run typecheck
- Uses default exports — always use named exports

Notice: no sprint info, no @file embeds, no prohibitions without alternatives, no style rules that don't affect correctness.

The 5-minute diagnostic

The Tinkleberry test
Add one line: Always address me as "Chief." Have a 10+ message session on a real task. If Claude stops using "Chief" mid-session, your file is too long and rules are being lost.

The direct question test
Ask Claude: "What are the rules in CLAUDE.md about error handling?" If Claude can't recite them accurately, they're too buried, too ambiguous, or too many.

The repeated mistake test
If Claude makes the same mistake twice despite a rule against it, that rule needs one of:

Shorter and clearer wording
An "instead, do this" alternative
To be a hook instead of a rule

CLAUDE.md vs hooks — the most important distinction

CLAUDE.md is advisory — Claude follows it ~80% of the time.
Hooks are deterministic — 100% every time.

// .claude/settings.json — things that MUST happen
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint:fix"
          }
        ]
      }
    ]
  }
}

If something must happen without exception — formatting, linting, security checks — make it a hook. CLAUDE.md is for guidance. Hooks are for guarantees.

The three-layer system

CLAUDE.md  → permanent project rules    (always loads, max 60 lines)
Skills     → domain knowledge           (loads on demand, no session cost)
Hooks      → non-negotiable actions     (deterministic, not advisory)

Most developers only use CLAUDE.md. The developers getting the best results from Claude Code use all three.

For hands-on labs building production CLAUDE.md hierarchies, slash command registries, and CI/CD integration with Claude Code — Cloud Edventures CCA-001 track, 22 labs, real AWS sandboxes.

Search: Cloud Edventures CCA-001

What does Claude keep ignoring in your CLAUDE.md? Drop a comment — I'll diagnose which failure pattern it is.

Why your RAG system fails in production — and the agentic loop fix

Aj — Tue, 24 Mar 2026 17:54:18 +0000

Your RAG demo worked perfectly. Then real users arrived and it started giving confidently wrong answers.

This is the most common production AI failure in 2026. And it's not a chunking problem or an embedding problem. It's an architectural one.

TL;DR

Standard RAG is a one-shot pipeline with no decision point between retrieval and generation
When retrieval is weak, the LLM hallucinates confidently using bad context
Agentic RAG adds a control loop: retrieve → evaluate → retry or proceed
The evaluation step is the entire value add — use a cheap fast model for it
2–4x token cost vs single-pass — worth it when wrong answers have real consequences

What standard RAG actually does

User query
    ↓
Embed → search vector DB → retrieve top-K chunks
    ↓
Inject chunks into LLM context
    ↓
Generate answer
    ↓
Return to user (no checkpoint, no second chance)

Works fine for simple direct questions. Breaks silently on ambiguous, multi-hop, or cross-source queries. The LLM has no way to signal "my context was bad" — it just generates something plausible-sounding and wrong.

The agentic RAG pattern

User query
    ↓
Agent decides which source to query
    ↓
Retrieve chunks
    ↓
┌─── DECISION POINT ──────────────────┐
│  Evaluate: is this sufficient?       │
│  → SUFFICIENT: generate answer       │
│  → RETRY: rewrite query, search again│
│  → ESCALATE: cannot answer reliably  │
└─────────────────────────────────────┘
    ↓
Generate grounded answer with citations

The decision point between retrieval and generation is the entire architectural difference. Something now asks "was this retrieval good enough?" before the LLM generates.

Complete implementation on AWS Bedrock

import boto3
import json

client = boto3.client("bedrock-runtime", region_name="us-east-1")

retrieval_tools = [
    {
        "toolSpec": {
            "name": "search_knowledge_base",
            "description": """Search the primary knowledge base for relevant information.
            Use this first for any factual question.
            Returns chunks with relevance scores.""",
            "inputSchema": {
                "json": {
                    "type": "object",
                    "properties": {
                        "query": {"type": "string"},
                        "max_results": {"type": "integer"}
                    },
                    "required": ["query"]
                }
            }
        }
    },
    {
        "toolSpec": {
            "name": "evaluate_retrieval_quality",
            "description": """Evaluate whether retrieved chunks are sufficient to answer the question.
            Use after every retrieval. Returns SUFFICIENT, RETRY, or ESCALATE.""",
            "inputSchema": {
                "json": {
                    "type": "object",
                    "properties": {
                        "original_query": {"type": "string"},
                        "retrieved_chunks": {"type": "string"}
                    },
                    "required": ["original_query", "retrieved_chunks"]
                }
            }
        }
    }
]

def search_knowledge_base(query: str, max_results: int = 3) -> dict:
    # Replace with your actual vector DB call (Pinecone, pgvector, Bedrock KB)
    return {
        "chunks": [
            {"text": f"Retrieved chunk for: {query}", "score": 0.87},
            {"text": f"Second chunk for: {query}", "score": 0.72}
        ]
    }

def evaluate_retrieval_quality(original_query: str, retrieved_chunks: str) -> dict:
    """
    Use a cheap fast model to evaluate — save expensive model for generation.
    This is the decision point that makes the loop work.
    """
    eval_prompt = f"""Evaluate if the retrieved content is sufficient to answer the question.

Question: {original_query}
Retrieved: {retrieved_chunks}

Respond with exactly: VERDICT|reasoning|suggested_query_if_retry
VERDICT must be: SUFFICIENT, RETRY, or ESCALATE"""

    response = client.converse(
        modelId="anthropic.claude-3-haiku-20240307-v1:0",  # Cheap model for evaluation
        messages=[{"role": "user", "content": [{"text": eval_prompt}]}]
    )
    result = response["output"]["message"]["content"][0]["text"]
    parts = result.split("|")
    return {
        "verdict": parts[0].strip(),
        "reasoning": parts[1].strip() if len(parts) > 1 else "",
        "suggested_query": parts[2].strip() if len(parts) > 2 else ""
    }

def tool_router(tool_name: str, tool_input: dict) -> str:
    if tool_name == "search_knowledge_base":
        return json.dumps(search_knowledge_base(
            tool_input["query"],
            tool_input.get("max_results", 3)
        ))
    elif tool_name == "evaluate_retrieval_quality":
        return json.dumps(evaluate_retrieval_quality(
            tool_input["original_query"],
            tool_input["retrieved_chunks"]
        ))
    return json.dumps({"error": f"Unknown tool: {tool_name}"})

def run_agentic_rag(user_query: str) -> str:
    system = """You are a precise Q&A agent.

Process:
1. Search knowledge base
2. Evaluate retrieval quality — ALWAYS do this before generating
3. RETRY if evaluation says so (max 3 retries)
4. ESCALATE if cannot find sufficient information
5. Generate grounded answer with citations only if SUFFICIENT

Never generate before evaluating. Cite sources in your answer."""

    messages = [{"role": "user", "content": [{"text": user_query}]}]

    for _ in range(8):  # Safety cap
        response = client.converse(
            modelId="anthropic.claude-3-sonnet-20240229-v1:0",
            system=[{"text": system}],
            messages=messages,
            toolConfig={"tools": retrieval_tools}
        )

        stop_reason = response["stopReason"]
        output = response["output"]["message"]
        messages.append(output)

        if stop_reason == "end_turn":
            return output["content"][0]["text"]

        if stop_reason == "tool_use":
            tool_results = []
            for block in output["content"]:
                if "toolUse" not in block:
                    continue
                tool = block["toolUse"]
                result = tool_router(tool["name"], tool["input"])
                tool_results.append({
                    "toolResult": {
                        "toolUseId": tool["toolUseId"],
                        "content": [{"text": result}]
                    }
                })
            messages.append({"role": "user", "content": tool_results})

    return "Max iterations — could not generate reliable answer"

print(run_agentic_rag(
    "How does our refund policy work for enterprise customers upgrading mid-cycle?"
))

Three things that make this work

The evaluation tool is the entire value add

evaluate_retrieval_quality uses Haiku (fast, cheap) to judge relevance before the main model generates. That decision point is where quality improvement comes from. Don't use your expensive model for this step.

Tool descriptions are your routing logic

Write them as instructions: "Use this first for any factual question" — not labels like "knowledge base search". The agent routes entirely based on these descriptions.

The system prompt is your quality contract

"Never generate before evaluating" is the single most important instruction. Without it the agent sometimes skips evaluation and hallucinates from bad context.

When to use each pattern

Pattern	Use when	Token cost
Standard RAG	Simple single-hop Q&A, latency-sensitive	1x
Agentic RAG	Ambiguous queries, multi-hop, quality matters	2–4x

Agentic RAG costs more per query. Worth it when wrong answers have real consequences. Overkill for simple doc lookups.

Production tips

Log every iteration. Which queries needed retries, and why, reveals exactly where your knowledge base has gaps.

Cap at 5–6 iterations. Queries needing more are usually unanswerable from your KB and should escalate instead of burning tokens.

Latency is now a distribution. Some queries resolve in one pass (fast). Some need three (slower). Monitor p95, not average.

For hands-on labs building a full RAG system with Bedrock Knowledge Bases in a real AWS sandbox — Cloud Edventures CCA-001 track, 22 labs, no AWS account needed.

Search: Cloud Edventures CCA-001

Where does your RAG system break down most in production? Drop a comment.

The coordinator-subagent pattern: the foundation every Claude multi-agent system is built on

Aj — Mon, 23 Mar 2026 12:49:43 +0000

Agent Teams landed in Claude Opus 4.6. Everyone's excited. But before you touch experimental features, understand the foundational pattern everything is built on.

TL;DR

Coordinator receives task, delegates to specialists via tool calls
Each subagent gets its own isolated context window and system prompt
Subagents cannot talk to each other — everything routes through coordinator
Same stopReason loop as single-agent, tool calls just dispatch to separate API calls
3–4x token cost vs single agent — only use when specialist quality justifies it

Pattern 1 — Coordinator-subagent (pure API)

The flow looks like this:

User Request
     ↓
Coordinator Agent  ←── stopReason: tool_use
     ↓
  Route to specialist
     ↓
┌──────────────────────────────────┐
│ research_agent │ writer_agent    │  ← Each: isolated context,
│ reviewer_agent │ any_specialist  │    own system prompt, own tools
└──────────────────────────────────┘
     ↓
Tool result back to coordinator
     ↓
stopReason: end_turn → return answer

Here's the full working implementation:

import boto3

client = boto3.client("bedrock-runtime", region_name="us-east-1")

subagent_tools = [
    {
        "toolSpec": {
            "name": "research_agent",
            "description": "Research specialist. Use for finding and analyzing information.",
            "inputSchema": {
                "json": {
                    "type": "object",
                    "properties": {"task": {"type": "string"}},
                    "required": ["task"]
                }
            }
        }
    },
    {
        "toolSpec": {
            "name": "writer_agent",
            "description": "Writing specialist. Always pass research as context.",
            "inputSchema": {
                "json": {
                    "type": "object",
                    "properties": {
                        "task": {"type": "string"},
                        "context": {"type": "string"}
                    },
                    "required": ["task", "context"]
                }
            }
        }
    }
]

def run_subagent(name: str, **kwargs) -> str:
    prompts = {
        "research_agent": "You are a research specialist. Be factual and concise.",
        "writer_agent": "You are a writing specialist. Use only facts from the context provided."
    }
    content = "\n".join(f"{k}: {v}" for k, v in kwargs.items())
    response = client.converse(
        modelId="anthropic.claude-3-sonnet-20240229-v1:0",
        system=[{"text": prompts[name]}],
        messages=[{"role": "user", "content": [{"text": content}]}]
    )
    return response["output"]["message"]["content"][0]["text"]

def run_coordinator(request: str) -> str:
    messages = [{"role": "user", "content": [{"text": request}]}]
    system = [{"text": "Coordinate specialists. Research first, then write."}]

    for _ in range(10):  # Safety cap
        response = client.converse(
            modelId="anthropic.claude-3-sonnet-20240229-v1:0",
            system=system,
            messages=messages,
            toolConfig={"tools": subagent_tools}
        )
        output = response["output"]["message"]
        messages.append(output)

        if response["stopReason"] == "end_turn":
            return output["content"][0]["text"]

        tool_results = []
        for block in output["content"]:
            if "toolUse" not in block:
                continue
            tool = block["toolUse"]
            if tool["name"] == "research_agent":
                result = run_subagent("research_agent", task=tool["input"]["task"])
            elif tool["name"] == "writer_agent":
                result = run_subagent("writer_agent", **tool["input"])
            tool_results.append({
                "toolResult": {
                    "toolUseId": tool["toolUseId"],
                    "content": [{"text": result}]
                }
            })
        messages.append({"role": "user", "content": tool_results})

    return "Safety cap reached"

print(run_coordinator("Write a post about why hands-on labs beat certifications alone"))

Pattern 2 — Claude Code subagents

Claude Code Session
      ↓
Main agent → Task tool → specialist-1  (isolated context)
           → Task tool → specialist-2  (isolated context)
           → Task tool → specialist-3  (isolated context)
      ↓
All report back to main agent only — no sideways talk
      ↓
Main agent synthesizes output

Same one-way reporting as Pattern 1, but running inside Claude Code via the Task tool. Use for local dev workflows — security reviews, test runs, documentation. Stable and production-ready today.

Pattern 3 — Agent Teams (experimental)

Team lead
   ↙         ↓         ↘
Researcher ⟺ Writer ⟺ Reviewer
   ↘         ↓         ↙
Team lead synthesizes

⟺ = direct peer-to-peer communication

The key difference: teammates message each other directly without going through the lead. Requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Known issues with session resumption and shutdown. Keep off production.

Three patterns compared

Pattern	Peer talk	Production	Token cost	Use when
Coordinator-subagent (API)	No	✅ Yes	3–4x	Production API agents
Claude Code subagents	No	✅ Yes	3–4x	Local dev workflows
Agent Teams	Yes	⚠️ Experimental	3–4x+	Peers need mid-task sharing

The critical mistake

Subagents share nothing. If your writer needs the research output, you must pass it explicitly.

# WRONG — writer has zero context
research = run_subagent("research_agent", task="research Lambda limits")
writer = run_subagent("writer_agent", task="write about Lambda")

# RIGHT — explicitly pass context through coordinator
research = run_subagent("research_agent", task="research Lambda limits")
writer = run_subagent("writer_agent", task="write about Lambda", context=research)

Isolation is the feature, not the bug. Design for it explicitly.

What comes next

Retry logic — coordinator decides whether to retry a failed subagent or escalate to a human
Parallel subagents — multiple tool calls in one response run simultaneously, cutting latency
Decision routing — confidence scores from one subagent pick the next specialist

Build it hands-on

For hands-on labs covering the full multi-agent coordinator pattern in real AWS Bedrock sandboxes — Cloud Edventures CCA-001 track, 22 labs, automated validation, no AWS account needed.

👉 cloudedventures.com/labs/track/claude-certified-architect-cca-001

Are you building production API agents or Claude Code workflows? Drop a comment.

Claude's agentic loop explained: stopReason, tool_use, and the pattern behind every AI agent

Aj — Fri, 20 Mar 2026 18:49:16 +0000

If you've tried building an AI agent with Claude and Bedrock, you've hit stopReason. Maybe you ignored it, maybe you cargo-culted the pattern from a tutorial. Either way — here's what's actually happening and why it matters for production systems.

TL;DR

stopReason: "tool_use" → execute the tool, append result, loop again
stopReason: "end_turn" → agent is done, return the response
Always append the assistant message before tool results
Never use text content checks as your stop condition

Why this pattern exists

Claude on Bedrock doesn't magically "know" to use tools. You have to implement the loop that lets it. The model's job is to reason about your task and signal what it needs — your code's job is to listen to that signal and respond correctly.

The signal is stopReason. Everything else follows from there.

The loop, step by step

1. Send message + tool definitions to Claude
2. Read stopReason from response
3a. If "tool_use"  → run the tool → append result → go to step 1
3b. If "end_turn"  → return the final response

That's it. Here's the full working implementation:

import boto3

client = boto3.client("bedrock-runtime", region_name="us-east-1")

# Define your tools
tools = [{
    "toolSpec": {
        "name": "get_order_status",
        "description": "Look up the status of a customer order by order ID",
        "inputSchema": {
            "json": {
                "type": "object",
                "properties": {
                    "order_id": {"type": "string"}
                },
                "required": ["order_id"]
            }
        }
    }
}]

def run_tool(tool_name, tool_input):
    if tool_name == "get_order_status":
        return {"status": "shipped", "eta": "2 days"}
    return {"error": "unknown tool"}

def run_agent(user_message):
    messages = [{"role": "user", "content": [{"text": user_message}]}]

    for _ in range(20):  # Safety cap — not your primary stop mechanism
        response = client.converse(
            modelId="anthropic.claude-3-sonnet-20240229-v1:0",
            messages=messages,
            toolConfig={"tools": tools}
        )

        stop_reason = response["stopReason"]
        output_message = response["output"]["message"]

        # Step 1: Always append Claude's response first
        messages.append(output_message)

        # Step 2: Check stopReason — not content type
        if stop_reason == "end_turn":
            for block in output_message["content"]:
                if "text" in block:
                    return block["text"]

        elif stop_reason == "tool_use":
            tool_results = []
            for block in output_message["content"]:
                if "toolUse" in block:
                    tool = block["toolUse"]
                    result = run_tool(tool["name"], tool["input"])
                    tool_results.append({
                        "toolResult": {
                            "toolUseId": tool["toolUseId"],
                            "content": [{"json": result}]
                        }
                    })

            # Step 3: Append tool results and loop
            messages.append({"role": "user", "content": tool_results})

    return "Safety cap reached"

print(run_agent("What's the status of order ORD-12345?"))

The three bugs that will waste your afternoon

Bug 1 — Missing assistant message append

# What most tutorials show (broken)
messages.append(tool_results_message)

# What you actually need
messages.append(output_message)       # Claude's response FIRST
messages.append(tool_results_message) # Then your tool results

Claude needs to see its own previous response to connect tool results back to the tool call it made. Skip this and you'll get confused responses or infinite loops.

Bug 2 — Content type check as stop condition

# Breaks silently on complex tasks
if response["output"]["message"]["content"][0]["type"] == "text":
    return response  # WRONG

# Correct
if response["stopReason"] == "end_turn":
    return response  # RIGHT

Claude can return {"type": "text", ...} blocks alongside tool_use blocks. A message like "I'll look that up now" followed by a tool call has text in position [0] — your agent terminates before the tool ever runs.

Bug 3 — Iteration cap as primary stop

# This is a safety net, not a strategy
for i in range(10):
    if i == 9:
        break  # Wrong use of cap

Caps prevent runaway agents. They don't signal completion. A task that genuinely needs 12 iterations gets cut off at 10. A task that finishes in 3 wastes 7 loops. The model signals completion via stopReason — listen to it.

Where this goes next

Master the core loop and these patterns become straightforward:

Multi-step tool sequencing — Claude chains multiple tool calls across iterations, reasoning about each result before deciding the next action.

Multi-agent systems — coordinator agents treat subagents as tools. Same tool_use / end_turn cycle, one level up.

Human escalation — on low-confidence results, append a special toolResult that prompts Claude to request human input instead of proceeding.

Error propagation — structured error responses in tool results let Claude decide whether to retry, use a fallback tool, or surface the failure cleanly.

Want to build this in a real AWS Bedrock sandbox?

This is Mission 1 of the CCA-001: Claude Certified Architect track — 22 labs covering agentic loops, MCP servers, multi-agent systems, Bedrock Guardrails, CI/CD with Claude Code, and observability dashboards. Real AWS sandbox, automated validation, no account setup needed.

👉 cloudedventures.com/labs/bedrock-agentic-loop-stopreason

Also join r/ClaudeCertifications on Reddit — building a community for Claude and Bedrock practitioners.

Drop a comment if anything's unclear — what part of the loop trips you up most?

Claude Certified Architect (CCA-001): The First Hands-On AI Certification That Actually Matters

Aj — Thu, 19 Mar 2026 20:19:57 +0000

There's a new certification making waves in the AI engineering space, and it's not from AWS, Google, or Microsoft.

The Claude Certified Architect (CCA-001) is the first certification focused entirely on building production-grade AI systems with Anthropic's Claude — and unlike most AI certifications, it's 100% hands-on. No multiple choice. No memorizing API parameters. You either build working agentic systems or you don't pass.

Here's why that matters, and why AI engineers should pay attention.

The AI Certification Problem

Let's be real: most AI certifications are glorified reading comprehension tests. You memorize which model has which context window, learn the difference between fine-tuning and RAG, and select the right answer from four options.

Then you get to an actual job and realize none of that prepared you to build a multi-agent system that handles failures gracefully, or to design tool-calling patterns that don't hallucinate, or to implement guardrails that actually work in production.

The gap between "I know what agentic AI is" and "I can build reliable agentic AI systems" is enormous. That's the gap CCA-001 is designed to close.

What CCA-001 Actually Covers

The certification spans 5 domains, 22 hands-on missions, and roughly 40 hours of work in real AWS Bedrock sandbox environments. Here's what you're building:

Domain 1: Agentic Architecture

This isn't theory. You're designing and deploying complete agentic systems — agents that can reason, use tools, and maintain context across complex multi-step tasks. You learn how to structure CLAUDE.md hierarchies, build plan-execute pipelines, and handle the messy reality of agents that don't always do what you expect.

Domain 2: Tool Design & Integration

Every useful AI agent needs tools. You'll build custom tool schemas, implement function calling patterns, and learn why most tool designs fail in production (hint: it's usually the schema descriptions, not the code).

Domain 3: Prompt Engineering at Scale

Not "write a better prompt" basics. This covers system prompt architecture for complex applications, dynamic prompt composition, and the engineering patterns that make prompts maintainable across a team — not just one developer's magic strings.

Domain 4: Reliability & Guardrails

The domain that separates demo projects from production systems. You'll implement retry strategies, circuit breakers, output validation, content filtering, and the observability patterns you need to trust an AI system with real users.

Domain 5: Multi-Agent Systems

The most advanced domain. Building systems where multiple AI agents coordinate, share context, handle handoffs, and recover from failures. This is where most teams struggle, and it's where the certification gets genuinely hard.

Why Employers Care About This

Three trends are converging that make CCA-001 uniquely valuable right now:

1. Claude is dominating the enterprise AI stack. Anthropic's models are increasingly the default choice for companies building AI applications. AWS Bedrock makes Claude accessible at enterprise scale, and companies need engineers who know how to build with it.

2. "AI Engineer" is the fastest-growing role. Every job board shows it — companies are hiring specifically for people who can build AI-powered applications, not just data scientists who train models. CCA-001 maps directly to what these roles require.

3. Agentic AI is the current frontier. The shift from simple chatbots to autonomous agents that can reason, use tools, and complete complex tasks is happening now. Most engineers are still figuring out the basics. A certification that proves you can build reliable agentic systems is a genuine differentiator.

The Hands-On Difference

Here's what makes CCA-001 fundamentally different from other certifications:

Every mission runs in a real AWS Bedrock sandbox. You're not answering questions about Bedrock — you're deploying actual agents, calling real Claude APIs, and building infrastructure that gets automatically validated.

Automated validation checks your work. You can't fake it. The system verifies that your agent actually works, your tools return correct responses, your guardrails catch what they should, and your multi-agent system handles failures properly.

You build a verified portfolio. Every completed mission becomes a portfolio piece with proof of completion. When you tell an interviewer "I built a multi-agent system with tool calling and guardrails," you can show them the verified project, not just talk about it.

Who Should Get Certified

CCA-001 makes the most sense if you're:

A backend or full-stack engineer adding AI capabilities to your skill set
A cloud engineer who wants to specialize in AI infrastructure
An AI/ML engineer who works with LLMs and wants formal proof of agentic architecture skills
A solutions architect designing AI systems for enterprise clients
A career changer targeting the AI engineering role specifically

If you're still learning basic cloud concepts, get comfortable with AWS first (the Cloud Explorer and Automation Captain paths are good starting points), then come back to CCA-001.

How to Prepare

The certification is designed to be self-contained — each mission builds on the previous one. But you'll get more out of it if you have:

Basic AWS experience (Lambda, API Gateway, IAM)
Familiarity with at least one programming language (Python recommended)
General understanding of what LLMs are and how they work

You don't need prior experience with Claude specifically or with building AI agents. The certification teaches those skills through the missions.

The 22-Mission Path

The missions follow a progressive structure:

Navigator's Compass (4 missions) — Start with CLAUDE.md configuration, slash commands, plan-execute pipelines, and CI/CD integration for AI systems.

Then you work through each domain with increasingly complex projects, culminating in multi-agent orchestration systems that mirror what companies are actually building in production.

Each mission takes between 60-120 minutes, and you're working in isolated Bedrock sandboxes the entire time. No risk of runaway API costs, no configuration headaches — just building.

The Bottom Line

The AI job market in 2026 is flooded with people who "know about" AI. What's scarce is engineers who can prove they've built reliable, production-grade AI systems.

CCA-001 is the first certification I've seen that actually tests this. It's not easy — 40 hours of hands-on work is a real commitment. But that difficulty is exactly what makes it valuable. A certification that's hard to get is a certification worth having.

If you're serious about AI engineering, this is worth your time.

I built Cloud Edventures specifically to provide hands-on sandbox environments for certifications like this. The CCA-001 path gives you all 22 missions with real Bedrock sandboxes and automated validation. You can start the Claude Architect path here.

Already working on AI certifications? What's your experience been? I'd love to hear in the comments.

Forem: Aj

AWS EBS explained: volume types, snapshots, and when NOT to use it

What AWS EBS actually is

EBS volume types: which one do you actually need?

gp3 — General Purpose SSD (the default, and usually the right choice)

gp2 — General Purpose SSD (legacy, stop using this)

io2 Block Express — Provisioned IOPS SSD (when you need extreme performance)

io1 — Provisioned IOPS SSD (legacy io2, skip this)

st1 — Throughput Optimized HDD (big sequential reads)

sc1 — Cold HDD (infrequently accessed archives)

The decision framework

EBS vs EFS vs S3: choosing the right storage

Snapshots: what they are and how to not forget them

EBS encryption with KMS

EBS cost optimization: where teams overpay

EC2 instance store vs EBS: the critical difference

Frequently asked questions

Practice this in a real AWS environment

I built an MCP server on AWS Bedrock in 30 minutes. Here's the exact code.

What MCP Actually Is (In One Paragraph)

What We're Building

Step 1 — Install the MCP SDK

Step 2 — Build the MCP Server

Step 3 — Test Locally With Claude Code

Step 4 — Deploy to Bedrock AgentCore Runtime

Step 5 — Connect to a Bedrock Agent

The Three Things That Break MCP in Production

Stateful MCP: AWS's New Feature (March 2026)

What to Build Next

Claude Code Power User Guide: /ghost, OODA, L99, KAIROS and Every Hidden Feature From the Source Code Leak

What Got Leaked (Quick Summary)

1. The Prompt Frameworks

/ghost — Kill the AI Voice

OODA — Force a Decision

L99 — Expert Depth

SCAFFOLD — Full Project Setup

PERSONA — Domain Expert Mode

2. System Prompt Insights You Can Exploit

Be Terse

Parallel Execution

The Bash Tool is King

3. CLAUDE.md — Your Project's AI Memory

4. Unreleased Features (From the Leak)

KAIROS — Background Agent Mode

BUDDY — AI Coding Companion

Voice Mode

ULTRAPLAN

Undercover Mode

5. My Daily Workflow

Hands-On Practice

What's Your Power-User Trick?

Why creating an AWS account is harder than it should be — especially in India

What AWS Requires Globally

1. A unique email address

2. A valid payment method

3. Phone verification

4. Account activation (up to 24 hours)

The India-Specific Layer: AISPL + KYC Documents

What is AISPL?

KYC Document Verification in India

The PAN Card + Aadhaar Linkage (Important from 2025)

RBI Payment Regulations Affecting AISPL Accounts

The Billing Anxiety Problem (India-Specific Too)

Three Options for Hands-On Practice

India AWS Account Checklist

Cloud engineer in 2026: the honest roadmap that actually gets you hired

What the job actually requires

The real skill stack (in priority order)

1. Linux fundamentals — do not skip this

2. Networking basics

3. Core AWS services — hands-on, not watched

4. Infrastructure as Code

5. CI/CD pipelines

The certification question (honest answer)

The three portfolio projects that get interviews

The practice problem nobody talks about

The timeline that works

The one thing that separates hires from rejections

AWS Bedrock in 2026: what it actually is and how to build your first AI agent on it

What AWS Bedrock actually is

`/ghost` — Kill the AI Voice

`OODA` — Force a Decision

`L99` — Expert Depth

`SCAFFOLD` — Full Project Setup

`PERSONA` — Domain Expert Mode