Como configurar Comandos Personalizados no Cody usando .vscode/cody.json para padronizar prompts e geração de código no time

Quando equipes de engenharia passam a adotar assistentes de código com inteligência artificial em larga escala, surge rapidamente um gargalo de consistência: o abismo de maturidade na escrita de prompts. Enquanto arquitetos e desenvolvedores sêniores constroem instruções ricas em contexto e restrições de arquitetura, outros profissionais recorrem a comandos genéricos como "arrume este bug" ou "crie um teste". Essa disparidade fragmenta a base de código gerada: frameworks de testes misturados, convenções de nomenclatura divergentes, tratamento de erros inconsistente e perda das boas práticas acumuladas pelo time.

O Sourcegraph Cody resolve esse problema na raiz do projeto com o recurso de Comandos Personalizados (Custom Commands) configurados no arquivo .vscode/cody.json. Ao transformar templates de prompts testados, modos de execução e escopos de contexto em arquivos versionados ("Prompts as Code"), a liderança técnica estabelece uma infraestrutura reutilizável. Qualquer desenvolvedor que clonar o repositório terá acesso instantâneo a comandos de barra (slash commands) padronizados, garantindo qualidade consistente em geração de código, refatoração e testes.

Arquitetura do .vscode/cody.json

O Cody diferencia comandos salvos no perfil global do usuário de comandos em nível de espaço de trabalho (Workspace Level). Ao criar o arquivo cody.json na pasta .vscode/ na raiz do projeto, os comandos ficam atrelados diretamente à pilha tecnológica, dependências e padrões do repositório:

repository-root/
├── .vscode/
│   ├── cody.json          <-- Definição de comandos da equipe
│   └── settings.json
├── src/
├── tests/
└── package.json

Uma vez comitado no Git, a extensão do Cody no VS Code carrega automaticamente o arquivo ao abrir o projeto. Os desenvolvedores podem acessar os comandos pelo atalho da paleta (Option + C no macOS ou Alt + C no Windows/Linux) ou digitando diretamente comandos de barra (como /unit-test) no painel de chat do Cody.

Estrutura do esquema JSON

O arquivo .vscode/cody.json organiza os comandos sob a chave principal commands:

{
  "commands": {
    "command-identifier": {
      "prompt": "Template de instruções detalhadas enviado ao LLM.",
      "description": "Descrição curta exibida no menu de comandos do Cody.",
      "mode": "ask",
      "context": {
        "codebase": false,
        "selection": true,
        "currentDir": false,
        "openTabs": false
      }
    }
  }
}

Descrição dos atributos fundamentais:

Modos de execução: Controlando a entrega do resultado

O atributo mode determina a interação entre a resposta da IA e o editor de código:

1. ask (Consulta e revisão interativa):

   • Exibe a resposta no painel lateral do Cody Chat.
   • Ideal para auditorias de segurança, revisões de arquitetura, explicações de lógica e criação de resumos de Pull Requests, onde o desenvolvedor precisa validar os argumentos antes de aplicar o código.

2. edit (Substituição direta no código):

   • Aplica a resposta diretamente sobre a seleção ativa no editor, substituindo o trecho original.
   • Perfeito para refatorações pontuais: aplicação de tipagem estrita no TypeScript, remoção de condicionais aninhadas ou conversão para código imutável.

3. insert (Inserção direcionada):

   • Insere o conteúdo gerado imediatamente acima da seleção ou na posição atual do cursor.
   • Indicado para inclusão de blocos de documentação (como TSDoc/JSDoc) ou scaffold inicial de suites de testes em arquivos recém-criados.

Delimitação de contexto: Qualidade versus latência

Em ferramentas de geração de código, a falta de contexto gera alucinações, enquanto o excesso de arquivos irrelevantes satura a janela de tokens, encarece as chamadas e aumenta a latência de resposta. O bloco context oferece controle granular:

• selection (booleano): Passa as linhas atualmente selecionadas no editor. Para tarefas de refatoração ou documentação localizada, manter como true assegura foco estrito no trecho desejado.
• codebase (booleano): Ativa a busca semântica do Sourcegraph por todo o repositório indexado. Permite que o Cody identifique utilitários compartilhados, modelos de domínio e mocks em outras pastas. Deve ser desativado em edições puramente locais para evitar overhead de rede.
• currentDir (booleano): Inclui os arquivos vizinhos da pasta atual. Muito útil em projetos modulares onde estilos, componentes e fixtures de teste residem no mesmo diretório.
• openTabs (booleano): Coleta o conteúdo de abas abertas no editor. Útil ao lidar com implementações que tocam múltiplos arquivos, mas pode adicionar ruído caso abas não relacionadas estejam abertas.

Receitas práticas para times de engenharia

Abaixo está um modelo completo de .vscode/cody.json pronto para produção, com quatro comandos essenciais para projetos TypeScript e React:

