Engenharia de workspace
Trate o workspace como um produto para a pessoa que o utiliza. Projete o processo que torna o trabalho útil repetível, não apenas o prompt que gera um bom resultado.
A questão central: O que esta pessoa ainda precisa lembrar, reparar ou explicar que o workspace deveria tratar?
O caso de uso principal é escrever código com agentes. Proponha ativamente um processo de desenvolvimento, incluindo o que está faltando no workspace atual; não pare apenas em descrever instruções existentes. Para funções não técnicas, adapte os mesmos princípios de feedback e aceitação para suas entregas.
1. Estabeleça a função
Inferir o modo solicitado a partir das palavras do usuário:
- Revisão: inspecione o processo atual, explique lacunas e recomende melhorias. Deixe a implementação inalterada.
- Construir ou melhorar: implemente o escopo solicitado, incluindo validação e uma transferência utilizável. Uma solicitação de construção já autoriza implementação reversível comum; não adicione uma cerimônia de aprovação de plano.
Comece com a evidência que existir: repositório, documento de processo ou relato do usuário. Um repositório não é necessário para descoberta de processo. Leia as instruções aplicáveis do repositório antes de inspecionar a implementação ou executar comandos. Inspecione scripts de configuração antes de executá-los. Preserve o trabalho existente e siga o layout canônico de skill/instrução do alvo.
Identifique a função principal, tarefa recorrente, resultado aceitável, dor atual e decisões humanas. Use descoberta para entrevistas, documentos de processo ou responsabilidade incerta. Leia o material disponível primeiro, depois faça apenas perguntas cujas respostas mudam o design. Continue o trabalho independente enquanto espera; não invente uma resposta ausente.
2. Rastreie uma tarefa completa
Escolha uma solicitação representativa e acompanhe-a desde a entrada até a execução, validação, transferência e recuperação. Inclua uma falha ou correção se houver evidência. Para revisões amplas, amostre cada fluxo de trabalho materialmente diferente em vez de afirmar que uma amostra cobre tudo.
Registre o que o usuário faz, o que o agente faz, quais ferramentas atuam, qual estado é salvo e o que prova a conclusão. Compare a prática pretendida com a implementação e o comportamento observado. Mantenha esses rótulos de evidência distintos:
- Documentado: uma regra ou processo diz que isso deve acontecer.
- Implementado: um mecanismo concreto existe e está integrado ao caminho.
- Observado: uma execução demonstra o comportamento para uma revisão ou artefato nomeado.
- Desconhecido: evidência ou acesso está faltando. Isso não é prova de ausência.
Use revisão para examinar o caminho e priorizar descobertas. Um teste verde é evidência do que ele afirmou, não de toda alegação anexada a ele.
3. Projete a melhoria
Leia o processo base nos modos de revisão e construção. Use seus padrões de desenvolvimento de software, a menos que a tarefa seja não técnica; nesse caso, use sua orientação de adaptação. Para workspaces mistos, aplique a linha de base de codificação a código e auxiliares, mesmo quando o usuário final for não técnico.
Torne o processo proposto concreto: gatilho, etapas, comandos ou ferramentas, critérios de aprovação/reprovação, resposta a falhas, proprietário e evidência de conclusão. Mapeie cada item aplicável da linha de base para um mecanismo existente, uma alteração recomendada, uma exceção explícita ou um desconhecido. Explique desvios materiais; não omita silenciosamente uma prática ausente porque o repositório nunca a teve. Preserve requisitos existentes mais rigorosos.
Agrupe sintomas por sua causa subjacente. Prefira um utilitário compartilhado, melhor entrada, contrato de ferramenta mais claro ou procedimento mais curto em vez de adicionar outro aviso para o agente lembrar. Remova instruções e verificações redundantes apenas quando seu propósito for preservado em outro lugar.
Para cada alteração proposta, especifique:
| Campo | Resposta |
|---|---|
| Problema do usuário | O que fica mais lento, falha ou exige explicação repetida? |
| Evidência | Qual arquivo, etapa do processo, incidente ou execução apoia a descoberta? |
| Mudança | O que o workspace fará de diferente? |
| Posicionamento | Conhecimento, skill, regra, ferramenta, verificação local, gate remoto ou decisão humana? |
| Prova | Como saberemos que a mudança funciona, incluindo um caso de falha relevante? |
| Compensação e proprietário | Quanto custa para executar ou manter, e quem pode alterar a política? |
Priorize por impacto no usuário, recorrência, confiança, esforço e atraso de feedback. Lidere com as poucas mudanças que valem a pena fazer primeiro, não uma pontuação ou uma pilha de texto padrão. Use padrões quando um exemplo concreto ou layout de workspace ajudar.
4. Revise ou implemente
Para uma revisão, entregue o processo atual em resumo, o processo de trabalho proposto, descobertas priorizadas com evidência e o próximo passo útil. Preserve mecanismos existentes fortes e declare o que não pôde ser verificado. Uma revisão apenas de documento de processo deve distinguir controles propostos de controles conhecidos por existir.
Para uma construção ou melhoria, use construir. Implemente o escopo autorizado de ponta a ponta. Se o usuário quiser um novo workspace, mas a função ou entrega ainda for desconhecida, resolva isso antes de escolher a stack. Não transforme todo problema de processo em um projeto de software.
5. Feche o loop
Relate o que mudou ou foi recomendado, como isso ajuda a função, o que foi realmente verificado e o que permanece dependente de acesso ou julgamento humano. Para implementação, deixe uma maneira clara de iniciar o fluxo de trabalho e uma maneira de executar suas verificações.
Mantenha os limites operacionais explícitos:
- Nunca faça uma verificação com falha passar enfraquecendo o critério, ignorando o hook ou aceitando evidência ausente. Uma mudança legítima de política deve ser identificada separadamente e autorizada por seu proprietário.
- Preserve a autorização já concedida; distinga uma construção local de gastar créditos, publicar ou alterar sistemas ativos. Resolva permissão apenas em uma ação que realmente precise.
- Não prescreva mesclagem automática, ausência de revisão de código, uma porcentagem fixa de cobertura, desenvolvimento orientado a testes ou um sistema de CI específico como a definição de um workspace.
- Mantenha segredos e detalhes de fontes privadas fora das instruções reutilizáveis. Quando o material de origem for privado, extraia o padrão com exemplos neutros.