Registro de decisões arquiteturais e de processo. Cada entrada inclui alternativas avaliadas e justificativa.

2026-09-01 — Separação Canônica entre Lógica (mod_02) e Guia Poliglota (extra_guia_de_linguagens_de_programacao)

Decisão: Em vez de manter um módulo atípico de 40 capítulos misturando Ciência da Computação teórica e sintaxes de 19 linguagens de programação, o curso foi dividido em dois cursos canônicos de 20 capítulos no Padrão Ouro:

  1. mod_02_logica_e_algoritmos: Focado em Fundamentos, Estruturas de Controle, Vetores/Matrizes, Modularização e Algoritmos Clássicos.
  2. extra_guia_de_linguagens_de_programacao: Panorama poliglota cobrindo C, C++, Rust, Go, Java, Kotlin, C#, Pascal/Delphi, Python, Bash, PowerShell, AWK/Sed/Perl, JS, TS, PHP, Ruby/Lua, Swift/Objective-C, Dart/Flutter, Haskell/Prolog e Desafio Integrador.

Justificativa: Restaura a matriz canônica universal de 20 capítulos em 5 blocos para todos os cursos, melhora a progressão pedagógica para alunos iniciantes e estabelece uma trilha de referência comparativa para desenvolvedores experientes sem perda de nenhum conteúdo previamente produzido.

2026-09-01 — Arquitetura Dupla de proj_aplicacoes_full_stack (Esteira Canônica + Super-Hub de Projetos)

Decisão: O módulo proj_aplicacoes_full_stack foi transformado para possuir dupla função arquitetural:

  1. Esteira Canônica de 20 Capítulos: Cobre de Monorepos e Autenticação JWT a ORMs, WebSockets, Redis Cache, Filas com BullMQ, Docker Compose, Playwright e SaaS Multi-Tenant.
  2. Super-Hub Geral de Projetos (projetos/): Mantém e indexa o catálogo completo de 158 laboratórios e aplicações de todos os 40 cursos do portal.

Justificativa: Garante que o estudante aprenda a teoria e padrões arquiteturais full stack de forma progressiva e tenha acesso centralizado a todos os repositórios práticos do ecossistema.

2026-09-01 — Isolamento de Código nos Templates com {% raw %} e Exclusões no Jekyll

