Phase 14 - Lesson 42

Projeto Final: Entregar um Pacote Reutilizável de Workbench de Agente

A minitrilha termina com um pacote que você insere em qualquer repositório. Onze lições de superfícies compactadas em um diretório que você pode copiar com cp -r e ter um agente funcionando de forma confiável na manhã seguinte. O projeto final é o artefato que valoriza este currículo.

Tipo: Construção Linguagens: Python (stdlib) Pré-requisitos: Fases 14 · 31 a 14 · 41 Tempo: ~75 minutos

Objetivos de Aprendizado

  • Empacotar as sete superfícies de workbench em um único diretório pronto para uso.
  • Fixar os esquemas, scripts e templates para que um novo repositório tenha uma linha de base conhecida e funcional.
  • Adicionar um único script instalador que configure o pacote de forma idempotente.
  • Decidir o que fica no pacote e o que fica de fora, defendendo a exclusão ou inclusão de cada um.

O Problema

Um workbench que vive em um Google Doc, no histórico de chat e em três scripts lembrados pela metade é um workbench que é reconstruído a cada trimestre. A cura é um pacote versionado: um repositório ou diretório com as superfícies, os esquemas, os scripts e um instalador de comando único.

Você terminará esta lição com o outputs/agent-workbench-pack/ gravado no disco e um bin/install.sh que o instala em qualquer repositório de destino.

O Conceito

flowchart TD
  Pack[agent-workbench-pack/] --> Docs[AGENTS.md + docs/]
  Pack --> Schemas[schemas/]
  Pack --> Scripts[scripts/]
  Pack --> Bin[bin/install.sh]
  Bin --> Repo[repositório de destino]
  Repo --> Surfaces[todas as sete superfícies de workbench conectadas]

A estrutura do pacote

outputs/agent-workbench-pack/
├── AGENTS.md
├── docs/
│   ├── agent-rules.md
│   ├── reliability-policy.md
│   ├── handoff-protocol.md
│   └── reviewer-rubric.md
├── schemas/
│   ├── agent_state.schema.json
│   ├── task_board.schema.json
│   └── scope_contract.schema.json
├── scripts/
│   ├── init_agent.py
│   ├── run_with_feedback.py
│   ├── verify_agent.py
│   └── generate_handoff.py
├── bin/
│   └── install.sh
└── README.md

O que fica dentro, o que fica fora

Dentro:

  • Esquemas das superfícies. Eles são o contrato.
  • Os quatro scripts acima. Eles são o ambiente de execução.
  • Os quatro documentos. Eles são as regras e a rubrica.

Fora:

  • Tarefas específicas do projeto. As tarefas pertencem ao quadro do repositório de destino, não ao pacote.
  • Chamadas de SDK de fornecedores. O pacote é agnóstico em relação a frameworks.
  • Prosa de integração (onboarding). O pacote vive ao lado da integração existente da equipe, não dentro dela.

O instalador

Um curto bin/install.sh (ou bin/install.py):

  1. Recusa-se a instalar sobre um pacote existente sem --force.
  2. Copia o pacote para o repositório de destino.
  3. Conecta o CI se um diretório .github/workflows/ existir.
  4. Imprime os próximos passos: preencher o quadro, definir comandos de aceitação, executar o script de inicialização.

Versionamento

O pacote carrega um arquivo VERSION. Alterações de esquema e mudanças de script que exigem migrações aumentam a versão major (maior). Alterações apenas na documentação aumentam o patch. O agent_state.json do repositório de destino registra com qual versão do pacote ele foi inicializado.

Construa

O code/main.py monta o pacote em outputs/agent-workbench-pack/ ao lado da lição, semeado com os esquemas e scripts das lições anteriores nesta minitrilha e os documentos que você já escreveu.

Execute-o:

python3 code/main.py

O script copia e fixa as superfícies, escreve o README, imprime a árvore do pacote e termina com sucesso (exit zero). A reexecução é idempotente.

Padrões de produção no mundo real

Um pacote só é valioso se sobreviver a bifurcações (forks), atualizações e a alterações inesperadas no repositório de origem (upstream hostil). Quatro padrões fazem isso funcionar.