{
  "commands": {
    "unit-test": {
      "description": "Gera testes unitários com Vitest, cobrindo mocks e casos de borda",
      "mode": "ask",
      "context": {
        "selection": true,
        "codebase": true,
        "currentDir": true,
        "openTabs": false
      },
      "prompt": "Você é um engenheiro sênior de automação de testes. Crie uma suíte de testes completa para o código selecionado utilizando Vitest e @testing-library/react quando aplicável.\n\nRegras rigorosas:\n1. Estruture os testes no padrão Arrange-Act-Assert (AAA).\n2. Reutilize fixtures e padrões de mock já existentes no repositório.\n3. Cubra fluxos principais, valores de borda, entradas nulas e rejeições assíncronas.\n4. Não importe bibliotecas externas não autorizadas; use os métodos nativos vi.fn() e vi.spyOn() do Vitest.\n5. Entregue código completo e pronto para execução, sem comentários de preenchimento como '// implemente aqui'."
    },
    "refactor-clean": {
      "description": "Refatora o código selecionado com TypeScript rigoroso e imutabilidade",
      "mode": "edit",
      "context": {
        "selection": true,
        "codebase": false,
        "currentDir": false,
        "openTabs": false
      },
      "prompt": "Refatore o bloco de código selecionado de acordo com padrões de Clean Code e TypeScript estrito:\n1. Mantenha intactos os contratos de API pública, assinaturas de método e comportamento em tempo de execução.\n2. Substitua o uso de 'any' por discriminated unions precisas ou generics tipados.\n3. Substitua mutações de estado por funções puras e atualizações imutáveis.\n4. Converta condicionais profundamente aninhadas em retornos antecipados (early returns).\n5. Retorne APENAS o código modificado, sem formatação markdown ao redor nem explicações adicionais."
    },
    "security-audit": {
      "description": "Verifica vulnerabilidades OWASP Top 10 e vazamento de dados no trecho selecionado",
      "mode": "ask",
      "context": {
        "selection": true,
        "codebase": true,
        "currentDir": false,
        "openTabs": false
      },
      "prompt": "Realize uma análise criteriosa de segurança no código selecionado.\n\nAvalie os seguintes vetores de risco:\n1. Falhas de injeção (SQL, NoSQL, comandos de sistema, templates ou XSS).\n2. Falhas de autenticação, controles de autorização ausentes e elevação de privilégio.\n3. Referências diretas a objetos inseguras (IDOR) e entradas de usuário sem validação.\n4. Chaves de API, senhas ou dados sensíveis (PII) expostos no código ou logs.\n5. Tratamento deficiente de exceções que possa expor rastreamento de pilha (stack trace).\n\nFormato de saída obrigatório: [Severidade: Alta/Média/Baixa] | [Problema] | [Linha Afetada] | [Correção Recomendada e Diff]."
    },
    "doc-api": {
      "description": "Gera documentação TSDoc/JSDoc estruturada para funções e interfaces",
      "mode": "insert",
      "context": {
        "selection": true,
        "codebase": false,
        "currentDir": false,
        "openTabs": false
      },
      "prompt": "Gere um bloco de documentação TSDoc profissional para a função ou interface selecionada:\n1. Adicione um resumo conciso de uma linha seguido da explicação do comportamento.\n2. Documente todas as tags @param com tipos precisos e descrições semânticas.\n3. Documente @returns especificando tipos e condições de retorno.\n4. Documente @throws com todos os erros ou exceções disparados.\n5. Inclua um bloco @example funcional e contextualizado.\n6. Formate a saída como um bloco JSDoc/TSDoc pronto para inserção logo acima do código."
    }
  }
}

Governança e evolução para a Prompt Library

Para manter a eficácia de longo prazo do .vscode/cody.json, as equipes de engenharia devem adotar boas práticas de ciclo de vida:

1. Prompts como código versionado (Prompts as Code)

Os comandos contidos em .vscode/cody.json são ativos de engenharia. Qualquer alteração ou nova instrução deve tramitar por Pull Requests com revisão técnica por pares. É recomendado incluir verificações de schema JSON na integração contínua (CI) para evitar erros de sintaxe que invalidem a extensão.

2. Gestão disciplinada do orçamento de contexto

Evite habilitar "codebase": true em todos os comandos. Em transformações de lógica pura, a busca no repositório inteiro só traz lentidão de rede e ruído semântico. Restrinja o contexto global para comandos que realmente dependem de referências cruzadas entre múltiplos módulos.

3. Integração com a Sourcegraph Prompt Library

Conforme a organização cresce e passa a gerenciar dezenas de repositórios independentes, manter múltiplos arquivos .vscode/cody.json pode gerar divergências de versão. A Sourcegraph disponibiliza a Prompt Library (Biblioteca de Prompts) no Sourcegraph Enterprise (e Cody para VS Code v1.30+).

Os times podem começar refinando seus prompts localmente em .vscode/cody.json. Quando amadurecidos, esses comandos podem ser promovidos para a Prompt Library central na interface web, permitindo categorização por tags, recomendação oficial por administradores (Promoted Prompts) e menções dinâmicas (@selection, @file, @repo) utilizáveis em múltiplos ambientes (VS Code e JetBrains).

Referências

• Cody for VS Code v1.16: More powerful custom commands plus Claude 3 models as the new default
• Cody for VS Code v1.30: Introducing prompts and the Prompt Library
• Top 5 tips for using Cody with React
• Prompts - Sourcegraph docs