ORACE — A Practical Architecture Framework for Engineers and AI Agents

Most architecture documentation fails in one of two ways. Either it does not exist — the team is moving fast and nobody writes anything down — or it exists but is wrong, because the diagram was drawn once at the start of the project and has not been touched since.

Both failures have the same consequence: when a new engineer joins, when a system needs to change, or when an AI coding agent needs to understand what it is working with, there is nothing reliable to hand them. They reverse-engineer the code instead. They make assumptions. They optimize for the wrong things. They break constraints nobody told them about.

ORACE is a five-question framework designed to fix this. It gives architects and engineers a structured way to document a system's architecture — not as a picture of the technology, but as a traceable chain from business outcomes to production evidence. The resulting artifact set is equally readable by a new engineer, a compliance officer, and an AI coding agent.

This article explains the framework, walks through it with a concrete example, and shows how to automate it with a Claude skill so your team can generate the full artifact set in a single session.

ORACE in One Minute

ORACE is an acronym. Each letter is a question that must be answerable for any system you build.

Letter	Question	Output artifact
O — Outcomes	What valuable outcomes must this system deliver, and which business failures must it prevent?	`outcomes.md`
R — Requirements	Which requirements are architecturally significant? Which quality attributes, with measurable scenarios?	`requirements.md`, `quality-scenarios.md`
A — Architectural Approaches	Which tactics, patterns, and interfaces address each scenario? What are the trade-offs?	`approaches.md`, `decisions/NNN-*.md`
C — Communication	Which views does each stakeholder need?	`views/context.md`, `views/module.md`, `views/runtime.md`, `views/deployment.md`
E — Evidence & Evolution	Which tests and production metrics prove the architecture works? What must evolve when evidence is insufficient?	`evidence/evidence-plan.md`, `evolution/backlog.md`

The framework reads as a cycle:

Business Outcomes
    ↓
Quality-Attribute Scenarios  (measurable requirements)
    ↓
Architectural Approaches     (tactics + decisions)
    ↓
Communication Views          (context, module, runtime, deployment)
    ↓
Evidence & Evolution         (tests + production metrics + evolution backlog)
    ↺
(revisit the right phase when evidence fails)

Everything flows from the top. A technology decision that cannot be traced back to a quality-attribute scenario, and a scenario that cannot be traced back to a business outcome, is floating. Floating decisions are how complexity accumulates without purpose.

O — Outcomes: Start with Business Risk, Not Technology

The most common mistake in architecture is starting with the technology. Teams ask: should we use microservices or a monolith? Kafka or RabbitMQ? REST or gRPC? These are the wrong first questions. The right first question is: what happens if this system fails?

Outcomes are the valuable results the system must deliver and the business failures it cannot allow. They come from conversations with stakeholders — not just engineering leadership, but also product owners, compliance officers, and operations teams.

For a payment API, the outcomes might look like this:

Business Outcome	Failure to Prevent
Process instant payments with sub-second confirmation	A payment with no definitive outcome creates a customer dispute and a potential double-spend
Screen every payment against sanctions lists before execution	A sanctions miss is a regulatory breach with fine exposure
Allow new sanctions providers to be onboarded without platform changes	Vendor lock-in means a three-month project every time regulators require a provider switch

Notice what is NOT in this table: no mention of microservices, no mention of Kafka, no mention of the cloud provider. The outcomes are about what the business needs to stay solvent, legally compliant, and trusted by its customers.

What to capture in outcomes.md: system name and purpose, stakeholder list with their primary concerns, 2–3 business outcomes, top 2–3 failure risks, regulatory constraints, and external dependencies classified as critical or non-critical.

R — Requirements: Turn Vague Attributes into Testable Scenarios

"The system must be fast, secure, and highly available."

Every engineer has written or read this sentence. And everyone knows it is useless. It does not tell you what to build. It does not tell you what to test. It does not tell you when you have succeeded.

Quality attributes become requirements only when they are attached to a scenario: a specific event, a specific context, a specific response, and a measurable outcome. The six-field scenario template is the tool for this.

Field	What it captures
Source	Who or what generates the trigger
Stimulus	The specific event or condition
Environment	Operating conditions (load, time of day, degraded mode)
Artifact	The specific component that must respond
Response	What the system should do
Measure	How you know the response was adequate — must include a number

Here is the same payment API's availability requirement, written as a scenario instead of a wish:

Field	Value
Source	Cloud infrastructure
Stimulus	The sanctions screening service becomes unreachable
Environment	Peak volume at 3,000 TPS
Artifact	Payment Orchestration service
Response	Route in-flight payments to a safe pending state; do not confirm or reject until screening recovers
Measure	Failure detected ≤ 5 seconds. Recovery ≤ 30 seconds. Zero transactions permanently lost.

