Codex Technomanticus

Setup completo — do zero ao sistema de produção

Leitura de 15 min

Setup completo — do zero ao sistema de produção

TL;DR

Esta nota atravessa as 11 camadas com um exemplo concreto: um gerador de newsletter semanal de IA. Para cada camada, preenchemos o template e mostramos a decisão. No fim, você tem o blueprint completo de um sistema — não apenas o que cada camada faz, mas como elas conversam entre si. Use esta recipe como ponto de partida pra adaptar a sistemas seus, trocando o exemplo pelos seus inputs.

flowchart TD
    P1["① Purpose\n(escopo + sucesso)"]
    P7["② Workflow vs Agent\n(arquitetura)"]
    P4["③ Output\n(contrato de saída)"]
    P2["④ Prompt + Context\n(comportamento + situação)"]
    P5["⑤ Retrieval + Tool\n(fontes + ações)"]
    P8["⑥ Evaluation + Guardrail\n(qualidade + segurança)"]
    P10["⑦ Logging\n(rastreabilidade)"]
    P11["⑧ Improvement\n(aprendizado contínuo)"]

    P1 --> P7 --> P4 --> P2 --> P5 --> P8 --> P10 --> P11

    style P1 fill:#4A90D9,stroke:#2171B5,color:#fff
    style P7 fill:#2CA05A,stroke:#1A7A3F,color:#fff
    style P8 fill:#F5A623,stroke:#C47D0A,color:#000
    style P11 fill:#9B59B6,stroke:#7D3C98,color:#fff

O sistema de exemplo

AI Weekly Newsletter Generator — um sistema que, toda sexta-feira, monta uma newsletter sobre o que aconteceu em IA na semana, com 5-7 itens curados, cada um com link, resumo e takeaway de uma frase.

Por que esse exemplo:

  • É comum o bastante pra todo mundo entender o problema.
  • Toca todas as 11 camadas (não é trivial demais).
  • Tem riscos reais (citação errada, viés de fonte, alucinação de link).
  • É o exemplo usado pelo @hooeem no thread original — facilita comparação.

Este é um exemplo didático

Os valores abaixo são razoáveis pro exemplo, não prescrição universal. Adapte a defaults sensatos pro seu domínio.

Ordem de construção ≠ ordem canônica

Este recipe percorre as camadas em ordem de construção (qual decidir primeiro), não em ordem numérica canônica. Cada passo identifica também a camada canônica entre parênteses pra cross-reference com a nota 01.

Passo 1 — Camada 1 (Purpose)

system_name: ai_weekly
primary_job: gerar newsletter semanal sobre o que aconteceu em IA na semana
user: profissional de tech que quer ficar a par sem ler 200 tweets/dia
main_output: 1 newsletter em markdown com 5-7 itens (título, link, resumo de ~80 palavras, takeaway de 1 frase)
success_criteria:
  - 100% dos links abrem e apontam pra fonte primária
  - cada resumo passa em 30 segundos de leitura
  - takeaway revela a relevância sem clickbait
  - newsletter é entregue toda sexta às 9h
not_in_scope:
  - opinião editorial extensa
  - cobertura de tópicos fora de IA
  - notícias com >7 dias
  - threads inteiras de X reproduzidas

O not_in_scope é o que evita escopo elástico: o sistema vai rejeitar assuntos fora dessa caixa.

Passo 2 — Camada 7 (Workflow vs Agent)

Decisão: workflow, não agent.

Justificativa: o caminho é predizível — (1) coletar candidatos da semana, (2) filtrar relevância, (3) escrever resumos, (4) montar newsletter. Nenhum passo precisa de “descoberta dinâmica do próximo passo”. Agent aqui seria over-engineering — mais erro, mais custo, debug pior.

Forma concreta: prompt chaining (4 chamadas de LLM em sequência, cada uma com input estruturado da anterior). Padrão da Anthropic: “the path is fixed; chain LLM calls.”

Passo 3 — Camada 2 (Prompt Layer)

System prompt (versão 1.0):

role: editor sênior especializado em IA, com tom direto e cético
primary_job: curar, resumir e organizar avanços relevantes em IA da semana
primary_standard: relevância > volume — nunca preencha pra atingir N itens
allowed_actions:
  - resumir artigo/release/paper
  - destacar trade-offs e limitações
  - apontar discordâncias entre fontes
forbidden_actions:
  - especulação sobre roadmap não anunciado
  - linguagem promocional ("revolucionário", "game-changer")
  - extrapolação sem citar a fonte
uncertainty_behavior: marcar com [confiança: baixa] e citar limitação da fonte
reasoning_style: conciso; evidência antes de afirmação

Note: forbidden_actions aqui é aspiracional — esperamos que o modelo siga. A imposição real fica na Guardrail Layer.

Passo 4 — Camada 3 (Context Layer)