VERSION é o contrato, não o marketing. Alterações maiores (major bumps) exigem uma migração de estado. Alterações menores (minor bumps) exigem uma reexecução do verificador. Alterações de correção (patch bumps) são apenas para documentação. O instalador escreve .workbench-version no repositório de destino a cada instalação; o lint_pack.py recusa-se a enviar se o arquivo de trava (lock) do destino discordar do VERSION do pacote. É assim que npm, Cargo e pyproject.toml sobrevivem a 10 anos de mudanças; nada nos agentes muda essas regras.

Fonte única para distribuição entre ferramentas. O Nx distribui um comando nx ai-setup que configura AGENTS.md, CLAUDE.md, .cursor/rules/, .github/copilot-instructions.md e um servidor MCP a partir de uma única configuração. O pacote deve fazer o mesmo; o instalador cria links simbólicos (ln -s AGENTS.md CLAUDE.md) para que uma única fonte de verdade se propague para todos os agentes de codificação. Fazer um fork do pacote para dar suporte a uma ferramenta em detrimento de outra é um padrão de falha.

uninstall.sh que recusa a desinstalação em caso de estado não trivial. Desinstalar o pacote não deve excluir os arquivos agent_state.json, task_board.json ou outputs/ do usuário. O desinstalador remove os esquemas, scripts, documentos e AGENTS.md (com a opção de exclusão --keep-agents-md) e recusa-se a prosseguir se os arquivos de estado tiverem alterações não salvas (uncommitted). O estado pertence ao usuário; o pacote não é dono dele.

Habilidade como publicável. Distribuição no estilo SkillKit. O pacote é distribuído como uma habilidade do SkillKit: skillkit install agent-workbench-pack o configura em 32 agentes de IA a partir de uma única fonte. O repositório do pacote é a fonte de verdade; o SkillKit é o canal de distribuição. O bloqueio de fornecedor (vendor lock-in) entra em colapso; as sete superfícies permanecem as mesmas.

Use-o

Três lugares onde o pacote é distribuído:

  • Como um diretório que você insere em um repositório. cp -r outputs/agent-workbench-pack /path/to/repo.
  • Como um repositório de template público. Faça um fork e personalize, com a VERSION controlando os desvios.
  • Como uma habilidade do SkillKit. Conectado ao seu produto de agente para que um único comando o instale.

O pacote é a receita. Cada instalação é uma porção.

Envie

O outputs/skill-workbench-pack.md gera um pacote ajustado ao projeto: regras refinadas com base no histórico da equipe, globs de escopo correspondentes ao repositório e dimensões de rubrica estendidas com uma entrada específica do domínio.

Exercícios

  1. Decida qual quinto documento opcional merece ser promovido ao pacote canônico. Defenda sua escolha.
  2. Reescreva o instalador em Python com uma flag --dry-run. Compare a ergonomia com o bash.
  3. Adicione um bin/uninstall.sh que remova o pacote com segurança e se recuse a fazê-lo se os arquivos de estado tiverem um histórico não trivial. O que conta como não trivial?
  4. Adicione um lint_pack.py que falhe quando o pacote se desviar da VERSION. Conecte-o ao CI do próprio repositório do pacote.
  5. Crie o manual de migração (runbook) de um workbench feito à mão para este pacote. Qual é a ordem das operações para minimizar o tempo de inatividade?

Termos-Chave

Termo O que as pessoas dizem O que realmente significa
Workbench pack "O kit inicial" Um diretório versionado contendo todas as sete superfícies
Installer "Script de configuração" bin/install.sh que instala o pacote de forma idempotente
Versão do pacote "VERSION" Alterações maiores para mudanças de esquema/script, de patch apenas para docs
Pacote drop-in "cp -r e pronto" O pacote funciona sem personalização por repositório no primeiro dia
Template bifurcável (forkable) "Template do GitHub" Repositório público a partir do qual a opção "Usar este template" do GitHub pode clonar

Leitura Adicional

0 lifetime access. Curriculum based on AI Engineering from Scratch by Rohit Ghumare (MIT, used under attribution).