The Measure field is the discipline check. If you cannot write a number in it, you are not finished. "Recovers quickly" is not a measure. "Recovers in ≤ 30 seconds" is a measure — you can write a chaos test for it.

A well-run system needs 3–6 scenarios covering the quality attributes that flow from the failure risks in your Outcomes. The most common attributes for backend systems in regulated environments are availability, performance, modifiability, and auditability.

What to capture in quality-scenarios.md: one scenario table per quality attribute, with all six fields completed and numbers in every Measure entry.

A — Approaches: Decisions That Outlast the Team

Once you have measurable scenarios, the Approaches phase asks: what architectural decisions make each scenario achievable?

The output is a set of Architecture Decision Records — ADRs. Each ADR documents one key decision in four fields:

Context: what situation forced the decision, and what forces are in tension
Alternatives: the options considered, with their benefits and costs
Decision: what was chosen, and what was explicitly NOT chosen
Consequences: what becomes easier, what becomes harder, what risk is now accepted

Here is an ADR for the payment API's availability scenario:

ADR-001: Use circuit breaker with dead-letter queue for screening outages

Status: Accepted

Context: The payment orchestrator depends on the sanctions screening service synchronously. If screening becomes unavailable, the orchestrator needs to degrade gracefully without losing transactions or confirming unscreened payments.

Alternatives considered:

Option	Benefit	Cost
Fail-fast (reject payments when screening is down)	Simple, no queue complexity	Customer-visible failures during outages; SLA breach
Pass-through (confirm payments without screening during outage)	Zero customer impact	Compliance breach — sanctioned payments may be approved
Circuit breaker + DLQ (route to pending, resume on recovery)	Zero data loss; no compliance breach	Queue complexity; recovery processing logic

Decision: circuit breaker with DLQ. Payments are routed to a pending state during outage and processed in order on recovery. We do NOT pass through unscreened payments under any condition.

Consequences:
- Easier: outages are transparent to customers; no regulatory exposure during degraded mode.
- Harder: the DLQ needs its own monitoring, ordering guarantees, and poison-message handling.
- Risk accepted: customers may see a payment in "pending" state for up to 30 seconds post-recovery. This is disclosed in the product SLA.

The ADR is six sentences per section. That is enough. The goal is not a design document — it is a decision log. When a developer reads this two years later and asks "why do we have a dead-letter queue here?", this ADR answers the question without requiring anyone to reconstruct a meeting from memory.

The trade-off discipline: every ADR should name what becomes harder. If your Consequences section only lists benefits, you have not finished writing it. Architecture trade-offs are real; the job is to make them visible, not to pretend they do not exist.

What to capture in decisions/: one file per key decision, numbered sequentially (001-circuit-breaker-dlq.md, 002-event-sourcing-audit-log.md). Aim for the 2–4 decisions that are most costly to reverse.

C — Communication: Three Views for Three Audiences

The same architecture looks different depending on who is reading it. A developer needs to know what their component is responsible for. An on-call engineer needs to know how components communicate at runtime and what breaks when a dependency goes down. A compliance officer needs to know where data lives and who can access it.

Three views, each in its own file:

Module view (views/module.md) — responsibilities and ownership. Lists each major component, its single responsibility, its owner, and what it depends on. Answers: who is responsible for what?

Runtime view (views/runtime.md) — communication patterns. Sequence diagrams or step-by-step flow descriptions for the 1–3 most critical flows. Marks each call as synchronous or asynchronous. Notes timeouts, retries, and failure behaviours. Answers: how does the system behave while it runs?

Deployment view (views/deployment.md) — infrastructure, trust zones, and data residency. Maps each component to its runtime environment and network zone. Specifies what can communicate with what and where sensitive data is and is not permitted to go. For systems with AI components, it defines the AI control boundary explicitly: what the model can read, what it can propose, what it can never execute directly.

The deployment view is the most neglected of the three. It is also the one where the most expensive security and compliance mistakes are made.

E — Evidence & Evolution: Proving It Works in Production

An architecture diagram is a hypothesis. The E phase defines how you prove the hypothesis — not once at launch, but continuously in production. And when evidence fails, it guides Evolution: directing the team back to the correct level of change.

For each quality-attribute scenario, the evidence plan names a production metric:

