Engineering Principles
Princípios que orientam minhas decisões de engenharia, arquitetura e liderança técnica.
How I Engineer#
Tecnologias mudam rapidamente. Frameworks mudam. Modelos mudam. Plataformas mudam. Mas alguns princípios continuam úteis por muito mais tempo.
Ao longo da minha trajetória, fui acumulando ideias que influenciam a forma como penso arquitetura, inteligência artificial, sistemas distribuídos e liderança técnica.
Não trato esses princípios como regras absolutas. Eles são ferramentas de decisão.
Index by Theme#
Trinta e oito princípios em ordem de escrita ficam difíceis de escanear. Agrupados por tema, eles ficam mais fáceis de navegar sem perder a leitura linear abaixo.
Autonomy & AI#
- 1. Evidence Before Autonomy
- 2. AI Is a System, Not a Prompt
- 3. Human-in-the-loop Is Architecture
- 22. Tools Create Responsibility
- 24. Authorization Is a Domain Problem
- 28. Auditability Grows with Power
Architecture & Boundaries#
- 5. Replaceable Boundaries
- 6. Domain Before Technology
- 7. Explicit State Beats Implicit Behavior
- 14. Incremental Evolution
- 15. Complexity Must Pay Rent
- 16. Simplicity Before Infrastructure
- 23. Protocols Can Become Architecture
- 35. Architecture Should Make Change Safer
- 37. The Goal Is Not Maximum Abstraction
- 38. Build for Evolution, Not Prediction
Reliability & Failure#
- 4. Observability by Design
- 8. Failure Is Part of the Architecture
- 9. Recovery Is a Feature
- 10. Safe Defaults
- 11. Immutability Where History Matters
- 25. Partial Failure Is Still Failure
- 26. Cancellation Is a Protocol
- 27. Idempotency Is a Reliability Tool
Research & Evidence#
- 17. Research and Runtime Are Different Systems
- 18. Baselines Must Be Protected
- 19. Scientific Correctness Is Different from Software Correctness
Context & Memory#
Leadership & Communication#
- 12. Documentation Is Engineering
- 13. Decisions Need Context
- 29. UX Must Reflect System Truth
- 30. Engineering Is Also Communication
- 31. Context Before Direction
- 32. Principles Before Rules
- 33. Ownership Before Control
- 34. Systems Before Heroes
- 36. Optimize for Understanding
1. Evidence Before Autonomy#
Autonomy should be earned, not assumed.
Um sistema não deveria receber mais autonomia simplesmente porque tecnicamente consegue executar determinada ação.
Existe uma diferença fundamental entre Can execute e Should execute.
A primeira é capacidade. A segunda envolve evidência, risco e responsabilidade.
Progressão possível:
Observe
↓
Recommend
↓
Prepare
↓
Execute with Approval
↓
Execute Within PolicyAntes de ampliar autonomia, procuro responder se o comportamento foi observado por tempo suficiente, se existem métricas, cenários de falha, reconstrução de decisões, rollback e condições que invalidam a confiança atual.
Exemplo: Invest Lucy utiliza Scientific Evidence → Shadow Outcomes → Calibration → Hypothesis Experiments → Walk-forward → OOS → Monte Carlo → Human Review.
2. AI Is a System, Not a Prompt#
Good prompts do not replace engineering.
Uma aplicação de IA envolve modelos, contexto, dados, retrieval, memória, ferramentas, permissões, avaliação, observabilidade, custos, fallback, segurança e governança.
O prompt é apenas uma interface entre essas partes.
Product
↓
AI Capability
↓
Context
↓
Model
↓
Tools
↓
EvaluationNo LucyOS, inteligência emerge da combinação entre agentes, memória, conhecimento, MCP, ferramentas, contexto e políticas.
3. Human-in-the-loop Is Architecture#
Human control should be designed, not improvised.
Participação humana precisa existir como parte explícita da arquitetura.
Precisamos definir onde decisões humanas são necessárias, quais ações exigem aprovação, como interromper uma execução, como revisar decisões e como comunicar incerteza.
Uma taxonomia útil:
Read
Suggest
Prepare
Execute with Approval
Execute Within Policy
High-Risk Execute4. Observability by Design#
If a system can act, we should be able to understand what it did.
Observabilidade vai além de logs.
Precisamos responder o que aconteceu, quando, por quê, quais dependências participaram, qual contexto estava disponível e qual foi o resultado.
Em sistemas inteligentes existe uma pergunta adicional: Como reconstruímos uma decisão?
5. Replaceable Boundaries#
External dependencies should not become your architecture.
Modelos, APIs, serviços e frameworks mudam.
Identificar dependências com alta probabilidade de mudança e impedir que detalhes específicos atravessem o sistema inteiro ajuda a reduzir acoplamento.
Domain
↓
Capability
↓
Adapter
↓
External Provider6. Domain Before Technology#
Understand the problem before choosing the abstraction.
Perguntas como “microservices?”, “eventos?” ou “agentes?” são secundárias.
Primeiro precisamos compreender entidades, estados, responsabilidades, invariantes, fluxos, falhas e boundaries.
No Livrya, a distinção entre working copy e published version veio antes da tecnologia.
7. Explicit State Beats Implicit Behavior#
Important state should be modeled.
Evitar ausência de registro significando “pendente”, booleanos tentando representar muitos estados ou processo finalizado sendo tratado como processo bem-sucedido.
Preferir estados explícitos como:
PENDING
PROCESSING
COMPLETED
FAILED
CANCELLED8. Failure Is Part of the Architecture#
Systems should be designed for failure, not surprise.
APIs falham, bancos ficam indisponíveis, workers caem, mensagens chegam duas vezes e requests sofrem timeout.
Precisamos responder: pode repetir? é idempotente? existe retry? cancellation? DLQ? recovery?
9. Recovery Is a Feature#
Restarting the process is not recovery.
Recuperação precisa considerar efeitos externos e estado real do mundo.
Reconciliation, checkpoints, idempotency, durable state, replay e recovery procedures fazem parte do design.
10. Safe Defaults#
When uncertain, systems should fail toward the safer state.
Exemplos:
No authorization → deny
No autonomy configuration → autonomy off
Unknown state → do not execute
Invalid evidence → do not promote11. Immutability Where History Matters#
Mutable systems still need immutable history.
Alguns dados representam fatos históricos: publicação, eventos financeiros, auditoria, decisões, fills e versões.
Pergunta útil: isso representa estado atual ou algo que aconteceu?
12. Documentation Is Engineering#
Code tells us what. Documentation preserves why.
PRD responde o que queremos construir. ADR responde por que escolhemos determinada abordagem. Implementation Plan responde como executar. Validation Report responde se a hipótese foi atendida. Roadmap registra sequência de evolução.
13. Decisions Need Context#
A decision without context becomes a rule without meaning.
Para decisões relevantes, registrar:
Context
Decision
Alternatives
Consequences
What could change this decision?14. Incremental Evolution#
Large systems should earn complexity progressively.
Preferir:
Simple
↓
Observed limitation
↓
Explicit requirement
↓
New capabilityem vez de construir grande infraestrutura para necessidade futura apenas possível.
15. Complexity Must Pay Rent#
Every abstraction should solve a real problem.
Cada nova camada adiciona manutenção, aprendizado, debugging, deploy, observabilidade e dependências.
Perguntas: qual problema concreto resolve? o que fica mais simples? quem manterá isso? existe solução menor?
16. Simplicity Before Infrastructure#
Infrastructure should support the product, not define it.
Começar pela menor infraestrutura capaz de sustentar requisitos atuais com margem razoável de evolução.
17. Research and Runtime Are Different Systems#
Experimentation and production optimize for different things.
Pesquisa precisa de liberdade para testar, comparar, falhar e mudar parâmetros. Runtime precisa de previsibilidade, estabilidade, governança e auditabilidade.
Research
↓
Evidence
↓
Promotion Gate
↓
Runtime18. Baselines Must Be Protected#
Experiments are useful only when there is something stable to compare against.
Baseline
vs
Experiment A
vs
Experiment B19. Scientific Correctness Is Different from Software Correctness#
A program can run perfectly and still produce invalid evidence.
Exemplos: look-ahead bias, data leakage, seleção inadequada, janela temporal errada e outcome prematuro.
Qualidade científica precisa validar:
Code Correctness
+
Data Correctness
+
Methodological Correctness20. Context Is a Resource#
More context is not always better context.
Contexto possui custo, ruído, limites e risco de conflito.
Separar memória, conhecimento, projeto, conversa e estado operacional ajuda a montar contexto intencionalmente.
21. Memory Requires Curation#
Remembering everything is another form of forgetting.
Memória precisa considerar relevância, tempo, atualização, conflito, consolidação e descarte.
22. Tools Create Responsibility#
Giving an agent a tool changes the risk model.
Um agente capaz de editar arquivos, enviar mensagens, executar código, modificar bancos ou operar sistemas financeiros possui outro perfil de risco.
Ferramentas precisam de autorização, scope, contracts, audit e aprovação humana quando necessário.
23. Protocols Can Become Architecture#
Good protocols create useful boundaries.
Protocolos podem separar Intent de Implementation. MCP é exemplo relevante em ecossistemas agentic.
24. Authorization Is a Domain Problem#
Permissions should describe capabilities, not scattered conditionals.
Preferir conceitos como canRead, canWrite, canManage ou guards de domínio equivalentes.
25. Partial Failure Is Still Failure#
Finished is not the same as successful.
Workflows distribuídos podem terminar com resultados incompletos. Semântica de estado importa.
26. Cancellation Is a Protocol#
Cancel is not just a UI button.
O request pode pedir cancelamento, mas worker precisa observar, interromper, persistir estado e liberar recursos.
27. Idempotency Is a Reliability Tool#
Retry without idempotency can duplicate side effects.
Operações importantes precisam identificar intent único, correlation id, existing result e safe retry behavior.
28. Auditability Grows with Power#
The more a system can do, the more it must explain.
Quanto maior a capacidade de impacto, maior precisa ser observabilidade, auditabilidade, autorização e clareza de intervenção humana.
29. UX Must Reflect System Truth#
The interface should never invent certainty the backend does not have.
Se o backend possui estado incerto, a UI precisa representar incerteza.
30. Engineering Is Also Communication#
Systems scale through shared understanding.
Arquitetura não escala se apenas uma pessoa a compreende. Naming, documentação, diagramas, reviews, princípios e decisões registradas fazem parte da engenharia.
31. Context Before Direction#
People make better decisions when they understand why.
Dar instruções resolve o problema imediato. Compartilhar contexto melhora decisões futuras.
32. Principles Before Rules#
Rules answer known situations. Principles help with new ones.
Princípios compartilhados permitem resolver novos problemas mantendo coerência.
33. Ownership Before Control#
Strong engineering teams need responsibility, not constant permission.
O equilíbrio está em contexto claro, boundaries claros e ownership real.
34. Systems Before Heroes#
Reliable organizations should not require constant rescue.
Boa engenharia tenta reduzir necessidade de heroísmo por automação, documentação, processos, observabilidade e melhores boundaries.
35. Architecture Should Make Change Safer#
The real test of architecture is not the first release.
Boa arquitetura não elimina mudança; reduz custo e risco de mudar.
36. Optimize for Understanding#
Clever code is expensive when nobody can safely change it.
Favorecer nomes claros, responsabilidade explícita, fluxo visível e abstrações justificadas.
37. The Goal Is Not Maximum Abstraction#
Abstractions should remove complexity, not hide it.
Cada abstração deveria possuir razão clara. Se apenas move complexidade para outro arquivo, talvez não esteja ajudando.
38. Build for Evolution, Not Prediction#
Architecture should tolerate change without pretending to know the future.
Não antecipar todos os requisitos futuros; identificar áreas de provável mudança e criar espaço para evolução.
My Decision Framework#
- What problem are we actually solving?
- What are the invariants?
- Where should state live?
- What happens when this fails?
- What changes most often?
- What needs to be auditable?
- What can humans override?
- How will we know if it works?
- What is the simplest acceptable solution?
- What would make us revisit this decision?
How the Principles Connect#
Autonomy
↓
requires Evidence
↓
requires Observability
↓
requires Explicit State
↓
requires Auditability
↓
requires Governance
↓
requires Human ControlE:
AI Capability
↓
uses Tools
↓
requires Boundaries
↓
requires Authorization
↓
requires Observability
↓
requires Failure HandlingProjects That Shaped These Principles#
LucyOS#
AI is a System, Not a Prompt; Context Is a Resource; Memory Requires Curation; Replaceable Boundaries; MCP-first; Human Control.
Invest Lucy#
Evidence Before Autonomy; Safe Defaults; Research vs Runtime; Scientific Correctness; Recovery; Auditability; Human Review.
Livrya#
Domain Before Technology; Explicit State; Immutability; Authorization; Cooperative Cancellation; Partial Failure; Product Boundaries.
These Principles Are Not Finished#
Esses princípios representam meu pensamento atual. Não são dogmas. Experiência nova pode refiná-los, criar exceções, revelar conflitos ou gerar novos princípios.
Closing#
Depois de mais de duas décadas trabalhando com software, minha visão se tornou menos centrada em tecnologias específicas.
O que mais importa para mim hoje é construir sistemas que consigam combinar capability com clarity, autonomy com control, complexity com understanding e change com reliability.
Build systems that can evolve without becoming impossible to understand.