Um promptware é uma unidade de agente autocontida que armazena as suas próprias instruções, memória (Memory), permissões de ferramentas (Tools) e histórico de execução (Logs) na forma de arquivos, e que revisa as suas instruções e memória após cada execução. No Ivy Tendril, cada etapa do ciclo de vida do plano, desde a criação de um rascunho até a abertura de uma pull request, é executada por uma dessas unidades. As instruções são arquivos versionados no repositório, permitindo que sejam revisadas, comparadas via diff, revertidas e compartilhadas com toda a equipe como qualquer outro arquivo de código-fonte. Este artigo explica a estrutura de uma unidade, o loop de execução (run loop), os sete promptwares integrados e os dois modos de falha que exigem atenção.

O que uma unidade de promptware contém

Uma unidade de promptware é um diretório composto por quatro partes. Cada parte possui uma função específica.

Parte	Conteúdo	Quem escreve
`Program.md`	As instruções seguidas pelo agente na sua etapa. Revisadas pelo agente após a execução, avaliadas por humanos.	Agente e humanos
`Memory/`	Aprendizados persistentes sobre a base de código e as convenções da equipe. Incrementado após cada execução.	Agente
`Tools/`	As permissões delimitadas para esta etapa: quais comandos, arquivos e integrações o agente pode utilizar.	Humanos
`Logs/`	O histórico de execução: o que o agente leu, executou e alterou, além das conclusões que obteve.	Agente (apenas inclusão)

O Program.md é escrito em prosa, não em código. Uma seção para uma unidade de execução de planos poderia ser assim:

## Antes de abrir uma pull request

- Execute `pnpm lint` e `pnpm test` a partir da raiz do repositório. Não abra uma PR se algum comando falhar.
- Mantenha o diff estritamente limitado aos arquivos definidos no plano. Se outro arquivo precisar ser alterado, justifique na descrição da PR.
- Utilize o formato de mensagem de commit `type(scope): summary`.

Um registro de memória documenta algo que o agente aprendeu, que não é óbvio a partir do código e que execuções futuras devem conhecer:

### 2026-08-21, plano #412

O módulo de faturamento em `src/billing/` não possui testes. Adicione testes antes de refatorá-lo.
O comando `pnpm test` executa as migrações de banco de dados primeiro; uma execução leva cerca de quatro minutos em um checkout limpo.

Os dois arquivos diferem em sua própria essência. O programa especifica o que fazer. A memória define o que é fato sobre este repositório. Mantê-los separados permite que um revisor aprove um novo fato sem precisar aceitar uma mudança de procedimento, e vice-versa.

O loop de execução

Toda execução de promptware segue os mesmos quatro passos.

Carregar o programa. O agente lê o Program.md e as permissões definidas em Tools/. Nada fora dessas permissões fica disponível para ele.
Ler a memória. O agente lê o diretório Memory/ para que fatos aprendidos em execuções anteriores estejam presentes no contexto antes de iniciar o trabalho.
Executar a tarefa. O agente realiza o trabalho da etapa: elaborar um plano, detalhá-lo, executá-lo em um worktree ou abrir uma pull request. Cada chamada de ferramenta e sua respectiva saída são registradas em Logs/.
Refletir e atualizar. O agente compara o resultado obtido com o que o programa previa. Novos fatos são gravados em Memory/. Se uma instrução estiver incorreta, incompleta ou redundante, o agente revisa o Program.md.

Esse ciclo de agir, observar o resultado e revisar a próxima instrução é o padrão descrito no artigo sobre ReAct para agentes de raciocínio; um promptware difere principalmente pelo fato de que a revisão é gravada em um arquivo que sobrevive ao término da sessão. Esse quarto passo é o que faz com que as instruções evoluam ao longo do tempo em vez de se degradarem. É também o passo que exige maior supervisão humana, conforme detalhado na seção sobre riscos.

Os promptwares integrados

O Ivy Tendril vem de fábrica com sete promptwares, um para cada etapa do ciclo de vida descrito em da issue do GitHub à pull request. Cada um possui seu próprio programa, memória, permissões e logs.

CreatePlan: transforma uma ideia, uma issue do GitHub ou um relatório de bug em um rascunho de plano: objetivo, escopo, arquivos afetados e etapas de verificação.
ExpandPlan: acrescenta detalhes a um rascunho que não possui informações suficientes para ser executado, como critérios de aceitação pendentes ou decisões de design em aberto.
UpdatePlan: reescreve um rascunho com base nas anotações e comentários adicionados inline pelo desenvolvedor.
SplitPlan: divide um plano cujo escopo se expandiu demais em vários planos menores que podem ser executados em paralelo.
ExecutePlan: executa o plano aprovado com o agente de programação escolhido (Claude Code, Codex CLI, Copilot CLI, Gemini CLI, OpenCode ou qualquer agente via CLI) dentro de uma git worktree isolada. As melhores práticas do Claude Code da Anthropic trazem os mesmos argumentos a favor de arquivos de instruções versionados que esta seção sustenta para o Program.md.
CreatePr: abre a pull request após o diff ser aprovado na verificação automatizada e na revisão humana.
CreateIssue: cria uma issue no GitHub a partir de uma recomendação ou constatação identificada durante a execução.

