O contexto de build do Jaime: engenharia de prompts como infraestrutura
Saiba como sistemas reproduzíveis, prompts versionados e skills compartilhadas sustentam o desenvolvimento agêntico confiável.
Resumo
Na era da IA agêntica, o gargalo para escalar projetos deixou de ser o volume de código e passou a ser a integridade do código. Para avançar na velocidade que a IA permite, sem introduzir atrito sistêmico, precisamos parar de tratar a IA como uma varinha mágica e começar a tratá-la como um motor de alta performance que exige uma pista perfeitamente calibrada.
-
Feche a lacuna: as equipes de engenharia estão se dividindo entre tradicionalistas de um lado e power users agênticos de alta velocidade do outro. Em apps de produção, sua infraestrutura precisa conectar os dois, criando um espaço compartilhado onde o rigor tradicional e a velocidade agêntica não apenas coexistam, mas fortaleçam uma à outra.
-
Aposte em sistemas reproduzíveis: um agente é tão bom quanto o seu ciclo de feedback. Se os seus testes não são reproduzíveis e o seu CI não tem um ciclo de feedback de alto sinal, os seus agentes estão voando às cegas.
-
Prompts como infraestrutura: pare de tratar suas melhores instruções de IA como conversas avulsas e efêmeras que desaparecem quando a sessão termina. Em vez disso, mova essas instruções de fluxos automatizados para um arquivo versionado, transformando o conhecimento tácito de cada pessoa em documentação executável que garante que todo membro da equipe consiga disparar os mesmos resultados de alta integridade, de forma confiável, em todo o projeto.
-
Migre para uma arquitetura baseada em Skills: o sucesso significa transformar seus fluxos de trabalho comprovados em Skills compartilhadas. Ao sair de prompts individuais e passar para Skills em nível de projeto, você oferece a toda a equipe um playbook padronizado e de alta integridade que os agentes podem executar automaticamente.
Recentemente, tenho refletido sobre o que significa, de fato, escalar um projeto de código aberto para uma nova onda de colaboradores. Estamos entrando em uma era em que a IA agêntica pode gerar código tão rapidamente que o simples volume deixa de ser o gargalo; o verdadeiro desafio passa a ser garantir que essa avalanche não comprometa nossas bases de código, nem nossos valores compartilhados como colegas de equipe. Muitas equipes estão se dividindo em um formato de haltere: programação manual tradicional de um lado e power users agênticos de alta velocidade do outro.
Para apps grandes, nossa infraestrutura precisa funcionar como a alça que conecta essas duas pontas do espectro, criando um espaço compartilhado onde o rigor tradicional e a velocidade agêntica não apenas coexistam, mas se fortaleçam mutuamente. Para escalar com eficiência, precisamos voltar aos fundamentos, ancorando nossos fluxos de trabalho nos princípios do desenvolvimento de software reproduzível. Para avançar na velocidade que essas ferramentas permitem, sem se afogar em dívida técnica ou em bases de código ilegíveis, nossos ambientes precisam oferecer um ciclo de feedback definitivo e de alto sinal.
Nesse contexto agêntico, a saúde do código-fonte é medida estritamente por testes que passam, métricas de cobertura determinísticas e análise limpa. Se esses fundamentos faltam, é como pedir a um motor de alta performance que dirija em velocidade máxima no escuro. É perfeitamente razoável, e muitas vezes responsável, sentir a necessidade de resistir a essas novas ferramentas se o ambiente não estiver pronto para elas.
O objetivo aqui não é forçar uma ferramenta em um projeto só pela velocidade; é construir os sensores digitais que nos permitem adotar essa nova velocidade com segurança. Mais importante: essa transição é sobre levar nossos colegas de equipe junto. A infraestrutura não deve ser uma barreira que separa os “power users de IA” do resto da equipe; ela deve ser o terreno comum onde todos se sentem confiantes. Ser um bom colega na era agêntica significa garantir que, embora nossos repositórios possam andar mais rápido, nossa cultura continue acolhedora. Construímos esses sistemas para que todos consigam avançar com confiança, garantindo que a “velocidade agêntica” seja um ganho para a equipe inteira, e não apenas um novo risco para um produto de software que já funciona.
No entanto, esses sensores digitais são tão confiáveis quanto o ambiente em que vivem. É por isso que precisamos ancorar nossa confiança nos sistemas de CI. Em um fluxo de trabalho verdadeiramente reproduzível, o CI é a única versão da realidade que importa; ele é o árbitro final para um agente que não tem a intuição humana. Se uma mudança não passa pelos portões automatizados, ela, na prática, não existe. Ao tratar o CI como um ciclo de feedback de alto sinal, removemos o gargalo humano da verificação manual e o substituímos por um portão reproduzível. Essa fonte absoluta de verdade permite escalar com mais responsabilidade, possibilitando que os agentes falhem rápido, iterem e, por fim, tenham sucesso sem comprometer a integridade do projeto nem a tranquilidade da equipe.
O pedido
Um acerto isolado de prompt é só sorte. A escala verdadeira vem de criar um volante de inércia: toda vez que você ou um colega voltar ao repositório, o agente deve estar mais capaz do que na última vez, porque a dívida de conhecimento foi quitada e transferida para um repositório compartilhado de prompts. Você está construindo uma memória institucional compartilhada, que não fica presa na cabeça de um único desenvolvedor.
Para tornar isso repetível para qualquer desenvolvedor da sua equipe, você precisa de uma biblioteca de instruções de prompt que funcione como documentação executável. Muitas equipes correm para criar arquivos globais de “config” e “rules”, mas eu acho que eles costumam levar a resultados inconsistentes: um agente pode “esquecer” uma regra ou aplicá-la no contexto errado. Como engenheiros que pensam cientificamente, devemos preferir eliminar variáveis. Ao controlar o prompt exato de uma tarefa específica, você garante que o agente tenha exatamente o que precisa para aquela tarefa, dentro do seu repositório. Fazer isso de forma intencional em um projeto é o que ajuda indivíduos e equipes a construir confiança genuína nessas novas ferramentas.
Apresentando os Agent Skills
No fim de 2025, a Anthropic introduziu os Agent Skills, um padrão aberto criado para fornecer a agentes de IA conhecimento especializado e modular. Em vez de apenas ferramentas genéricas, as Skills empacotam instruções e recursos juntos para garantir que tarefas complexas sejam executadas de forma consistente. Isso está avançando rápido: no início de 2026, muitas ferramentas já estão adicionando suporte ao padrão para permitir portabilidade entre plataformas.
-
Flexibilidade: você pode usar Skills com vários agentes, incluindo Antigravity, Cursor, Claude Code, Gemini CLI e VS Code, porque elas são um padrão aberto.
-
Conhecimento compartilhado: as Skills podem ser facilmente compartilhadas com colaboradores ou salvas em uma pasta do usuário para uso em vários projetos.
-
Fluxos de trabalho repetíveis: as Skills garantem que os agentes executem de forma consistente tarefas complexas e de várias etapas, orientando-os com passos procedimentais claros.
-
Recursos adicionais: as Skills podem incluir scripts, templates ou outros dados junto com as instruções.
-
Acesso sob demanda: quando as Skills são carregadas pela primeira vez, apenas os metadados entram no contexto do agente. Isso significa que as instruções específicas só são adicionadas ao contexto quando necessário, o que economiza tokens.
-
Manutenção da qualidade do código: a construção dessas Skills pode ser usada como um conjunto de ferramentas que ajuda os colaboradores a ter o contexto certo para montar PRs, testes e documentação de maior qualidade, seguindo as suas melhores práticas.
Documentação das principais ferramentas atuais que suportam Skills
Consulte a documentação da sua ferramenta para saber onde adicionar esses arquivos.
-
Antigravity — https://antigravity.google/docs/skills
-
Claude Code — https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
-
Gemini CLI — https://geminicli.com/docs/cli/skills/
-
VS Code — https://code.visualstudio.com/docs/copilot/customization/agent-skills
A anatomia de uma Skill eficaz
Para garantir que a sua biblioteca de Skills continue sendo um “Runbook para Robôs” e não apenas uma lista de sugestões, todo prompt desta coleção segue um conjunto rigoroso de boas práticas:
-
Estado conhecido e bom: antes que um agente toque em uma linha de código, ele deve verificar se os testes existentes passam e se o analisador está limpo. Se a base estiver rachada, o agente conserta a base antes de construir por cima dela.
-
Verificação acionável: ancore as instruções em comandos como
flutter test --coverageoudart fix --apply, para dar ao agente o feedback determinístico de que ele precisa para se corrigir sozinho. -
Escopo finito: para que o agente mantenha um contexto amplo e foco, os prompts são projetados com limites claros, mirando funções, arquivos ou lacunas de cobertura específicos. Isso garante que o agente se mantenha focado em um único objetivo, evitando o crescimento descontrolado do escopo e garantindo que a saída seja fácil de revisar.
-
O ciclo de relatório e revisão: o trabalho do agente termina com um resumo estruturado, não com um commit. Ao exigir que o agente explique suas mudanças e sugira uma mensagem de commit, sem de fato enviar código, mantemos o engenheiro humano no papel de tomador de decisão final.
Exemplo de Skill: preparar o trabalho atual para PR
---
name: pr-prep
description: Prepare current work for PR
---
## Prepare current work for PR: Verify Tests Passing and Cleanup
**Objective:** Verify the current test suite status with `flutter test`, clean up any temporary modifications, and harden test coverage for active files.
**Instructions:**
1. **Baseline:**
* Run `dart fix --apply` to apply automated fixes.
* Run `flutter analyze` to ensure no analysis issues.
* Run `flutter test` to establish the current passing state.
* Run `flutter test integration_test/app_test.dart` to verify integration integrity.
2. **Fix Failures:** If there are any test failures or analysis errors, investigate and resolve them. Prioritize fixing code over deleting tests.
3. **Cleanup:** Review any currently modified files (run `git status` or check the diff). Remove any:
* `print` / `debugPrint` statements.
* Unused imports.
* Commented-out code blocks.
* Temporary "hack" fixes that should be replaced with proper solutions.
4. **Verify & Expand:**
* For the files you touched or cleaned up, check if there are obvious edge cases missing from their unit tests. Add tests to cover these cases.
* Run `flutter analyze` again to ensure clean code.
* Run `flutter test` again to ensure cleanup didn't break anything.
* Repeat this step as necessary.
5. **Report & Review:**
* Summarize the cleanup status (e.g., "Tests passing, removed 3 debug prints").
* **Action:** Ask the user to review the changes closely to ensure no intended code was accidentally removed.
* **Do not commit or push.**
* Provide a suggested Git commit message (e.g., "Prepare for PR: Fix tests and remove debug code").
Exemplo de Skill: cobertura de testes de um único arquivo
---
name: single-file-test-coverage
description: Write a new test or modify an existing test
---
## Single File Test Coverage Improvement
**Objective:** Write a new single test file, or modify an existing file, to improve coverage for a specific target class.
**Instructions:**
1. **Identify Target:** Choose a single source file (Dart) in `lib/` that has low or no test coverage and is suitable for unit testing (e.g., utility classes, logic helpers).
3. **Establish Baseline:**
* Run `flutter analyze` to ensure validity.
* Run `flutter test` to ensure the project is stable.
* Run `flutter test --coverage` and check `coverage/lcov.info`.
4. **Implement/Update Test:** Create a new test file in `test/` or update the existing one. Focus on:
* Edge cases (null inputs, empty strings, boundary values).
* Branch coverage (ensure if/else paths are exercised).
* Mocking dependencies where necessary (using `mockito` or `mocktail`).
5. **Verify & Iterate:**
* Run the tests to ensure they pass.
* Run `flutter analyze` to ensure no regressions.
* If coverage is still low, **iterate a few times**: analyze missed lines/branches and add targeted test cases.
5. **Report & Review:**
* Summarize what was fixed/covered and report coverage progress (e.g., `X% -> Y%` for `<filename>`).
* **Action:** Ask the user to review the new tests closely.
* **Do not commit or push.**
* Provide a suggested Git commit message (e.g., "Improve test coverage for [Class Name]").
Exemplo de Skill: migrar para os recursos modernos do Dart
---
name: migrate-to-modern-dart-features
description: Migrate to modern Dart features (Dart 3+)
---
## Migrate to Modern Dart Features
**Objective:** Optimize consistency and conciseness by migrating to modern Dart features (Dart 3+).
**Candidates for Migration:**
* `if-else` chains -> `switch` expressions.
* Data classes with manual `==`/`hashCode` -> `Records` or `equatable` (or class modifiers).
* Null checks -> pattern matching.
**Instructions:**
1. **Baseline:** Run `flutter test` and `flutter analyze`.
2. **Select Target:** Identify a *single* migration opportunity.
3. **Constraint:** Keep the change extremely small (**max 50 lines**).
4. **Migrate:** Refactor to use the new feature.
5. **Verify:**
* Run `flutter analyze`.
* Run `flutter test` to ensure no regressions.
6. **Report & Review:**
* Summarize the migration.
* **Action:** Ask the user to review the changes closely.
* **Test Location:** Explicitly state where in the app the user should go to manually test the change (e.g., "Click the bottom button after the app opens").
* **Do not commit or push.**
* Provide a suggested Git commit message (e.g., "Refactor: Use switch expression in [Class Name]").
Em resumo
O jogo longo da era agêntica não é sobre o volume de código que você produz hoje; é sobre arquitetar com responsabilidade a infraestrutura e as expectativas culturais dos repositórios de amanhã. Ao construir a alça do haltere, garantimos que, à medida que nossas ferramentas avançam mais rápido, elas continuem ancoradas em nossos valores compartilhados e no rigor técnico.
Em um futuro muito próximo, os agentes deixarão de ser assistentes reativos para se tornar colaboradores proativos, verificando o seu repositório e resolvendo issues enquanto você dorme. Ao fortalecer seus ciclos de feedback de alto sinal e documentar seus fluxos de trabalho em um conjunto de Skills versionado, você não está apenas economizando tempo; está treinando os agentes do futuro para respeitar a sua arquitetura específica, a sua visão e os seus padrões. Mais importante: você está garantindo que, à medida que o motor do desenvolvimento acelera, toda a sua equipe tenha os sensores digitais e o conhecimento compartilhado para avançar com confiança coletiva e uma cultura de engenharia mais forte e resiliente.