Context montado a cada execução semanal:

goal: gerar newsletter da semana de YYYY-MM-DD a YYYY-MM-DD
audience: profissional de tech sênior, segue IA mas não passa o dia no X
project_context: newsletter no ar há N semanas; tom estabelecido na edição #1
source_material:
  - feeds RSS de blogs oficiais (Anthropic, OpenAI, Google, Meta)
  - papers do arXiv (cs.CL, cs.AI, novos da semana)
  - 5 newsletters de referência (cita só, não copia)
preferences:
  - exemplos práticos preferidos a benchmarks abstratos
  - 1 item de paper, 1 item de produto, 1 item de "lado sombrio", o resto livre
constraints:
  - máximo 1200 palavras na newsletter inteira
  - orçamento: $5 por edição em chamadas de modelo
decision_history:
  - edição #12 cortou "tweet of the week" — engagement subiu
  - edição #18 testou tom mais opinativo — feedback negativo, revertido
known_failure_modes:
  - inflar releases de produto com hype
  - confundir paper preprint com peer-reviewed
  - perder release importante por falha de feed RSS

known_failure_modes no contexto força o modelo a se vigiar sobre esses pontos.

Passo 5 — Camada 4 (Output Layer)

primary_format: markdown
required_sections:
  - "## Esta semana em IA — [date]"
  - "### Em destaque" (1 item)
  - "### Releases" (1-2 itens)
  - "### Pesquisa" (1-2 itens)
  - "### Para refletir" (1 item — lado sombrio/crítico)
  - "### Curtas" (opcional, 0-2 itens)
confidence_level: opcional — emitir só quando <medium
uncertainty_flags:
  - "[confiança: baixa]" antes do resumo quando aplicável
  - "[fonte: preprint]" quando paper não é peer-reviewed
actionability: sugestão — newsletter é leitura, não ação automática

Cada item da newsletter segue schema interno:

{
  "title": "string, ≤80 chars",
  "url": "string, validado por requisição HEAD",
  "summary": "string, 60-100 palavras",
  "takeaway": "string, 1 frase ≤25 palavras",
  "confidence": "high|medium|low",
  "source_type": "official_blog|paper|news|preprint"
}

Passo 6 — Camada 5 (Retrieval Layer)

use_retrieval_when:
  - sempre — newsletter inteira depende de fontes da semana
source_hierarchy:
  - 1. blogs oficiais (Anthropic, OpenAI, Google, Meta, Mistral)
  - 2. arXiv (cs.CL, cs.AI, cs.LG)
  - 3. publicações estabelecidas (The Information, IEEE Spectrum)
  - 4. blogs/newsletters de referência (citar, não reproduzir)
citation_rule: toda claim factual no resumo cita link da fonte primária
conflict_rule: blog oficial > arXiv > terceiros; mais recente em caso de empate
missing_source_rule: se não há fonte primária verificável, item é descartado (não inventado)

Implementação: RSS readers + arXiv API + web search via tool. Indexação simples por data (não precisa vector DB — janela é só 7 dias).

Passo 7 — Camada 6 (Tool Layer)

available_tools:
  - name: fetch_rss
    when_to_use: coletar itens da semana de feeds conhecidos
    when_not_to_use: feeds não estão na allowlist
  - name: fetch_arxiv
    when_to_use: buscar papers novos da semana em categorias-alvo
    when_not_to_use: paper >7 dias
  - name: web_get
    when_to_use: ler conteúdo completo de URL específica
    when_not_to_use: URL fora dos domínios permitidos
  - name: validate_url
    when_to_use: confirmar que URL responde 200 antes de incluir
    when_not_to_use: nunca; sempre validar
allowed_without_approval:
  - fetch_rss, fetch_arxiv, web_get, validate_url
requires_approval:
  - send_newsletter (envio real pros assinantes)
forbidden:
  - tools de escrita em sistemas externos exceto envio aprovado
tool_failure_behavior: retry 2x com backoff exponencial; em falha definitiva, log e continua (newsletter pode sair com -1 item)

Passo 8 — Camada 8 (Evaluation Layer)

success_criteria: herda do Purpose Layer
scoring_rubric:
  accuracy: 1-5 (claims do resumo batem com a fonte?)
  completeness: 1-5 (cobre o que a newsletter prometeu?)
  usefulness: 1-5 (o leitor tira valor?)
  format_adherence: 1-5 (markdown válido, seções na ordem, schema dos itens?)
  source_quality: 1-5 (fonte primária ou terciária?)
  specificity: 1-5 (resumos concretos ou genéricos?)
  risk_control: 1-5 (sem hype, sem clickbait, sem PII?)
pass_threshold: média ≥4 e nenhuma dimensão <3
automatic_failure_conditions:
  - link quebrado em qualquer item
  - palavras-clichê de hype detectadas ("revolucionário", "muda tudo")
  - preprint marcado como peer-reviewed

