Design Heuristics

Bound uncertainty early

Translate open-ended model behavior into narrow component contracts as close to the model boundary as possible.

Separate selection from generation

When a system must choose evidence and produce an answer, inspect and evaluate those decisions separately before combining them.

Make the safe path the easy path

Tool interfaces should encode permissions, validation, idempotency, and audit metadata so callers do not recreate safety on every use.

Preserve lineage

Outputs should retain references to their inputs, configuration, source evidence, and component versions. Lineage turns a result into an inspectable artifact.

Prefer reversible changes

Start with changes that can be shadowed, compared, rolled back, or compensated. Irreversible state changes demand stronger verification.

Test the seams

Many failures live between components: truncation, encoding, schema drift, permissions, timeouts, and mismatched assumptions. Contract tests at seams often outperform more unit tests inside a component.