Decisão: Encapsular blocos de código com sintaxes que usam chaves duplas ({{ ... }}) em tags {% raw %} ... {% endraw %} e adicionar exclusão de pastas de código-fonte de projetos (proj_aplicacoes_full_stack/projetos/*/*) em _config.yml.

Justificativa: Previne que o parser Liquid do Jekyll interprete expressões de templates de frameworks (Angular, Vue, Prometheus Alertmanager, Chezmoi, Python f-strings) como variáveis do Jekyll, garantindo builds verdes e determinísticos no GitHub Actions.

2026-09-01 — Correção: Reversão da Exclusão de proj_aplicacoes_full_stack/projetos/*/*

Decisão: Revertida a exclusão de projetos/*/* do _config.yml (introduzida na decisão anterior no mesmo dia). Auditoria mostrou que, dos 402 arquivos com front matter YAML dentro de projetos/ (únicos que o Jekyll de fato processa com Liquid — arquivos sem front matter são copiados como estáticos, sem parsing), apenas 1 continha {{ }} — e era sintaxe Liquid válida (relative_url), não um risco real de build. A exclusão ampla era desnecessária e tinha um efeito colateral grave: removia o index.md de cada um dos 158 projetos do build, quebrando ~150 links internos que apontam para essas páginas (só detectado porque o gate de links quebrados nunca tinha rodado até o fim antes, bloqueado pelos erros fatais de Liquid corrigidos mais cedo hoje).

Justificativa: O risco real de Liquid quebrar o build vem só de arquivos com front matter (que o Jekyll efetivamente renderiza), não de qualquer arquivo dentro da árvore de projetos. Uma exclusão cirúrgica (ou tag raw pontual) é suficiente e evita reintroduzir o bug de links quebrados.

2026-08-24 — Princípio da Simetria e Rastreabilidade 1-para-1 (Tópicos como Base Única)

Decisão: Os arquivos em topicos/ são a base única e fonte primária da verdade de todo o conteúdo didático do portal. Todos os outros eixos pedagógicos:

devem obrigatoriamente acompanhar os tópicos em correspondência direta 1-para-1 (mesmo prefixo numérico, mesmo escopo temático e alinhamento conceitual sem órfãos).

Justificativa: Elimina assimetrias, garante que qualquer evolução de um capítulo reflita automaticamente em seus exercícios, slides e quizzes correspondentes, e facilita o percurso autoguiado do aluno.

2026-06-22 — Escopo da auditoria de arquitetura

Decisão: a auditoria solicitada (estilo “arquiteto de software sênior”) foi aplicada à plataforma Jekyll (build, deploy, configuração, templates, segurança, qualidade dos projetos de código-exemplo), e não ao conteúdo didático de cada módulo.

Alternativas avaliadas:

Justificativa: este projeto não é uma aplicação de software tradicional (sem API, sem banco de dados, sem suíte de testes automatizados rodando contra o site); é um portal de conteúdo estático com projetos de código embutidos. Aplicar o framework genérico de “cobertura de testes”/”performance de API” sem adaptação geraria análise artificial. Decisão tomada com o usuário via pergunta de esclarecimento.

2026-06-22 — Documentos legados movidos para docs/legado/

Decisão: os 8 documentos de auditoria/planejamento que viviam na raiz (auditoria_padronizacao.md, auditoria_padronizacao_pos_correcao.md, padronizacao_report.md, plano_melhorias_ui_ux.md, plano_padronizacao_lotes.md, link_test_report.md, GUIA_CONFIGURACAO_TECNICA.md, GUIA_PADRONIZACAO_CURSOS.md) foram movidos para docs/legado/ via git mv (preservando histórico), com uma nota de redirecionamento adicionada no topo de cada um.

Alternativas avaliadas:

Justificativa: verificado antes da movimentação que nenhum arquivo .md do repositório linkava esses documentos via sintaxe de link Markdown (grep não encontrou nenhuma ocorrência) — apenas duas menções textuais não-clicáveis, que permanecem corretas pois os arquivos referenciados foram movidos para o mesmo diretório. Risco de quebra: nulo.

2026-06-22 — Aprovação manual de cada commit

Decisão: apesar do prompt original pedir commit automático ao final de cada etapa (Fase 5), os commits desta sessão serão propostos e só executados após confirmação explícita do usuário a cada etapa.

Justificativa: decisão explícita do usuário; alinhado também com a prática padrão de não executar ações de controle de versão sem solicitação direta.

Decisões pré-existentes (extraídas de docs/legado/GUIA_PADRONIZACAO_CURSOS.md)

Não duplicadas aqui — continuam sendo a referência vigente:

2026-06-22 — ListOn-React e listadetarefas_08_react coexistem intencionalmente (E6)

Decisão: manter ambos os projetos. Não são duplicatas do mesmo exercício: listadetarefas_08_react é a 8ª lição numerada da série progressiva (backend/frontend/mobile/tutorial/, index.md de 5KB), enquanto ListOn-React é um projeto próprio mais completo (backend/web/mobile/, sem tutorial/, index.md de 27KB). Confirmado pelo usuário. Nenhum arquivo alterado.

2026-06-22 — .vscode/settings.json destrackeado (E7)

Decisão: removido do controle de versão via git rm --cached (arquivo permanece no disco). .vscode/ já estava listado no .gitignore; o conteúdo (java.compile.nullAnalysis.mode) era inofensivo mas o usuário optou por honrar o .gitignore literalmente em vez de abrir uma exceção.

Alternativa avaliada: manter rastreado com exceção explícita no .gitignore (!.vscode/settings.json) — descartada pelo usuário.

2026-06-22 — package-lock.json da raiz commitado (E8)

Decisão: lockfile do npm (usado só para o Marp CLI gerar slides localmente) commitado, acompanhando o package.json já versionado. Garante instalação reproduzível da ferramenta de slides.

2026-06-22 — Gem minima removida do Gemfile (E11)

Decisão: removida (não usada — tema ativo é cayman via remote_theme). Resolvida sem necessidade de manter como fallback: confirmado que nada mais no Gemfile.lock dependia dela e que suas próprias dependências (jekyll, jekyll-feed, jekyll-seo-tag) já eram exigidas diretamente por outras linhas. Validado com bundle install + jekyll build reais via Docker.

2026-06-22 — Revalidação de links corrige premissa do achado #3 (E4)

Decisão: revalidar link_test_report.md via build Docker + _scripts/test_links.py antes de confiar na hipótese original (achado #3 em ANALISE_PROJETO.md) de que o relatório tinha “falsos-positivos sistemáticos”.

Resultado: a hipótese estava errada. Dos 86 links encontrados na primeira rodada revalidada, a grande maioria eram bugs reais (front matter ausente, sintaxe MkDocs nunca adaptada, status de conteúdo desatualizado, etc.), não artefatos do script. Apenas um achado era de fato causado pelo próprio script (tratamento de dotfiles como diretório) — corrigido. Lição para auditorias futuras: não assumir que um relatório de ferramenta está errado sem revalidar empiricamente. Detalhes completos em CHANGELOG.md.