A Cidadela da Nuvem

[!NOTE] Status: Conteúdo pronto · Mídia: Capa gerada e ilustração SVG original · Última verificação: 2026-09-05
Capacidade principal: Delegar trabalho ao agente de nuvem do GitHub Copilot

[!TIP] Baixe este kit de aprendizado e use o guia de extração e configuração. Mantenha intacto o starter original.

---
config:
  theme: base
  look: classic
  themeVariables:
    darkMode: false
    background: "#ffffff"
    primaryColor: "#f5f5f5"
    primaryTextColor: "#111111"
    primaryBorderColor: "#555555"
    secondaryColor: "#e0e0e0"
    secondaryTextColor: "#111111"
    secondaryBorderColor: "#666666"
    tertiaryColor: "#bdbdbd"
    tertiaryTextColor: "#111111"
    tertiaryBorderColor: "#444444"
    lineColor: "#444444"
    textColor: "#111111"
    mainBkg: "#f5f5f5"
    nodeBorder: "#555555"
    clusterBkg: "#ffffff"
    clusterBorder: "#999999"
    edgeLabelBackground: "#ffffff"
    actorBkg: "#e0e0e0"
    actorBorder: "#555555"
    actorTextColor: "#111111"
    actorLineColor: "#777777"
    signalColor: "#333333"
    signalTextColor: "#111111"
    labelBoxBkgColor: "#f5f5f5"
    labelBoxBorderColor: "#777777"
    labelTextColor: "#111111"
    loopTextColor: "#111111"
    activationBkgColor: "#bdbdbd"
    activationBorderColor: "#555555"
    noteBkgColor: "#f5f5f5"
    noteTextColor: "#111111"
    noteBorderColor: "#777777"
    attributeBackgroundColorOdd: "#f5f5f5"
    attributeBackgroundColorEven: "#e0e0e0"
---
flowchart LR
    accTitle: Mapa de capacidades de A Cidadela da Nuvem
    accDescr: O kit local prepara o contrato. Ele não pode estabelecer a disponibilidade na nuvem nem provar que uma implementação foi executada remotamente.
    I["Issue e aceite"] --> P["Revisão de caminhos e autoridade"]
    P --> C["Sessão em nuvem autorizada"]
    C --> D["Diff, logs e verificações"]
    D --> H{"O mantenedor aceita?"}
    H -->|Não| I
    H -->|Sim| E["Decisão registrada"]

Legenda. A etapa na nuvem é uma execução ao vivo opcional; o losango de decisão continua sendo um limite de revisão humana.

Explicação. O kit local prepara o contrato. Ele não pode estabelecer a disponibilidade na nuvem nem provar que uma implementação foi executada remotamente.

Referências oficiais

Estas fontes oficiais são a autoridade sobre o comportamento e a disponibilidade do produto. Consulte-as novamente ao usar uma superfície diferente ou após uma atualização do produto.

• Sobre o GitHub Copilot cloud agent
• Iniciar sessões do cloud agent
• Riscos e mitigações do cloud agent

História

A Cidadela da Nuvem concede a um agente uma oficina efêmera. Uma missão segura chega com escopo, critérios de aceitação e um caminho para revisão humana.

A fantasia é um recurso de memorização; a lição de engenharia exige evidências observáveis e reproduzíveis.

Objetivos de aprendizagem

• Escreva uma tarefa do tamanho de um issue com caminhos permitidos, não objetivos e um comando de verificação.
• Diferencie validar um contrato de tarefa local de executar um agente na nuvem.
• Defina os logs, diff e verificações que um mantenedor precisa antes de aceitar um resultado remoto.

Pré-requisitos

Para preparar ferramentas e contas pessoais, conclua o guia de pré-requisitos. Para estudar somente pelo terminal, siga o fluxo via CLI no kit extraído; as evidências específicas do VS Code continuam separadas.

