---
id: "action-define-rules-of-engagement"
type: "action-item"
source_timestamps: ["00:12:12", "00:12:38"]
tags: ["api-design"]
related: ["concept-semantic-context", "concept-context-engineering", "framework-dark-code-solution"]
speakers: ["Nate B. Jones"]
action: "Embed performance expectations, failure modes, and behavioral contracts directly into code interfaces."
outcome: "Ensures AI agents generate code that respects production realities, not just code that compiles."
sources: ["s23-amazon-16k-engineers"]
sourceVaultSlug: "s23-amazon-16k-engineers"
originDay: 23
---
# Define Semantic Rules of Engagement

## Action

Go beyond data-shape definitions. Embed the **rules of engagement** directly into every code interface:

- **Performance expectations** — latency budgets, throughput limits
- **Failure modes** — what errors are possible, how they must be raised
- **Retry semantics** — idempotency guarantees, backoff requirements
- **Behavioral contracts** — invariants the code must uphold

## Outcome

AI agents reading the interface understand not just *what* data is exchanged but *how* the code must behave operationally. Result: generated code respects production realities instead of merely compiling.

## How To Encode

This is conceptually similar to API contracts (e.g., OpenAPI extensions, gRPC deadlines) but applied universally — every interface in the codebase, not just public APIs. Implementations can use:

- Decorators / annotations carrying metadata
- Sidecar contract files parseable by AI agents
- Inline machine-readable comments tied to interface declarations

## Connects To Concept

This operationalizes [[concept-semantic-context]] — paired with [[concept-structural-context]] (operationalized in [[action-create-module-manifests]]) to form [[concept-context-engineering-d23]].

Layer 2 of [[framework-dark-code-solution]].