Metric	Proves	Target	Alert at
Duplicate posting count	Idempotency of payment state machine	Zero	Any non-zero
p99 end-to-end payment latency	Performance scenario	≤ 500ms	> 400ms
Circuit breaker open rate	Dependency health	Near zero, stable	Rising trend over 24h
DLQ depth at 30s post-recovery	Availability recovery scenario	Zero	Any non-zero

Two principles for a good evidence plan:

Alert thresholds are not targets. The target is the number from the scenario's Measure field. The alert threshold is the warning level — the value at which you investigate before you breach the target.

Absence of alerts is not evidence. A system with no alerts may have no alerts because everything is fine, or because the alerts are wrong. A chaos test that kills a dependency and verifies the recovery metric within 30 seconds is stronger evidence than 90 days of silence.

How Evidence drives Evolution: when evidence fails, it directs the team to the correct level of change — not just back to Outcomes every time:

Situation	Revisit
Implementation doesn't match the approved approach	Communication artifacts or implementation
Technology/tactic cannot meet the requirement	Architectural Approaches
Requirement is incomplete, contradictory, or unmeasurable	Requirements
Business priority, regulation, or risk appetite changes	Outcomes

For systems with AI components, the evidence plan should include governance signals: the human override rate on AI proposals (healthy range: 5–25%, stable), the AI grounded-claim rate (≥ 95% of recommendations should include a traceable evidence reference), and the count of unauthorized capability attempts (target: zero).

Using the ORACE Claude Skill

The ORACE framework is available as a Claude Code skill. The skill conducts the interview for you — asking the right questions for each phase, probing for missing numbers in Measure fields, and writing the output files immediately after each phase completes.

Installation

The skill lives in this GitHub repository: github.com/dariopalladino/orace-skill

Clone it into your Claude skills directory:

git clone https://github.com/dariopalladino/orace-skill/skills ~/.claude/skills/

Alternatively, copy the SKILL.md file directly:

mkdir -p ~/.claude/skills/orace-workshop
curl -o ~/.claude/skills/orace-workshop/SKILL.md \
  https://raw.githubusercontent.com/dariopalladino/orace-skill/main/skills/orace-workshop/SKILL.md

mkdir -p ~/.claude/skills/orace-adr
curl -o ~/.claude/skills/orace-adr/SKILL.md \
  https://raw.githubusercontent.com/dariopalladino/orace-skill/main/skills/orace-adr/SKILL.md

# orace-workshop
- **orace-workshop** - full ORACE architecture interview. Trigger: `/orace-workshop`
When the user types `/orace-workshop`, invoke the Skill tool with `skill: "orace-workshop"`.

# orace-adr
- **orace-adr** - single ADR interview. Trigger: `/orace-adr`
When the user types `/orace-adr`, invoke the Skill tool with `skill: "orace-adr"`.

Running the full workshop

Navigate to your project root and run:

/orace-workshop

The skill will create an ./architecture/ folder and run the interview phase by phase. Each phase completes with a file written to disk before the next phase begins.

If you have already run the workshop and want to resume from where you left off — after a break, or after filling in a phase manually — the skill detects which output files already exist and skips the completed phases:

ORACE Workshop — resume check
──────────────────────────────
[O] Outcomes      → outcomes.md              ✓ done
[R] Requirements  → quality-scenarios.md     ✓ done
[A] Approaches    → decisions/ (2 files)     ✓ done
[C] Communication → views/                   ✗ missing
[E] Evidence      → evidence-plan.md         ✗ missing
──────────────────────────────
Resuming from Phase C.

To write the artifacts to a custom path:

/orace-workshop ./docs/architecture

To document a single decision mid-sprint without running the full workshop:

/orace-adr

The ADR skill reads your existing quality-scenarios.md for context, determines the next sequence number from the decisions/ folder, and runs a focused 7-question interview. After writing the ADR, it offers to append the accepted risk to the risk register.

Bootstrapping a Project with a Coding Agent

Once the artifact set is complete, it becomes the input layer for an AI coding agent. The artifacts answer the questions that an agent would otherwise have to guess at, and that guessing — about naming conventions, about what failure modes to handle, about which quality attributes matter — is where AI-generated code most commonly drifts from what the team actually needs.

The artifact set as system context

When starting a new coding session with Claude Code (or any agent that accepts file context), include the ORACE artifacts in the context window in this order:

outcomes.md                   ← system purpose, stakeholders, constraints
quality-scenarios.md          ← what the system must prove it can do
views/module.md               ← component boundaries and ownership
views/deployment.md           ← trust zones, AI control boundary
decisions/001-*.md            ← why key decisions were made
decisions/002-*.md
evidence/evidence-plan.md     ← what tests and metrics to produce

