Skip to content

Commit 68dd0b1

Browse files
soterocrasoterocra
committed
adiciona artefatos de demo
1 parent fbf82c8 commit 68dd0b1

3 files changed

Lines changed: 326 additions & 0 deletions

File tree

‎.github/skills/issue-to-brief/SKILL.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
name: issue-to-brief
3+
description: Analisa uma issue do GitHub e transforma em um briefing tecnico acionavel para este projeto Spring Boot. Use quando o pedido mencionar issue, ticket, backlog, bug, feature, requisito ou criterios de aceite vindos do GitHub, especialmente antes de implementar com custom agents. Ajuda a ler a issue via MCP, identificar impacto no codigo, preservar contrato HTTP e preparar handoff para refatoracao e testes.
4+
---
5+
6+
# Skill issue-to-brief
7+
8+
Conduza a etapa de entendimento e preparacao antes da implementacao.
9+
10+
## Fluxo
11+
12+
1. Ler a issue e, se existirem, comentarios, checklist, labels e criterios de aceite via GitHub MCP.
13+
2. Resumir o objetivo funcional em linguagem direta.
14+
3. Separar fatos confirmados de inferencias.
15+
4. Mapear impacto provavel no codigo deste repositorio.
16+
5. Destacar invariantes observaveis que nao devem mudar.
17+
6. Preparar um handoff explicito para o custom agent de refatoracao.
18+
7. Preparar um handoff explicito para o custom agent de testes.
19+
20+
## Estrutura de saida obrigatoria
21+
22+
Responder com estas secoes, nesta ordem:
23+
24+
```text
25+
Resumo da issue
26+
- Objetivo:
27+
- Contexto:
28+
- Criterios de aceite:
29+
30+
Escopo confirmado
31+
- O que precisa mudar:
32+
- O que nao foi pedido:
33+
34+
Impacto provavel no codigo
35+
- Controller:
36+
- Service:
37+
- Repository:
38+
- Entity:
39+
- DTO:
40+
- Util/Exception:
41+
- Testes existentes relacionados:
42+
43+
Invariantes e restricoes
44+
- Contrato HTTP a preservar:
45+
- Headers relevantes:
46+
- Estrutura de sucesso e erro:
47+
- Restricoes tecnicas:
48+
49+
Pontos em aberto
50+
- Duvidas:
51+
- Suposicoes adotadas:
52+
53+
Handoff para refactor
54+
- Arquivos ou classes candidatas:
55+
- Resultado esperado:
56+
- Cuidados obrigatorios:
57+
58+
Handoff para test
59+
- Classes a validar:
60+
- Cenarios minimos:
61+
- Evidencias esperadas:
62+
```
63+
64+
## Heuristicas para este repositorio
65+
66+
Ao analisar impacto provavel, considerar primeiro:
67+
68+
- `src/main/java/br/com/devsuperior/dev_xp_ai/controller`
69+
- `src/main/java/br/com/devsuperior/dev_xp_ai/service`
70+
- `src/main/java/br/com/devsuperior/dev_xp_ai/repository`
71+
- `src/main/java/br/com/devsuperior/dev_xp_ai/entity`
72+
- `src/main/java/br/com/devsuperior/dev_xp_ai/dto`
73+
- `src/main/java/br/com/devsuperior/dev_xp_ai/exception`
74+
- `src/main/java/br/com/devsuperior/dev_xp_ai/util`
75+
- `src/test/java/br/com/devsuperior/dev_xp_ai`
76+
77+
## Regras
78+
79+
1. Nao comecar implementando.
80+
2. Nao inventar requisito ausente na issue sem marcar como suposicao.
81+
3. Se a issue tocar endpoint existente, explicitar que path, verbo, status code, headers e JSON observavel devem ser preservados salvo pedido explicito em contrario.
82+
4. Se a issue estiver incompleta, registrar as lacunas antes do handoff.
83+
5. Sempre produzir handoff utilizavel pelos custom agents `refactor` e `test`.
84+
85+
## Como preparar o handoff para os agents
86+
87+
Para o `refactor`:
88+
89+
- dizer qual comportamento deve ser criado ou alterado
90+
- listar classes e pacotes provaveis
91+
- destacar contrato HTTP e restricoes de persistencia
92+
- apontar riscos de regressao
93+
94+
Para o `test`:
95+
96+
- listar classes alteradas ou provaveis
97+
- informar cenarios de sucesso e erro
98+
- cobrar validacao de status, body, headers e cobertura
99+
100+
## Resultado esperado
101+
102+
Um bom resultado reduz ambiguidade da issue e deixa a implementacao pronta para seguir, com contexto suficiente para o agent de refatoracao atuar primeiro e o agent de testes atuar em seguida.

