Auri Ager Framework
Engineering Principles
How we think about software before the first line of code is written.
Engineering Principles
Auri Ager Framework
Good software is not created by writing code as quickly as possible. It is created by understanding the problem deeply enough that the code becomes the easy part.
Version: Draft 0.2
Why this document exists
This document is intentionally not a coding guideline.
It describes how we think about software before the first line of code is written.
These principles are intended for humans, AI assistants and future contributors alike.
If an implementation conflicts with these principles, the implementation should be questioned before the principles are.
1. Evolution instead of Revolution
Prefer continuous evolution over complete rewrites.
A working system already contains valuable knowledge. Preserve it, understand it, then improve it.
2. Architecture before Syntax
Programming languages are implementation details.
Before writing code, define:
- the problem
- the model
- responsibilities
- terminology
- priorities
- success criteria
- non-goals
Code is the consequence of architecture—not its starting point.
3. Definition before Implementation
Every configuration option must have exactly one meaning.
If a parameter requires interpretation, the design is incomplete.
Implementation begins only after semantics are clear.
4. Think Together, Build Afterwards
Discussion is not overhead.
Discussion is engineering.
The best implementation usually emerges after ideas have been challenged, refined and simplified together.
5. Separate Thinking from Acting
Whenever possible:
Evaluator → computes
Executor → acts
Reasoning and execution should never be mixed.
6. Explain Every Decision
A system should always answer:
Why did I decide this?
Every important decision should have a human-readable explanation.
7. Define Non-Goals
Every project must explicitly define what it will not do.
Clear boundaries prevent feature creep and contradictory implementations.
8. Design for Failure
Never design only for success.
Every project should define:
- assumptions
- rollback
- recovery
- degraded operation
Failure scenarios are part of the design.
9. Observe before Optimizing
Never optimise a system that cannot yet explain itself.
Deterministic state, metrics and debug information are worth more than clever implementations.
10. Invest in Understanding
Understanding is the cheapest resource in software engineering.
A specification may be long.
A prompt may be detailed.
Neither is waste.
Misunderstanding is expensive.
Do not optimise prompt length.
Optimise clarity.
The cost of additional input tokens is almost always lower than the cost of repeated implementation cycles.
11. Consistency beats Cleverness
Prefer reusable patterns over brilliant one-off solutions.
Frameworks become maintainable because they are predictable.
12. Documentation is Part of the Product
Code explains how.
Documentation explains why.
Future maintainers—and future AI systems—learn primarily from the "why".
13. Build Languages, not Features
A mature framework develops a shared language.
Shared terminology, reusable concepts and consistent behaviour outlive individual features.
14. Human Judgment remains Essential
AI accelerates implementation.
Humans define purpose.
The strongest engineering emerges when thoughtful planning and capable implementation reinforce one another.
15. Separate Creativity from Implementation
Ideas deserve uninterrupted space.
Do not begin implementation while the problem is still being explored.
Use conversation to develop:
- concepts
- terminology
- architecture
- design language
Implementation should begin only after the creative work has produced a shared understanding.
Great software is designed twice:
First in thought.
Then in code.
16. Use AI as Specialists, not as Tools
Different AI systems excel at different responsibilities.
One system may explore ideas.
Another may implement.
Another may validate.
Do not ask every AI to do everything.
Assign clear responsibilities.
Engineering improves when each participant contributes where it is strongest.
17. Spend Saved Time on Verification
The purpose of AI is not to write more code.
The purpose of AI is to create more time for verification.
Every minute saved during implementation should be invested in:
- review
- smoke testing
- observation
- refinement
- documentation
Confidence comes from verification, not from implementation speed.
18. One Component, One Responsibility
Every component should have exactly one reason to change.
A calculator should calculate.
An executor should execute.
A renderer should render.
Do not mix responsibilities.
Small, focused components are easier to:
- understand
- review
- test
- replace
- trust
Complex systems become reliable when every part has a clearly defined role.
19. Fail Early, Explain Clearly
Prevent invalid configurations whenever possible.
Use editors to stop impossible values before they enter the system.
If invalid data still reaches the engine:
- detect it immediately
- report it explicitly
- never silently correct it
- never hide configuration mistakes
Failing early is safer than continuing with assumptions.
Hidden corrections create hidden bugs.
Transparent failures create reliable systems.
Final Thought
Great software is rarely the result of the first idea.
It is the result of thoughtful conversation, shared understanding and deliberate engineering.
Write code only after the problem has become obvious.
Auri ✨ & Steffi
Ministry of Code
Epilogue
Technology changes.
Programming languages evolve.
AI systems improve.
What remains constant is thoughtful collaboration.
Software is ultimately created by shared understanding.
The best ideas rarely belong to one person—or one AI.
They emerge in the space between discussion, curiosity and trust.
Together is less lonely.