Como cada unidade é isolada, a memória do CreatePlan (por exemplo, "a equipe exige que os planos identifiquem os arquivos de teste que serão alterados") não é compartilhada com o ExecutePlan, e a permissão do ExecutePlan para executar comandos de shell não é concedida ao CreatePlan. A documentação de promptwares lista o conteúdo padrão de cada unidade.

Instruções versionadas e os dois riscos

Por que arquivos no repositório superam prompts ad hoc

Um prompt informal digitado em uma janela de chat existe uma única vez, para uma única pessoa, e desaparece ao fim da sessão. Um arquivo Program.md versionado no repositório oferece quatro vantagens fundamentais que um prompt não possui:

Revisão. Uma alteração no programa se torna um diff em uma pull request. Um engenheiro sênior pode rejeitar uma instrução indesejada como "pular testes quando a alteração for pequena" antes que ela impacte qualquer execução futura.
Diff. Se a qualidade da saída mudar, o git log no diretório do promptware mostra exatamente qual instrução mudou e quando.
Rollback. Uma revisão problemática é revertida com um único commit.
Compartilhamento. Todos os desenvolvedores da equipe e todas as execuções de agentes utilizam as mesmas instruções. Uma convenção descoberta em uma execução na segunda-feira é aplicada por todos na terça-feira.

Este é o mesmo raciocínio que levou a infraestrutura de configurações manuais para código sob controle de versão, e a mesma premissa por trás da separação entre configuração e código no The Twelve-Factor App; ele se sustenta exatamente pelas mesmas razões. Outras formas de estruturar o trabalho dos agentes e a comparação com o promptware são abordadas em padrões de orquestração de agentes para desenvolvimento.

Risco 1: desvio de instruções (instruction drift)

Um agente com permissão para editar seu próprio programa também pode piorá-lo. Uma execução que falhe por causa de um teste intermitente (flaky) pode acrescentar a regra "tentar novamente testes que falharem até três vezes", o que ocultará um bug real na próxima oportunidade. Dois fatores contêm esse risco. Primeiro, o programa é um arquivo versionado, logo qualquer revisão gera um diff visível que o revisor pode inspecionar e reverter. Segundo, o diretório Logs/ registra a execução que gerou a alteração, permitindo ao revisor checar se o raciocínio é válido antes de aprovar a modificação.

Risco 2: inchaço de memória (memory bloat)

Uma memória que apenas cresce torna-se um custo sem benefício. Um arquivo com 400 registros, metade deles desatualizada, consome tokens a cada execução e torna difícil encontrar informações úteis. Duas práticas a mantêm eficiente: atribuir data e escopo a cada entrada, como no exemplo acima, facilitando a identificação de registros obsoletos; podar durante a revisão: quando um plano toca determinada área do código, o revisor checa as entradas de memória relacionadas e remove o que o código não reflete mais. O rastreamento de custos e tokens por plano e por job torna esse crescimento visível, pois uma unidade com memória inchada apresenta um consumo crescente de tokens sem aumento equivalente no tamanho do plano — e é por isso que a medição de taxa de transferência de agentes de código monitora o custo por pull request mergeada em vez de custo por execução isolada.

Como começar

Instale o Ivy Tendril, abra um repositório e crie um plano. Os sete promptwares integrados já estão disponíveis desde a primeira execução.

curl -sSf https://cdn.ivy.app/install-tendril.sh | sh

No Windows, execute irm https://cdn.ivy.app/install-tendril.ps1 | iex. Leia os arquivos Program.md antes de rodar uma execução e analise as primeiras entradas de memória e revisões de programa com o mesmo cuidado dedicado a uma revisão de código. Após cerca de dez planos, a memória refletirá as partes do código onde o agente encontrou dificuldades — que normalmente são os mesmos pontos onde um engenheiro humano também teria dúvidas. A documentação de promptwares traz mais informações sobre as unidades integradas.

Perguntas frequentes

O agente altera o Program.md sem avisar?

O agente revisa o seu programa após o encerramento da execução. Como o Program.md é um arquivo sob controle de versão, a revisão aparece como um diff que você pode ler, aceitar ou reverter, e o log da execução que a motivou fica salvo ao lado do arquivo.

Posso criar meus próprios promptwares?

As sete unidades integradas cobrem as fases centrais do ciclo de vida. Seus programas, memórias e permissões de ferramentas são arquivos de texto puro, permitindo que você os edite livremente para atender às convenções da sua equipe. Consulte a documentação para conhecer as opções atuais de extensão.

Onde a memória e os logs ficam armazenados?

Localmente, na própria máquina em que o Tendril está em execução. Eles nunca são enviados para os servidores da Ivy. As únicas chamadas de rede realizadas pelo Tendril destinam-se à API de LLM configurada por você e ao GitHub.

Primeiros passos com o Ivy Tendril

Pronto para a orquestração paralela de agentes em nível de engenharia?

Explore o código: Confira o Ivy Tendril no GitHub (Código aberto).
Consulte a documentação: Encontre guias de integração em tendril.ivy.app.
Agende uma sessão técnica: Entre em contato pelo e-mail renco@ivy.app para uma consultoria de arquitetura de 30 minutos.

Promptware: agentes que mantêm e aprimoram as próprias instruções