Pular para conteúdo

ADR-003 — Prompt As Code — prompts versionados em repositório Git

Status: ✅ Aceito Data: 2026-06-10

Contexto

Os agentes de IA do AMia (Visão, Arquitetura, Design, Story Mapping, Codificação, QA) são guiados por prompts de sistema. Na fase inicial da plataforma, esses prompts eram armazenados em arquivos locais (config/roles/*.md) dentro do repositório do Agents, exigindo redeploy de containers a cada alteração.

Este modelo apresentou os seguintes problemas: - Alterações de prompt requeriam ciclo completo de CI/CD (build, push, deploy) - Sem rastreabilidade de quem alterou o que e quando - Impossível testar um prompt sem deployar o container - Rollback de prompt = rollback do container inteiro

Decisão

Adotar o princípio Prompt As Code: prompts armazenados em repositório Git dedicado (amIA-PromptAsCode), publicados automaticamente no AMia Core via pipeline CI/CD, e consumidos pelos agentes em runtime via HTTP.

Fluxo implementado

amIA-PromptAsCode (repo Git)
    → PR com revisão humana
    → merge na branch principal
    → pipeline Azure DevOps
    → POST /api/v1/prompts/{key}/versions (AMia Core)
    → agentes consomem via GET /api/v1/prompts/{key} em runtime

Justificativa

  • Prompts tratados como artefatos de código: revisão via PR, histórico de commits, blame, diff legível
  • Alterações entram em vigor sem redeploy — agentes carregam o prompt mais recente a cada request
  • Rollback trivial: revert de commit → pipeline republica versão anterior
  • Auditoria completa: Core armazena hash SHA-256 de cada versão para verificação de integridade

Consequências

Positivas: - Ciclo de iteração de prompt de ~20 minutos (redeploy) para ~2 minutos (pipeline) - Rastreabilidade total: quem, quando, o quê e por quê (via PR description e commit message) - Múltiplos ambientes (dev/staging/prod) com versões de prompt independentes

Negativas: - Requer pipeline adicional por repositório de prompts - Equipe precisa entender o fluxo PR → pipeline → Core antes de editar prompts - Latência mínima adicionada em cada request dos agentes (GET /api/v1/prompts/{key}) — mitigada por HybridCache no Core