Aplicação: LLM-as-judge roda em todos os candidatos antes da newsletter sair. Itens com nota <3 em qualquer dimensão são reescritos ou descartados. Newsletter inteira só sai se passar o threshold.

Dataset de regression: 20 edições anteriores anotadas, comparadas a cada mudança de prompt.

Passo 9 — Camada 9 (Guardrail Layer)

allowed_without_approval:
  - gerar drafts internos
  - chamar tools de leitura
requires_approval:
  - publicar newsletter (humano clica "enviar")
forbidden:
  - inclusão de URL não-validada
  - inclusão de claim sem fonte
  - reprodução >50 palavras de fonte de terceiros
must_flag:
  - confidence:low em qualquer item
  - item de fonte tier 4 (newsletter de terceiros)
  - dimensão da rubrica <3
must_stop_when:
  - custo da execução >$5
  - 3 chamadas de modelo falham em sequência
  - guardrail de hype dispara 3x no mesmo item
escalation_rule: pausa, registra trace, notifica owner via Slack

Implementação: middleware antes e depois da chamada do modelo, mais filtros no schema validator.

Passo 10 — Camada 10 (Logging Layer)

Por execução semanal, registra um trace com:

{
  "run_id": "uuid",
  "week_of": "2026-05-25",
  "prompt_version": "1.0",
  "models": ["claude-opus-4.7", "gpt-5"],
  "sources_consulted": [{ "url": "...", "fetched_at": "...", "status": 200 }],
  "candidates_collected": 47,
  "candidates_after_filter": 6,
  "tool_calls": [{ "name": "fetch_rss", "latency_ms": 230, "success": true }],
  "eval_scores": { "accuracy": 4.6, "format_adherence": 5, "...": "..." },
  "guardrails_triggered": [{ "name": "hype_detector", "item": 3, "action": "rewrite" }],
  "cost_usd": 3.47,
  "final_output_hash": "sha256:...",
  "human_approval": { "approved_by": "...", "approved_at": "..." }
}

Implementação: OpenTelemetry GenAI semantic conventions + Langfuse.

Passo 11 — Camada 11 (Improvement Layer)

review_cadence: após cada edição (curto) + revisão mensal (longo)
questions_per_review:
  - quais itens performaram melhor (open rate, cliques)?
  - quais resumos exigiram edição humana antes do envio?
  - quais guardrails dispararam — padrão?
  - mudou alguma fonte (atualizar source_hierarchy)?
artifacts:
  - changelog do system prompt (versionado em git)
  - dataset de regression atualizado com casos novos
  - novas regras de hype-detector quando palavra clichê passa
ownership: editor humano da newsletter; revisão mensal com time

Saída esperada: prompt_version sobe a cada 4-6 semanas; dataset de eval cresce; guardrails ficam mais finos.

Checklist final antes de produção

Antes de publicar pra primeiro grupo de assinantes:

  • Purpose Layer revisada com um stakeholder
  • Prompt Layer testada em 5 semanas históricas (replay)
  • Schema do Output Layer valida com jsonschema sem erros
  • Retrieval Layer tem allowlist de domínios fechada
  • Tool Layer com requires_approval cobrindo o envio
  • Evaluation Layer com dataset de regression e threshold
  • Guardrail Layer com kill switch de custo configurado
  • Logging Layer escrevendo em backend persistente
  • Improvement Layer com cadência agendada no calendário
  • Plano de rollback (versionado) caso a edição 1 falhe feio
    • Versão anterior do system prompt versionada em git e recuperável com um único comando (git revert, não edição manual sob pressão)
    • Critério objetivo de quando disparar o rollback (ex.: 2+ dimensões da rubrica <3 na primeira edição real, ou reclamação de assinante sobre claim errada)
    • Feature flag que pausa o envio sem quebrar o cron semanal — a newsletter falha em “não enviar”, nunca em “enviar errado”
    • Owner humano notificado automaticamente (mesmo canal do escalation_rule da Guardrail Layer) no instante em que o rollback é acionado, não só depois

Armadilhas comuns ao montar o stack completo

Construir na ordem errada

A tentação é começar pelo Prompt Layer — é a parte mais visível e divertida. Mas sem Purpose Layer fechada, o system prompt vira um documento sem critério de sucesso. Sem Output Layer definida, o prompt não sabe o que produzir. A ordem natural é Purpose → Workflow → Output → Prompt — não o contrário. Cada retrabalho de prompt gerado por Purpose indefinida custa mais do que o tempo de fechar o escopo antes.

Pular a Evaluation Layer porque "é óbvio quando está bom"