Limite de evidência: O verificador não executa node test/run.js nem atribui um issue real. Um exercício ao vivo precisa de um repositório com esse comando real e autorização separada.

Duração estimada da sessão: 45–75 minutos após os pré-requisitos; a duração real varia. Nunca use segredos de produção nem dados de clientes.

Explicação dos conceitos

O GitHub Copilot cloud agent pode trabalhar em tarefas atribuídas do repositório em um ambiente hospedado pelo GitHub e propor alterações por meio de um pull request. A elegibilidade, as políticas, o acesso a modelos, as ferramentas, o acesso à rede e a disponibilidade de funcionalidades variam. As pessoas continuam responsáveis pela definição e pela revisão da tarefa. A issue é um contrato executável e não deve conter segredos.

Caso de uso concreto

Um trabalhador na nuvem recebe um issue pequeno com escopo de origem e critérios de aceite. Um comando escrito em JSON é apenas uma verificação proposta até que um trabalhador autorizado realmente o execute.

Verificação de vocabulário

• Papel: Ask, Plan, Agent ou um agente personalizado.
• Harness/superfície: o runtime ou a superfície do produto em que um papel opera.
• Destino: o destino de sessão selecionado, como Local, Copilot ou Cloud, quando exposto.
• Ambiente: a pasta, worktree, máquina local, Codespace ou ambiente remoto.
• Instruções: contexto duradouro aplicado automaticamente.
• Prompt: um modelo de tarefa invocado manualmente.
• Skill: conhecimento especializado reutilizável, carregado quando relevante.
• Agente personalizado: um papel com instruções, ferramentas e transferências opcionais.
• MCP: Model Context Protocol.
• Evidência: um caminho, diff, resultado de comando, rastreamento ou decisão de revisão.

Fluxo de trabalho Ask → Plan → Agent

Ask — investigar

1. Identifique o resultado real esperado pelo usuário e a fonte de verdade atual.
2. Inspecione os arquivos, as instruções, as ferramentas, as permissões e as verificações existentes relevantes.
3. Cite caminhos concretos ou evidências da plataforma para cada descoberta importante.
4. Registre as incertezas e não deduza capacidades indisponíveis.

Ponto de controle: Nenhuma implementação antes de compreender o estado atual e as evidências.

Plan — projetar

1. Declare o escopo, o que está fora dele, as suposições, os riscos e os limites de confiança.
2. Selecione o mínimo necessário de papel, ferramentas, autoridade e ambiente.
3. Defina critérios de aceitação, comandos de verificação, revisão e restauração.
4. Sinalize qualquer dependência em versão prévia (Preview) ou experimental e forneça uma alternativa.

Ponto de controle: Outra pessoa em aprendizagem deve conseguir prever a conclusão a partir do plano.

Agent — executar

1. Faça a menor alteração reversível ou produza o artefato planejado.
2. Use ciclos curtos de inspecionar → alterar → verificar.
3. Preserve a saída dos comandos, o status de saída, os diffs, os rastreamentos ou os registros da plataforma.
4. Pare quando os critérios de aceitação forem atendidos; não faça limpezas sem relação com a tarefa.

Revisão — questionar

1. Inspecione o diff ou artefato completo.
2. Compare cada resultado com o plano e os critérios de aceitação.
3. Execute a verificação existente mais restrita e relevante, ampliando-a somente quando houver justificativa.
4. Registre as limitações e os riscos não resolvidos.
5. Avalie o trabalho com rubric.md.

Missão guiada

1. Prepare uma cópia isolada

1. Baixe e extraia o kit cloud-citadel para um novo diretório da unidade de trabalho.
2. Leia KIT-START.md na raiz dele. Abra starter/ como workspace do VS Code ao testar a descoberta, mas execute o verificador na raiz do kit.
3. Inspecione starter/task-contract.json e verify.js antes de editar.
4. Na raiz do kit extraído, execute node verify.js.
5. Registre a rejeição documentada do starter. Um runtime ausente ou uma falha não relacionada não é o resultado esperado do exercício.

