---
id: "concept-semantic-context"
type: "concept"
source_timestamps: ["00:12:12", "00:12:20"]
tags: ["software-architecture", "api-design"]
related: ["concept-context-engineering", "action-define-rules-of-engagement"]
definition: "Embedded rules of engagement within code interfaces that dictate performance expectations, failure modes, and behavioral contracts to AI agents."
sources: ["s23-amazon-16k-engineers"]
sourceVaultSlug: "s23-amazon-16k-engineers"
originDay: 23
---
# Semantic Context

## Definition

**Semantic Context** is the set of embedded rules of engagement within code interfaces that dictate performance expectations, failure modes, and behavioral contracts to AI agents.

## What It Goes Beyond

Traditional interface definitions describe the *shape* of data — types, fields, return values. Semantic context describes the *behavior* and *operational realities*:

- **Performance expectations** — latency budgets, throughput targets
- **Failure modes** — what errors are possible and how they must be raised
- **Retry semantics** — idempotency guarantees, backoff requirements
- **Behavioral contracts** — invariants the code must uphold (e.g., 'never block on the main thread', 'always emit audit log on write')

## Why AI Needs This

An AI that reads only data shapes will write code that *compiles* but does not respect production realities. It may:

- Add a synchronous network call inside a hot loop
- Skip retry logic on transient failures
- Violate idempotency assumptions of an upstream service

With semantic context embedded directly in the interface, the AI's generated code is bounded by behavioral law, not just type law.

## Pattern Reference

This is conceptually similar to API contracts (e.g., OpenAPI's `x-ratelimit-*` extensions, gRPC deadlines) but applied universally — every interface, not just public APIs.

## Relationship to [[concept-context-engineering-d23]]

Semantic context is the second pillar of context engineering. Paired with [[concept-structural-context]], the two together produce a self-describing codebase that suppresses [[concept-dark-code]] at generation time.

## Operationalization

See [[action-define-rules-of-engagement]].