Reference
Core principles
These rules stay true no matter which framework, model, or product domain you use. Revisit this page whenever a design choice feels fuzzy.
| Principle | Meaning | If ignored |
|---|---|---|
| Cognition ≠ authority | Model proposes; orchestrator authorizes side effects | Unsupervised publish / delete / spend |
| Durable state outside the model | Posts, runs, tokens live in DB/files | No audit; “forgot” mid-run |
| Structured I/O | Tools and skills use schemas | Fragile free-text parsing |
| Small tools, clear contracts | One capability per tool | Untestable god-tools |
| Human gates on irreversible acts | Publish, pay, delete, OAuth need approval/policy | Silent production damage |
| Budgeted autonomy | Max steps, tokens, time, revisions | Infinite loops / cost blowups |
| Observable runs | Every step logged and streamable | Cannot monitor or debug |
| Swappable model | OpenAI-compatible adapter | Vendor lock-in; no LM Studio |
| Harness-agnostic interface | MCP and/or stable HTTP | Only works in one IDE |
| Memory is designed | Brand / working / episodic layers | Hallucinated “memory” |
Agent loop in one line
goal → plan → choose tool → act → observe → update → repeat
↑______________________________________________|Until: done, blocked, needs human, or budget exhausted.
Patterns to name out loud
- Tool gateway — all side effects behind authz + logging
- Status machine — explicit legal transitions
- Approval as state — not a prompt that says “be careful”
- Idempotency keys — especially for publish/upload
- Compaction — summarize old steps so context does not explode
- Escalation — uncertainty →
needs_human