diff --git a/docs/debugger/README.md b/docs/debugger/README.md new file mode 100644 index 00000000..25ad808d --- /dev/null +++ b/docs/debugger/README.md @@ -0,0 +1,113 @@ +# Especificação — Ciclo de Desenvolvimento Prometeu +**Versão:** 0.1 +**Status:** Conceitual / Filosófico + +--- + +## 1. Princípio Central + +O Prometeu é uma plataforma didática de desenvolvimento de software interativo. +Seu ciclo de desenvolvimento é projetado para separar claramente: + +- Criação de código +- Compilação +- Execução +- Observação e explicação + +Cada etapa possui uma ferramenta própria, especializada e não sobreposta. + +--- + +## 2. Ferramentas do Ciclo + +O ciclo utiliza quatro pilares: + +1. **Editor de Código** + Ambiente livre (ex: WebStorm) onde o desenvolvedor escreve em TypeScript. + +2. **Compilador Prometeu** + Converte código fonte em bytecode executável pela runtime Prometeu. + +3. **Runtime Prometeu** + Executa jogos e aplicações em seu próprio ambiente gráfico. + +4. **Prometeu Debugger** + Ferramenta didática de observação, análise e explicação do comportamento interno do sistema. + +Nenhuma dessas ferramentas tenta substituir a outra. +Elas cooperam através de contratos claros. + +--- + +## 3. Fluxo Geral + +O ciclo segue sempre a mesma sequência conceitual: + +1. O desenvolvedor escreve código em TypeScript. +2. O código é compilado para bytecode Prometeu. +3. O bytecode é empacotado como cartucho. +4. O cartucho é executado pela runtime. +5. O comportamento interno pode ser observado pelo Prometeu Debugger. + +--- + +## 4. Modos de Execução + +O Prometeu possui dois modos conceituais de execução: + +### Execução Normal (Run) + +- O cartucho é empacotado e executado. +- A runtime funciona de forma autônoma. +- O Debugger atua apenas como observador. + +### Execução Assistida (Debug) + +- O cartucho é empacotado e executado. +- A runtime aguarda conexão do Prometeu Debugger. +- O Debugger passa a controlar e observar a execução. + +--- + +## 5. Separação de Papéis + +Cada parte do ciclo tem responsabilidade única: + +| Etapa | Papel principal | +|-----------|--------------------------------------| +| Editor | Criar código | +| Compilador| Transformar código em bytecode | +| Runtime | Executar | +| Debugger | Observar, explicar e ensinar | + +Essa separação é intencional e parte da filosofia do Prometeu. + +--- + +## 6. Filosofia Didática + +O Prometeu não é apenas uma engine. +Ele é uma plataforma para aprender como software interativo funciona por dentro. + +O ciclo de desenvolvimento é pensado para: + +- Tornar a execução visível +- Tornar decisões técnicas observáveis +- Tornar erros explicáveis +- Tornar desempenho mensurável + +O Debugger não é apenas uma ferramenta de correção, mas um instrumento pedagógico. + +--- + +## 7. Síntese + +O Ciclo de Desenvolvimento Prometeu é: + +- Modular +- Observável +- Didático +- Não acoplado a uma IDE específica +- Orientado a aprendizado e compreensão profunda + +Ele existe para que o desenvolvedor não apenas escreva programas, mas entenda como eles vivem dentro da máquina.