No sistema de newsletter, “está bom” é claramente definível — link válido, resumo de 80 palavras, sem hype. Mesmo assim, sem dataset e rubrica formal, você não detectará regressão quando trocar de modelo ou atualizar o prompt. O passo mínimo — 20 edições anteriores anotadas como dataset de regressão — leva 2 horas e evita meses de degradação silenciosa.

Colocar em produção sem Logging Layer

Sem o trace por execução, o primeiro incidente real (newsletter sai com link quebrado, item com hype passa, edição atrasada) vai ser investigado no escuro. Você tem o output final, mas não tem: qual versão do prompt estava ativa, quais candidatos foram descartados, qual guardrail disparou ou não disparou, qual foi o custo. Logging precisa estar ativo antes do primeiro assinante real, não depois do primeiro incidente.

Construir todas as camadas ao mesmo tempo antes de validar a Purpose Layer

É tentador abrir os 11 arquivos de config de uma vez e preencher tudo numa tarde — parece mais produtivo do que “perder tempo” só decidindo escopo. O problema é que cada camada downstream herda decisão da anterior: se o success_criteria do Purpose mudar depois (porque só ficou claro na prática que “100% dos links abrem” era exigente demais, por exemplo), a rubrica da Evaluation que você já escreveu, o forbidden_actions do Prompt e o schema do Output todos precisam ser revisitados — não porque estavam errados, mas porque foram construídos sobre uma premissa que mudou. O custo não é escrever a Purpose Layer de novo; é rastrear todo o resto que dependia dela. Valide a Purpose Layer com um stakeholder real — nem que seja uma conversa de 15 minutos — antes de escrever a segunda linha de qualquer outra camada.

Como explicar em inglês

This note walks through all 11 layers of the AI engineering stack applied to a concrete example: an automated AI newsletter generator. The key insight it demonstrates: the layers aren’t independent building blocks you can assemble in any order — they reference each other. The Purpose Layer’s success criteria become the Evaluation rubric. The Prompt Layer’s forbidden actions become the Guardrail’s enforcement rules. The Context Layer’s known failure modes become new guardrails after incidents. Building the stack means deciding in the right order: purpose, then architecture, then output contract, then prompt, then control layers.

In a technical interview, you might say:

“When I build an AI system end-to-end, I follow a specific construction order that isn’t the same as the logical dependency order. I start with Purpose — what does the system do, what’s out of scope, what’s the measurable success criteria. Then I make the architecture decision: workflow or agent. Only then do I define the output contract, because that’s what tells me what the prompt needs to require. The control layers — Evaluation, Guardrail, Logging — come after the happy path is defined. This order avoids rework: every time I’ve seen teams start with the prompt, they rewrite it three times because they didn’t know what it was supposed to produce.”

PTEN
Recipe completoEnd-to-end recipe
Ordem de construçãoBuild order
Camadas que se referenciamCross-referencing layers
Artefato versionadoVersioned artifact
Replay de semanas históricasHistorical replay
Dataset de regressãoRegression dataset
Schema de outputOutput schema
Allowlist de domíniosDomain allowlist
Aprovação humanaHuman approval / Human-in-the-loop
Plano de rollbackRollback plan

O que esta recipe demonstra

Três coisas que não aparecem olhando camada por camada:

  1. As camadas se referenciam. success_criteria do Purpose vira rubrica da Eval. forbidden_actions do Prompt vira regra real na Guardrail. known_failure_modes do Context vira guardrail novo após cada incidente.

  2. A ordem natural não é numérica. Construímos Purpose → Workflow → Output → Prompt+Context → Retrieval → Tool → Eval → Guardrail → Logging → Improvement. Pular pra Prompt Layer antes de fechar Purpose e Output é receita de retrabalho.

  3. Cada camada produz artefato versionado. Nada disso é “documento de design que ninguém vê”. É arquivo de configuração, schema, rubrica, prompt versionado — todos em git, todos com diff revisável.

O que vem a seguir

Esta trilha cobriu o blueprint: o que cada camada é, por que existe, e como as 11 conversam entre si. O próximo passo natural é aprofundar cada camada nas trilhas especializadas — onde cada conceito tem 8 a 12 notas dedicadas.

A ordem de aprofundamento sugerida para quem quer ir a produção:

  1. Evaluation — sem evals, você não tem sinal; é o que mais impacta a qualidade percebida
  2. RAG e Vector Databases — a Retrieval Layer é onde a maioria dos sistemas falha em produção
  3. Anatomia de Agents — se seu sistema for agentic, aqui está o detalhe de orquestração
  4. Segurança e Guardrails — pirâmide de validação, prompt injection, Llama Guard
  5. Observability — implementar o Logging Layer de verdade com OpenTelemetry
  6. Context Engineering — a Context Layer é mais rica do que parece
  7. Improvement Loop — fechar o ciclo operacional de melhoria contínua

Veja também

Fontes

Visão de gráfico

Backlinks