Skip to content

PATTERN Cited by 1 source

Local-emulation-first

Pattern

Prefer a local emulator over a cloud deployment as the default feedback path for every proposed code change. Escalate to cloud resources only when the change is one the local tier structurally cannot validate (cold start, IAM policy, scale behavior, cross- service race).

Canonical statement from the 2026-03-26 AWS Architecture Blog post:

"Whenever possible, your architecture should allow AI agents to test changes locally before touching cloud resources."

Why

  • Iteration latency collapses. Seconds (local) vs minutes (cloud deploy + log-tail) per validation.
  • Cost collapses. No billed capacity on throwaway iterations.
  • Cloud-quota pressure drops. Agents often iterate dozens of times per successful change; keeping that loop local avoids burning Lambda / deploy / pipeline quotas.
  • Credentials stay off the inner loop. Local emulation doesn't need IAM, which means a compromised agent can't exfiltrate via a ten-iteration-test-cycle.

Canonical realizations (named in the 2026-03-26 post)

Workload shape Local emulator Cloud target
Serverless API systems/aws-sam sam local start-api systems/aws-lambda + systems/amazon-api-gateway
Container service docker run <same-image> systems/amazon-ecs / systems/aws-fargate
Key-value data systems/dynamodb-local systems/dynamodb
Data pipeline systems/aws-glue Docker image with ETL libs + sample data systems/aws-glue cloud job

"An AI agent can invoke Lambda functions through a locally emulated API Gateway, observe responses immediately, and iterate in seconds rather than minutes."

"Containers offer similar benefits for services that run on Amazon Elastic Container Service (Amazon ECS) or AWS Fargate. By building and running the same container images locally, an agent can validate application behavior before deploying to the cloud."

"For data persistence, Amazon DynamoDB Local allows the agent to test create, read, update, and delete (CRUD) operations against a local database that mirrors the DynamoDB API."

Where local emulation falls short (escalation criteria)

  • IAM / resource-policy correctness — emulators don't enforce IAM; only real cloud smoke tests will.
  • Regional / latency behavior — only real deployments.
  • Scale / throughput — local is a correctness oracle, not a perf model.
  • Cross-service coordination under real retry + clock skew — race conditions that only appear with real queues / real clocks.

These are what push to the next tiers: patterns/hybrid-cloud-testing (for services without emulators) and patterns/ephemeral-preview-environments (for end-to-end validation).

Enabling codebase shape

Local-emulation-first works because the application code is hexagonal (concepts/hexagonal-architecture): the domain layer has no Amazon dependencies, so unit tests run without any emulator, and the infrastructure-adapter layer can swap a local emulator in for the production SDK via config alone.

Caveats

  • Drift between emulator and real service is real. DynamoDB Local, SAM Local, Glue Docker all have known semantic gaps against their cloud counterparts. See systems/dropbox-nucleus Heirloom (~100× slowdown) for a candid articulation of mock-suite drift cost.
  • Doesn't substitute for smoke tests in the real cloud. The 2026-03-26 post explicitly keeps the smoke-test tier to catch "configuration or permission issues that only appear at runtime."

Seen in

Last updated · 200 distilled / 1,178 read