Tema
CRP.AI Skill — Guia de Uso
Este guia descreve o uso da CRP.AI Skill em fluxos de trabalho com Azure DevOps.
1. Objetivo
A CRP.AI Skill organiza o ciclo de desenvolvimento ligado ao Azure DevOps. Ela apoia o registro de contexto, a criação de branch e Draft PR e a preparação da publicação.
Ela não substitui o trabalho de engenharia. A skill conduz o fluxo, registra decisões e executa integrações com o Azure DevOps; o colaborador continua responsável pelo entendimento do requisito, pela decisão técnica, pela implementação, pelos testes e pela qualidade da entrega.
As decisões de processo, os papéis de governança e os limites aplicáveis estão no Modelo de Governança do Desenvolvimento Assistido. O contexto e a justificativa das fases que este guia executa estão no Processo de Desenvolvimento Assistido.
2. O que a Skill Faz
Com a skill, você pode:
- Iniciar um novo desenvolvimento com branch e Draft PR criados após prévia e confirmação
- Planejar o escopo com perguntas guiadas antes de começar
- Entrevistar requisitos para esclarecer critérios, dependências e decisões antes da implementação
- Registrar definições em um documento vivo local
- Recomendar ativação de tarefas antes do handoff para o desenvolvimento externo
- Publicar PRs com descrição padronizada e work items vinculados
A skill também verifica condições importantes antes de alterar o Azure DevOps. Mudanças como publicação de PR e movimentação de work item exigem confirmação explícita do colaborador.
3. Quando Usar
Use a CRP.AI Skill quando o trabalho envolver itens do Azure DevOps, criação de branch, acompanhamento de requisitos, abertura de PR ou publicação de mudanças. Para tarefas fora desse fluxo, siga o processo do projeto.
Use especialmente quando houver:
- Requirement, User Story, Bug ou Task que precise ser vinculado à entrega
- Necessidade de criar branch e Draft PR a partir de um item do Azure DevOps
- Requisitos que precisam ser confirmados antes da implementação
- Publicação de PR com descrição padronizada e work items vinculados
4. Pré-requisitos
- OpenCode instalado e configurado via CRP.AI Installer
- MCP Azure DevOps corporativo configurado para o ambiente local
- Arquivo de ambiente do MCP com
AZURE_DEVOPS_ORG_URLeAZURE_DEVOPS_PAT, sem expor os valores - Repositório Git clonado localmente
O Installer oferece a configuração do MCP apenas quando há PAT provisionado e o colaborador confirma a operação. A skill usa o MCP corporativo e não deve recorrer a chamadas REST diretas, cabeçalhos PAT manuais ou implementações MCP alternativas.
5. Ciclo de Trabalho
A skill organiza as etapas abaixo para manter o fluxo rastreável e recuperável entre sessões. Ajustes ao processo do projeto devem ser confirmados antes de alterar artefatos no Azure DevOps.
| Etapa | Resultado esperado |
|---|---|
| Configuração | Projeto, repositório e branch destino definidos |
| Planejamento | Escopo confirmado antes de qualquer escrita no Azure DevOps |
| Início | Branch criada, Draft PR aberta e documento vivo iniciado |
| Verificação da Draft PR | Branch local e PR Draft confirmadas antes de continuar |
| Entrevista de requisitos | Dúvidas, critérios e decisões levantados com o colaborador |
| Handoff de definições | Definições confirmadas registradas no documento vivo |
| Ativação | Decisão sobre mover tarefas para Active antes do desenvolvimento externo |
| Handoff externo | Desenvolvimento conduzido pelo colaborador ou pelo método escolhido fora da skill |
| Publicação | PR atualizada, publicada e vinculada aos work items |
| Verificação | Artefatos criados ou alterados conferidos antes da conclusão |
6. Iniciar um Desenvolvimento
Para começar um novo desenvolvimento, abra o OpenCode no diretório do repositório e diga o que você precisa fazer. Exemplos:
- "Preciso implementar a US_5"
- "Vou corrigir o bug #1234"
- "Iniciar desenvolvimento da tarefa 5678"
A skill vai:
- Planejar fazendo perguntas sobre o escopo, repositório e tipo de entrega
- Exibir a prévia da branch e da Draft PR antes de criar artefatos no Azure DevOps
- Criar ou reutilizar a branch e abrir ou reutilizar uma Draft PR após confirmação
- Esclarecer requisitos e registrar as definições relevantes
- Registrar as definições no documento vivo em
.crp-ai/documents/
Ao final, você recebe o nome da branch, o link do Draft PR e a confirmação de que o setup e o esclarecimento inicial de requisitos foram concluídos. Antes do handoff, a skill apresenta a decisão de ativação. A implementação começa depois, fora da skill, com o método de desenvolvimento escolhido pelo colaborador.
7. Durante o Desenvolvimento
Enquanto você implementa:
- A skill organiza o processo, mas não substitui as decisões técnicas
- O Draft PR fica visível para seu time acompanhar o progresso
- Os artefatos do projeto no Azure DevOps e os documentos operacionais associados mantêm o registro das decisões
A skill recomenda a ativação antes do desenvolvimento externo. Se você recusar ou adiar, o fluxo continua e a decisão é registrada no documento vivo.
8. Publicar sua PR
Quando o código estiver pronto para revisão:
- Verifique se tudo foi commitado — a skill avisa se houver alterações pendentes
- Solicite a publicação dizendo "publicar PR" ou "finalizar desenvolvimento"
- Revise o link da Draft PR e confirme à skill que a revisão foi concluída
- A skill exibe uma prévia completa:
- Número da PR
- Branch de origem e destino
- Título e descrição que serão publicados
- Work items que serão vinculados
- Confirme a publicação
Após sua confirmação, a skill:
- Atualiza a descrição da PR
- Publica a PR (sai de Draft)
- Vincula os work items
- Atualiza o documento vivo
9. Artefatos do Fluxo
| Artefato | Função |
|---|---|
| Branch | Isola o trabalho da entrega em andamento |
| Draft PR | Dá visibilidade inicial sem abrir a revisão final |
| Documento vivo | Registra contexto, decisões, definições e progresso do fluxo |
| Comentários finais nos work items | Preservam decisões úteis para manutenção e planejamento futuro |
| PR publicada | Formaliza a entrega para revisão |
O documento vivo fica em .crp-ai/documents/ no repositório local. Ele não deve conter segredos, tokens, conteúdo de .env ou notas não relacionadas à entrega.
10. Exemplo de Fluxo Completo
11. Regras Importantes
- Siga as etapas aplicáveis do fluxo — cada fase registra informações necessárias para a publicação
- Revise a prévia antes de confirmar a publicação
- Não inclua IDs de work item nos títulos de PR
- Use português em títulos, descrições e comentários
- Commite antes de publicar — código não commitado bloqueia a publicação
- Envie a branch antes de publicar — a publicação exige branch remota atualizada
- Não publique sem duas confirmações — revise a Draft PR e confirme a prévia final
- Não registre segredos — PATs,
.enve credenciais não devem aparecer em comentários ou documentos
12. Problemas Comuns
| Situação | O que fazer |
|---|---|
| Skill não reconhece o work item | Verifique se o ID ou código US está correto e se você tem acesso no Azure DevOps |
| Erro ao criar branch | Verifique se o repositório está clonado e se você tem permissão de escrita |
| Draft PR não foi criada | Verifique a conectividade com o Azure DevOps e as credenciais MCP |
| Publicação bloqueada por código não commitado | Execute git status, faça commit das alterações relevantes e tente novamente |