5 Choose among meaningful alternatives

An agent can often produce several architectures on request. That does not mean the alternatives expose a real decision. Three diagrams with different service names may conceal the same tradeoff, while one apparently minor difference in ownership changes the entire failure behavior.

The point of alternatives is to reveal consequences that matter to the intended outcome.

Compare the same problem

For the resource system, consider three approaches. Reuse the existing publication API if it already provides the required readiness semantics. Add a narrow operation if transfer and publication are currently conflated. Introduce a shared acquisition layer if several actual consumers need the same identity and lifecycle contract.

These options differ in scope, migration cost, and the responsibilities they centralize. Compare them against the same scenarios: a successful replacement, a failed readiness check, cancellation during finalization, an existing reader holding the old version, and a restart after an uncertain result.

Do not let each option choose its own favorable criteria. A reusable layer should answer the same immediate usability requirement as a direct implementation. A small patch should account for any repeated lifecycle logic it leaves behind. The comparison should make costs visible on both sides.

The Architecture Tradeoff Analysis Method formalizes evaluation around quality scenarios, risks, sensitivity points, and tradeoffs. A small option note can borrow that reasoning without pretending to be a complete ATAM evaluation. The full method carries a process cost that may be inappropriate for a small reversible change. ATAM Method for Architecture Evaluation.

Include the option of doing less

A simpler design must be a legitimate outcome. If the consumer can tolerate restarting an interrupted download, resumable transfer may not belong in the first release. If only one application needs the behavior, a local implementation may be sufficient. If the existing interface fits, the best result of discovery may be a decision not to add another abstraction.

Doing less is not automatically simpler over the whole lifecycle. Duplicating a subtle publication rule across three consumers may reduce today's diff while increasing tomorrow's risk. The relevant question is which complexity is necessary now, which is a demonstrated common need, and which is merely anticipated.

An alternative should therefore include its likely point of reconsideration. “Use the current API until a second consumer needs a different retention policy” is more informative than “keep it simple.” It tells future developers what evidence would reopen the decision.

Make consequences understandable

A requester may approve an option because it meets every stated requirement, yet be surprised by an unstated consequence. A shared service may need to remain running. A local cache may retain data longer than expected. Automatic runtime selection may use more disk space. A stronger consistency rule may reduce concurrency.

Explain these consequences in terms of behavior, not just implementation. “This keeps the old version available while preparing the new one, at the cost of temporarily storing both” is easier to judge than a storage-class diagram alone.

Sometimes the consequence belongs to someone other than the requester. A change that makes contributions easier may increase maintainer review work. An agent-friendly interface may require another component to own retries or cleanup. Include the receiving party's needs rather than optimizing only the caller's experience.

Do not manufacture numerical certainty

A weighted score can help when criteria are genuinely comparable and the weights have an agreed meaning. It can also disguise judgment. Giving maintainability eight points and complexity six points does not measure either property.

Use numbers where there is a basis: measured startup time, memory use under a stated workload, migration steps, or a known license cost. Use reasoned comparisons where there is not. State the uncertainty instead of converting it to an arbitrary decimal.

Requirements framing itself can affect the search. Mohanani, Turhan, and Ralph's two experiments found less original but more practical concepts under requirements-oriented framing than ideas-oriented framing. Their paper-design tasks and samples limit transfer to agent engineering. The useful implication is to distinguish genuine obligations from tentative ideas, not to pretend every constraint is optional. Requirements Framing Affects Design Creativity.

Record the choice at the right scale

A compact decision record can retain the context, selected approach, alternatives, and consequences. It should explain the surprising part of the choice. If the obvious existing operation was reused without controversy, a sentence in the task record may suffice. If a shared boundary is being introduced, a durable record is more valuable.

Michael Nygard's architecture-decision proposal uses short records with context, decision, status, and consequences, retaining superseded choices. It is an early practitioner account rather than measured proof of effectiveness. Its practical appeal is that future readers can understand why a choice made sense without reconstructing the entire discussion. Documenting Architecture Decisions.

Choose one design decision in your current work. Describe two materially different viable approaches, or explain why only one meets the constraints. Compare them through the same concrete scenario. State the selected behavior, its cost, and the observation that would justify reconsidering it. That record is enough if it allows another developer to challenge the decision intelligently.