‎.github/skills/pr-summary/SKILL.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
name: pr-summary
3+
description: Gera um resumo tecnico final de implementacao pronto para demonstracao, comentario de pull request ou fechamento de tarefa. Use quando o trabalho ja tiver sido implementado e testado, especialmente apos usar custom agents de refatoracao e testes. Ajuda a consolidar mudancas, comandos executados, cobertura, riscos, relacao com a issue e proximos passos sem omitir evidencias.
4+
---
5+
6+
# Skill pr-summary
7+
8+
Conduza a etapa final de fechamento tecnico depois da implementacao e da validacao.
9+
10+
## Objetivo
11+
12+
Produzir um resumo final consistente, auditavel e facil de apresentar.
13+
14+
## Fluxo
15+
16+
1. Reunir o contexto da issue original.
17+
2. Reunir o que foi alterado no codigo de producao.
18+
3. Reunir o que foi alterado nos testes.
19+
4. Consolidar comandos executados e seus resultados relevantes.
20+
5. Consolidar cobertura, quando disponivel.
21+
6. Registrar riscos, limitacoes e pendencias.
22+
7. Fechar com uma relacao explicita entre issue, implementacao e validacao.
23+
24+
## Estrutura de saida obrigatoria
25+
26+
Responder com estas secoes, nesta ordem:
27+
28+
```text
29+
Resumo final
30+
- Issue:
31+
- Objetivo entregue:
32+
33+
Implementacao
34+
- O que mudou:
35+
- Principais classes afetadas:
36+
- Decisoes tecnicas relevantes:
37+
38+
Testes e validacao
39+
- Testes criados ou ajustados:
40+
- Comandos executados:
41+
- Resultado dos testes:
42+
- Cobertura JaCoCo:
43+
44+
Contrato e riscos
45+
- Contrato HTTP preservado ou alterado:
46+
- Riscos e limitacoes:
47+
- Pendencias:
48+
49+
Pronto para PR
50+
- Resumo curto para PR:
51+
- Relacao com a issue:
52+
```
53+
54+
## Regras
55+
56+
1. Nao afirmar execucao, cobertura ou sucesso de testes sem evidencia no contexto.
57+
2. Separar claramente fato observado de inferencia.
58+
3. Se nao houver cobertura disponivel, dizer explicitamente.
59+
4. Se a issue tiver criterios de aceite, dizer como cada um foi atendido ou o que ficou pendente.
60+
5. Se houve mudanca de contrato HTTP, explicitar de forma objetiva e concreta.
61+
62+
## Fechamento curto para demonstracao
63+
64+
Quando fizer sentido, terminar com um bloco curto de resumo executivo contendo:
65+
66+
- objetivo da issue
67+
- o que foi implementado
68+
- como foi validado
69+
- se esta pronto para revisao/PR
70+
71+
## Resultado esperado
72+
73+
Um bom resultado deixa a demo com um encerramento claro: contexto da issue, implementacao feita, testes executados, cobertura reportada e riscos remanescentes.

