Apêndices: modelos de trabalho e glossário · Engenharia de Software na Era da IA

AApêndice A

Contrato de uma tarefa para agentes

Copie para sua próxima tarefa delegada. Cada campo existe para remover uma ambiguidade que, de outra forma, seria adivinhada.

contrato-da-tarefa.txt

Problema e usuário:  Qual necessidade ou falha deve ser resolvida? Para quem? Resultado esperado:  Qual comportamento observável deve existir ao concluir? Contexto confiável:  Quais arquivos, documentos, contratos e exemplos devem orientar?  Qual versão ou estado inicial está em uso? Invariantes:  O que deve permanecer verdadeiro, inclusive sob falha? Escopo:  O que pode mudar? Que decisão ou acesso exige outro responsável? Evidência:  Como verificar comportamento, integração e consequências?  Quais riscos requerem casos específicos? Execução:  Quais recursos estão disponíveis? Qual orçamento e condição de parada?  Como registrar progresso e retomar a tarefa? Conclusão:  Entregar mudança, evidências vinculadas à versão, limites e pendências.

BApêndice B

Conteúdo de um mapa curto do repositório

O que um arquivo curto de orientação deve cobrir. O mapa deve apontar para os detalhes — replicar conteúdo em vários arquivos cria mais lugares para manter e reconciliar.

01

Propósito

O que o sistema faz e quais usuários atende.

02

Navegação

Onde estão os módulos, contratos e decisões relevantes.

03

Preparação

Como obter um ambiente reproduzível com dados apropriados.

04

Execução e validação

Comandos reais e mantidos para iniciar, testar e investigar.

05

Limites

Regras de dependência, segurança e alterações sensíveis.

06

Evidência

Como registrar resultados e identificar a versão validada.

07

Continuidade

Onde ficam estado de tarefas, decisões e problemas conhecidos.

CApêndice C

Registro de falha e melhoria do fluxo

Transforme cada falha recorrente em uma melhoria verificada do fluxo.

registro-de-falha.txt

Tarefa e configuração:Sintoma observado:Evidência reproduzível:Resultado esperado: Causa investigada:  requisito / contexto / ambiente / ferramenta / modelo / verificação / outra Intervenção escolhida:  mudança mínima que trata a causa Validação da intervenção:  caso que falhava; resultado atual; condições verificadas Conhecimento compartilhado:  teste, ferramenta, documento ou procedimento alterado Acompanhamento:  responsável; sinal de recorrência; condição para revisar ou remover a regra

EApêndice E

Glossário breve

O vocabulário do curso.

Tente adivinhar o significado e depois vire a carta.

Ler a seção completa do relatório originalO texto integral — com todas as fontes e nuances.

Os modelos abaixo foram elaborados para este relatório. Adapte-os ao tamanho e à consequência da tarefa; campos que não ajudam uma decisão podem ser removidos.

Apêndice A — Contrato de uma tarefa para agentes

Problema e usuário:
  Qual necessidade ou falha deve ser resolvida? Para quem?

Resultado esperado:
  Qual comportamento observável deve existir ao concluir?

Contexto confiável:
  Quais arquivos, documentos, contratos e exemplos devem orientar?
  Qual versão ou estado inicial está em uso?

Invariantes:
  O que deve permanecer verdadeiro, inclusive sob falha?

Escopo:
  O que pode mudar? Que decisão ou acesso exige outro responsável?

Evidência:
  Como verificar comportamento, integração e consequências?
  Quais riscos requerem casos específicos?

Execução:
  Quais recursos estão disponíveis? Qual orçamento e condição de parada?
  Como registrar progresso e retomar a tarefa?

Conclusão:
  Entregar mudança, evidências vinculadas à versão, limites e pendências.

Apêndice B — Conteúdo de um mapa curto do repositório

Informação	Conteúdo esperado
Propósito	O que o sistema faz e quais usuários atende.
Navegação	Onde estão os módulos, contratos e decisões relevantes.
Preparação	Como obter um ambiente reproduzível com dados apropriados.
Execução e validação	Comandos reais e mantidos para iniciar, testar e investigar.
Limites	Regras de dependência, segurança e alterações sensíveis.
Evidência	Como registrar resultados e identificar a versão validada.
Continuidade	Onde ficam estado de tarefas, decisões e problemas conhecidos.

O mapa deve apontar para os detalhes. Replicar todo o conteúdo em vários arquivos cria mais lugares para manter e reconciliar.

Apêndice C — Registro de falha e melhoria do fluxo

Tarefa e configuração:
Sintoma observado:
Evidência reproduzível:
Resultado esperado:

Causa investigada:
  requisito / contexto / ambiente / ferramenta / modelo / verificação / outra

Intervenção escolhida:
  mudança mínima que trata a causa

Validação da intervenção:
  caso que falhava; resultado atual; condições verificadas

Conhecimento compartilhado:
  teste, ferramenta, documento ou procedimento alterado

Acompanhamento:
  responsável; sinal de recorrência; condição para revisar ou remover a regra

Apêndice D — Revisão de uma entrega orientada por evidências

Use estas perguntas para localizar lacunas, ajustando a profundidade à mudança:

O resultado resolve o problema acordado?
As decisões de domínio estão explícitas?
A alteração preserva contratos e invariantes relevantes?
As evidências foram produzidas sobre a versão que será integrada ou implantada?
A verificação exercita os riscos importantes, inclusive falhas e concorrência quando aplicáveis?
Há diferenças relevantes entre o ambiente de teste e o de uso?
Os acessos, dependências e efeitos externos correspondem ao escopo autorizado?
O comportamento será observável e existe um caminho de recuperação?
O registro final distingue fatos verificados, hipóteses e pendências?
Alguma descoberta deveria melhorar o próximo ciclo de trabalho?

Apêndice E — Glossário breve

Termo	Significado neste relatório
Agente	Sistema que usa um modelo e ferramentas para avançar por etapas em uma tarefa.
Harness	Infraestrutura que organiza execução, ferramentas, estado e interação com o modelo.
Engenharia de contexto	Organização da informação necessária ao agente ao longo do trabalho.
Skill	Procedimento reutilizável com instruções e, quando necessário, recursos e scripts.
Eval	Avaliação estruturada do comportamento de um sistema de IA em tarefas definidas.
Oráculo	Critério ou mecanismo que permite julgar se um resultado está correto.
Invariante	Propriedade que deve permanecer verdadeira nas condições definidas do sistema.
Idempotência	Propriedade contratada que permite repetir uma operação sem acrescentar o efeito indesejado.
Outbox	Registro transacional de eventos a publicar posteriormente.
Prompt injection	Tentativa de fazer conteúdo recebido redirecionar indevidamente o comportamento do agente.
Sandbox	Ambiente com limites impostos à execução e ao acesso a recursos.
MCP	Model Context Protocol, usado para integrar aplicações de IA a ferramentas e fontes de contexto.
CI/CD	Automação de integração, validação e entrega ou implantação de mudanças.
Observabilidade	Capacidade de investigar o comportamento do sistema por sinais e evidências de execução.
Toil	Trabalho operacional repetitivo que pode ser reduzido por melhorias de engenharia.