2. Investigue e planeje

Comando da verificação inicial pronto para copiar, a partir da raiz do kit extraído:

node verify.js

Em Ask, solicite um rastreamento dos arquivos inspecionados e do que o verificador realmente observa. Questione qualquer afirmação sobre execução ao vivo que não esteja respaldada pela saída.

Use este prompt de planejamento:

Complete the goal, allowedPaths, acceptanceCriteria, local verification command and required evidence. Keep networkRequired false and add no credentials or deployment instructions.
Do not implement yet. Identify affected files, the negative case and a safe reset.

3. Implemente o recorte revisado

1. Aprove apenas o artefato starter nomeado e os testes focados necessários.
2. Peça a Agent para implementar um único recorte; inspecione os comandos propostos antes da execução.
3. Execute node verify.js novamente a partir da raiz do kit, ou node ../verify.js a partir de starter/.
4. Compare o resultado exato com o ponto de verificação abaixo e revise o diff completo.
5. Registre separadamente a descoberta do host ou a atividade ao vivo quando disponível. Não habilite serviços extras para fabricar um resultado aprovado.

[!IMPORTANT] Ponto de controle: A tarefa nomeia os dois diretórios exatos permitidos e a evidência que um revisor exigirá. O verificador não executa node test/run.js nem atribui um issue real. Um exercício ao vivo precisa de um repositório com esse comando real e autorização separada.

4. Comprove que uma verificação pode rejeitar um erro

Defina networkRequired como true no contrato copiado e confirme a rejeição. Restaure o contrato local delimitado.

Termine com a evidência de capacidade específica da aventura na rubrica, não apenas com a presença de um arquivo.

Falha intencional: O Decreto Real Vazio

Faça isso somente em um ambiente descartável:

Escreva apenas “melhore o projeto”. Não é possível determinar a conclusão porque faltam a intenção do produto, a tolerância a riscos e as exclusões.

Recuperação

Retorne a Ask, identifique o limite violado, restrinja o plano, remova autoridade ou contexto desnecessários e repita a menor verificação relevante. Documente a lição sobre a causa, em vez de apenas afirmar que a tentativa falhou.

Desafio independente

Prepare uma issue que altere código e documentação, mas proíba implantação, atualizações de dependências e limpeza sem relação com a tarefa.

Restrições:

• Não copie a missão guiada literalmente.
• Não adicione ferramentas, permissões ou recursos de nuvem sem uma necessidade declarada.
• Não faça alegações de qualidade, desempenho, compatibilidade ou disponibilidade sem evidências obtidas por execução.
• Mantenha a linguagem de fantasia subordinada à clareza técnica.

Lista de verificação de evidências

• Descobertas de Ask fundamentadas nas fontes.
• Plano aprovado com escopo, exclusões, riscos, verificações e restauração.
• Diff ou artefato de Agent limitado ao escopo declarado.
• Saída de verificação com comando, status ou registro da plataforma.
• Causa raiz da falha intencional e recuperação.
• Resultado do desafio independente.
• Limitações explícitas e notas sobre o status das funcionalidades.
• rubric.md preenchido.

Instruções de restauração

1. Salve seu diff, a saída do comando e as limitações do kit descartável.
2. Pare apenas o processo ou a sessão de aprendizagem que você iniciou. Não pare outros projetos.
3. Se você inicializou Git no kit, inspecione git status --short lá e restaure apenas os seus arquivos de exercício nomeados a partir da baseline local.
4. Caso contrário, extraia o ZIP original em um novo diretório não utilizado para outra tentativa; não sobrescreva seu trabalho atual.
5. Remova apenas configurações, worktrees ou recursos remotos pertencentes ao exercício depois de revisar o que vale a pena preservar.

A fonte do currículo e os demais projetos devem permanecer inalterados. Uma redefinição da cópia do kit não é um reset completo do repositório.

Próxima aventura

O Portal do Terminal