A useful opening prompt for the agent:

Read the architecture artifacts in ./architecture/ before writing any code.

Your implementation must:
1. Satisfy the quality-attribute scenarios in quality-scenarios.md, not as aspirations, but as testable constraints. Write tests for the Measure field of each scenario.
2. Respect the component boundaries in views/module.md. Do not add responsibilities to a component that is not defined as its owner.
3. Respect the trust zones in views/deployment.md. Do not create a write-capable path from an AI component to an execution boundary.
4. Follow the decisions in decisions/. When a decision is relevant, do not re-litigate it, implement it. When a new decision is needed, flag it rather than choosing silently.
5. Produce evidence artefacts as described in evidence/evidence-plan.md: tests named after the scenarios they validate, metrics instrumentation where specified.

What the agent can do with the artifacts

With this context loaded, a coding agent can work at a meaningfully higher level than it can from a blank prompt or a README:

Task	Without ORACE artifacts	With ORACE artifacts
Scaffold a component	Generic structure, unknown ownership	Correct responsibilities per `module.md`, named after the canonical component
Write availability tests	Generic health check, unknown thresholds	Chaos tests targeting the specific Measure fields from `quality-scenarios.md`
Implement a provider integration	Hard-coded provider, no abstraction	Provider-neutral interface per the relevant ADR
Set up monitoring	Generic latency metrics	Exact metric names, targets, and alert thresholds from `evidence-plan.md`
Handle a failure mode	May not handle it	Implements the Response field from the relevant quality-attribute scenario
Propose a new architectural decision	May choose silently	Flags the decision and asks before implementing

The last row is the most important. An agent that has read the ADRs knows that certain decisions were deliberate. When it encounters a situation where a new decision is needed — a new external dependency, a new failure mode, a new quality attribute — it can flag it rather than choosing silently and embedding an invisible assumption in the codebase.

Incremental use: ADRs mid-sprint

ORACE is not a one-time exercise. As the project evolves, new architectural decisions emerge. The /orace-adr skill is designed for this workflow: run it whenever a significant decision is made, and the decision folder grows incrementally alongside the code.

A team that runs /orace-adr consistently throughout a project ends up with an audit trail of how the system evolved — not just what it does today, but why each significant choice was made, what was rejected, and what risk was accepted. That audit trail is as valuable for onboarding new engineers as it is for feeding context to an AI agent six months from now.

Quick Reference Card

The five questions

Letter	Question	If you cannot answer it...
O	What must this system achieve, and what happens if it fails?	You are building without a purpose
R	For each risk, what is the measurable quality-attribute scenario?	Your requirements are aspirations
A	For each scenario, which tactics address it, and what are the trade-offs?	Your decisions are invisible
C	Which view does each stakeholder need to see?	Your communication has gaps
E	Which metrics prove the architecture is working right now? What evolves when they fail?	Your architecture is a hypothesis

The six-field scenario template

Source      → who or what triggers it
Stimulus    → what specifically happens
Environment → under what operating conditions
Artifact    → which component must respond
Response    → what the system does
Measure     → how you know it worked — must include a number

The four-field ADR

Context      → what situation forced this decision
Alternatives → what options were considered, with costs
Decision     → what was chosen and what was NOT chosen
Consequences → easier / harder / risk accepted + owner

Skill commands

/orace-workshop              # full ORACE interview → ./architecture/
/orace-workshop <path>       # write artifacts to a specific folder
/orace-workshop --reset      # start over, ignoring existing files
/orace-adr                   # document one decision → ./architecture/decisions/
/orace-adr <path>            # use a specific architecture folder

Artifact folder structure

architecture/
  outcomes.md                O — system purpose, stakeholders, risks, constraints
  quality-scenarios.md       R — 6-field scenarios with measurable outcomes
  decisions/
    001-<slug>.md            A — one ADR per key decision
  views/
    context.md               C — system context and boundaries
    module.md                C — responsibilities and ownership
    runtime.md               C — communication patterns and flows
    deployment.md            C — infrastructure, trust zones, AI boundary
    data-and-trust.md        C — data flows and trust boundaries
  risks/
    risk-register.md         risks accepted in ADRs, with owners
  evidence/
    evidence-plan.md         E — production metrics + pre-release tests
    production-metrics.md    E — live metric values and trends
  evolution/
    backlog.md               E — improvements pending when evidence fails

The full skill source is available at: github.com/dariopalladino/orace-skill

The repository contains both the orace-workshop and orace-adr skills with installation instructions, example output for a sample API project, and a blank ORACE worksheet you can fill in manually if you prefer not to use the automated interview.