‎DEMO.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# Demo: GitHub Copilot + MCP + Skills + Custom Agents
2+
3+
Este material foi escrito para quem está assistindo à demonstração.
4+
5+
## O que está acontecendo nesta demo
6+
7+
Nesta apresentação, uma issue do GitHub é usada como ponto de partida para uma implementação real dentro deste projeto. Em vez de depender de um único comando genérico, o fluxo foi dividido em etapas com responsabilidades claras.
8+
9+
O objetivo é mostrar como diferentes mecanismos do GitHub Copilot podem trabalhar juntos:
10+
11+
- `GitHub MCP` traz o contexto externo da issue
12+
- a skill `issue-to-brief` transforma esse contexto em um briefing técnico
13+
- o custom agent `refactor` implementa a mudança no código de produção
14+
- o custom agent `test` valida o resultado com testes automatizados
15+
- a skill `pr-summary` organiza o fechamento técnico da execução
16+
17+
## Conceitos principais
18+
19+
### MCP
20+
21+
O MCP funciona como uma ponte entre o agente e sistemas externos. Nesta demo, ele é usado para acessar as informações da issue no GitHub sem depender de cópia manual para o prompt.
22+
23+
### Skill
24+
25+
Uma skill não é o componente que executa a mudança no código. Ela serve para orientar o raciocínio do agente em uma etapa específica do fluxo.
26+
27+
Nesta demo, duas skills são usadas:
28+
29+
- `issue-to-brief`: organiza a issue em um briefing técnico acionável
30+
- `pr-summary`: consolida o resultado final em um resumo claro e rastreável
31+
32+
### Custom agent
33+
34+
Um custom agent é um especialista com instruções próprias para um tipo de tarefa.
35+
36+
Nesta demo, há dois:
37+
38+
- `refactor`: cuida da implementação no código de produção
39+
- `test`: cuida da validação por meio de testes automatizados
40+
41+
## Fluxo da demonstração
42+
43+
### 1. A issue é lida e entendida
44+
45+
A primeira etapa não é alterar código. Primeiro, o sistema lê a issue do GitHub e organiza o problema em termos técnicos.
46+
47+
### 2. O problema vira um briefing técnico
48+
49+
Depois de ler a issue, a skill `issue-to-brief` transforma o conteúdo em algo mais útil para desenvolvimento.
50+
51+
Esse briefing normalmente destaca:
52+
53+
- objetivo da mudança
54+
- critérios de aceite
55+
- impacto provável no código
56+
- riscos de regressão
57+
- partes do contrato HTTP que devem ser preservadas
58+
59+
### 3. A implementação vai para um especialista em código
60+
61+
Com o briefing pronto, o trabalho segue para o custom agent `refactor`.
62+
63+
Esse agent foi configurado para atuar especificamente em refatoração e implementação de código de produção, com foco arquitetural e com menor risco de regressão.
64+
65+
### 4. A validação vai para um especialista em testes
66+
67+
Depois da implementação, a tarefa segue para o custom agent `test`.
68+
69+
Isso mostra que testes não foram tratados como uma consequência opcional da implementação. Eles entram como uma etapa própria, com foco próprio e com critérios objetivos de validação.
70+
71+
### 5. O resultado final é consolidado
72+
73+
Por fim, a skill `pr-summary` organiza um fechamento técnico da execução.
74+
75+
Esse fechamento conecta:
76+
77+
- a issue original
78+
- o que foi alterado no código
79+
- o que foi validado em testes
80+
- riscos, limitações e pendências
81+
82+
## Prompts usados na apresentação
83+
84+
Os prompts abaixo são os que serão usados durante a demonstração.
85+
86+
### Prompt 1: Ler a issue e gerar o briefing
87+
88+
```text
89+
Leia a issue #2 do repositorio devsuperior/ia-java-spring-2026 via GitHub MCP.
90+
91+
Use a skill `issue-to-brief` #file:.github/skills/issue-to-brief/SKILL.md para transformar a issue em um briefing técnico acionável para este projeto
92+
```
93+
94+
### Prompt 2: Implementar com o agent de refatoração
95+
96+
```text
97+
Agora implemente a issue com o custom agent `refactor`, seguindo o briefing gerado.
98+
99+
Preserve o contrato HTTP existente, faça mudanças incrementais e ao final entregue a lista de classes que precisam ser analisadas pelo agent de testes.
100+
```
101+
102+
### Prompt 3: Validar com o agent de testes
103+
104+
(altere o agente antes de executar o prompt)
105+
```text
106+
Agora use o custom agent `test` para criar ou ajustar os testes necessários com base nas classes listadas pela etapa anterior.
107+
108+
Execute os testes relevantes, informe os comandos executados, o resultado e a cobertura JaCoCo quando disponível.
109+
```
110+
111+
### Prompt 4: Gerar o fechamento final
112+
113+
Antes faça:
114+
- altere a branch para `feature/tabela`
115+
- git add e git commit das mudanças
116+
- git push
117+
118+
```text
119+
Use a skill `pr-summary` #file:.github/skills/pr-summary/SKILL.md para gerar o fechamento técnico desta execução.
120+
O commit e push já foi feito, mapeie a branch atual e seguida para próxima tarefa.
121+
Faça o PR dessa branch para a main, usando via GitHub MCP, usando o resumo curto gerado e referenciando a issue #2.
122+
```
123+
124+
## O que observar durante a apresentação
125+
126+
Durante a demo, vale prestar atenção em cinco sinais:
127+
128+
1. O sistema primeiro entende a issue antes de alterar qualquer arquivo.
129+
2. O contexto da tarefa vem do GitHub, não de uma descrição manual resumida.
130+
3. A responsabilidade é distribuída entre skill e custom agents.
131+
4. O teste aparece como etapa de validação, não como detalhe opcional.
132+
5. O fechamento final conecta problema, implementação e evidências.
133+
134+
## Estrutura usada no repositório
135+
136+
Os arquivos mais relevantes para esta demonstração são:
137+
138+
- `.github/agents/refactor.agent.md`
139+
- `.github/agents/test.agent.md`
140+
- `.github/skills/issue-to-brief/SKILL.md`
141+
- `.github/skills/pr-summary/SKILL.md`
142+
- `ISSUE-SEPARAR-USUARIO-EXPERIENCIA.md`
143+
144+
## Resultado esperado
145+
146+
Ao final da apresentação, a expectativa é que fique claro que:
147+
148+
- o MCP traz contexto externo de forma integrada
149+
- skills ajudam a organizar e orientar o fluxo
150+
- custom agents permitem especialização por responsabilidade
151+
- implementação e validação podem ser encadeadas de forma mais disciplinada

0 commit comments

Comments
 (0)