Cuando las organizaciones de ingeniería implementan asistentes de codificación con IA en sus equipos, a menudo se encuentran con una marcada brecha de adopción. Mientras que los arquitectos e ingenieros sénior formulan instrucciones estructuradas y conscientes de los límites arquitectónicos, otros desarrolladores tienden a escribir indicaciones ambiguas como "corrige este error" o "crea una prueba". Esta falta de homogeneidad genera código dispar: pruebas unitarias con librerías incompatibles, divergencias en el manejo de errores, inconsistencias de estilo y una escasa capitalización de las mejores prácticas internas.
Sourcegraph Cody ofrece una solución nativa para solventar esta disparidad en el repositorio: los comandos personalizados (Custom Commands) configurados mediante .vscode/cody.json. Al integrar plantillas de prompts probadas, modos de ejecución y límites precisos de contexto en un archivo versionado, los líderes técnicos pueden convertir el diseño de prompts en infraestructura compartida ("Prompts as Code"). Cualquier desarrollador que clone el repositorio adquiere de inmediato comandos con barra diagonal listos para usar, garantizando un estándar uniforme de generación, refactorización y pruebas en toda la base de código.
Arquitectura y funcionamiento de .vscode/cody.json
Cody clasifica los comandos personalizados en dos niveles: de usuario (guardados globalmente en la configuración del editor) y de espacio de trabajo (Workspace Level). Al almacenar cody.json dentro de la carpeta .vscode/ en la raíz del proyecto, los comandos quedan vinculados a las dependencias, herramientas y directrices específicas del repositorio:
repository-root/
├── .vscode/
│ ├── cody.json <-- Definición de comandos de equipo
│ └── settings.json
├── src/
├── tests/
└── package.json
Cuando este archivo se confirma en Git, la extensión de Cody en VS Code lo detecta y analiza automáticamente al abrir el espacio de trabajo. Los desarrolladores pueden ejecutar los comandos mediante el atajo de la paleta de comandos (Option + C en macOS o Alt + C en Windows/Linux) o escribiendo el comando correspondiente (como /unit-test) directamente en el cuadro de chat de Cody.
Estructura del esquema JSON
El archivo .vscode/cody.json se organiza en torno a un objeto principal denominado commands, donde cada clave actúa como el identificador del comando:
{
"commands": {
"command-identifier": {
"prompt": "Plantilla de instrucciones enviada al modelo de lenguaje subyacente.",
"description": "Descripción breve mostrada en el menú de comandos de Cody.",
"mode": "ask",
"context": {
"codebase": false,
"selection": true,
"currentDir": false,
"openTabs": false
}
}
}
}
Propiedades fundamentales de cada comando:
| Campo | Tipo | Descripción |
|---|---|---|
prompt | String | Instrucción base enviada al modelo de lenguaje. Define el rol, restricciones técnicas, criterios de prueba y formato de salida. |
description | String | Resumen explicativo que aparece en la paleta de Cody para orientar a los desarrolladores sobre el propósito del comando. |
mode | String | Modo de interacción y destino del resultado generado (ask, edit o insert). |
context | Object | Ajustes detallados que controlan la información del código fuente que Cody recopila automáticamente para alimentar el prompt. |
Modos de ejecución: Control de la entrega de código
La propiedad mode define cómo interactúa la respuesta del modelo con el editor de código:
-
ask(Consulta y revisión interactiva):- Envía la respuesta al panel lateral de Cody Chat.
- Adecuado para revisiones de seguridad, explicaciones conceptuales de algoritmos, auditorías de arquitectura o resúmenes de PR, donde se requiere la inspección humana previa.
-
edit(Modificación en el lugar):- Reemplaza directamente el bloque de código seleccionado en el archivo activo.
- Ideal para refactorizaciones directas: fortalecimiento de tipos en TypeScript, eliminación de ternarios anidados o adopción de patrones inmutables.
-
insert(Inserción en la posición actual):- Introduce el contenido generado inmediatamente arriba o en la posición del cursor/selección activa.
- Perfecto para generar bloques de documentación (como TSDoc/JSDoc) o crear la estructura inicial de una suite de pruebas en un archivo nuevo.
Delimitación del contexto: Calidad frente a latencia
En los asistentes de código, la escasez de contexto produce alucinaciones, mientras que un exceso de información irrelevante satura la ventana de contexto, eleva los tiempos de respuesta y diluye la atención del modelo. El bloque context permite ajustar estos límites:
selection(booleano): Pasa las líneas de código actualmente seleccionadas en el editor. Para tareas locales de refactorización o documentación, activar esta opción garantiza que el modelo se enfoque en el fragmento deseado.codebase(booleano): Activa la búsqueda semántica e indexación de Sourcegraph en todo el repositorio. Permite a Cody localizar utilidades compartidas, tipos de dominio y configuraciones de prueba en otros directorios. Debe deshabilitarse en transformaciones aisladas para evitar latencia innecesaria.currentDir(booleano): Incluye los archivos situados en el mismo directorio que el archivo activo. Resulta muy útil en arquitecturas modulares donde los componentes, estilos y datos de prueba conviven en una misma carpeta.openTabs(booleano): Pasa el contenido de las pestañas abiertas en el editor. Resulta práctico para flujos de trabajo con múltiples archivos relacionados, aunque puede incorporar ruido en tareas independientes.
Recetas prácticas para equipos de ingeniería
A continuación se muestra un archivo .vscode/cody.json listo para producción, configurado con cuatro comandos estándar para proyectos TypeScript/React:
{
"commands": {
"unit-test": {
"description": "Genera pruebas unitarias estándar con Vitest, mocks y cobertura de casos límite",
"mode": "ask",
"context": {
"selection": true,
"codebase": true,
"currentDir": true,
"openTabs": false
},
"prompt": "Actúa como un ingeniero sénior de automatización de pruebas. Diseña una suite de pruebas completa para el código seleccionado utilizando Vitest y @testing-library/react cuando aplique.\n\nReglas obligatorias:\n1. Organiza cada prueba bajo el patrón Arrange-Act-Assert (AAA).\n2. Respeta las convenciones de fixtures y mocks ya existentes en el repositorio.\n3. Cubre casos de éxito, valores límite, entradas nulas o indefinidas y rechazos asíncronos.\n4. No importes bibliotecas de mock no autorizadas; usa vi.fn() y vi.spyOn() nativos de Vitest.\n5. Genera código completo y listo para ejecutar, sin comentarios de relleno como '// implementar aquí'."
},
"refactor-clean": {
"description": "Refactoriza el código seleccionado aplicando TypeScript estricto e inmutabilidad",
"mode": "edit",
"context": {
"selection": true,
"codebase": false,
"currentDir": false,
"openTabs": false
},
"prompt": "Refactoriza el bloque de código seleccionado siguiendo principios de código limpio y TypeScript estricto:\n1. Mantén intactos los contratos de API pública, firmas de funciones y el comportamiento en tiempo de ejecución.\n2. Reemplaza tipos 'any' por uniones discriminadas precisas o restricciones genéricas.\n3. Sustituye patrones de estado mutable por funciones puras y actualizaciones inmutables.\n4. Convierte anidamientos condicionales profundos en cláusulas de retorno anticipado (guard clauses).\n5. Devuelve ÚNICAMENTE el código modificado, sin explicaciones ni bloques de markdown adicionales."
},
"security-audit": {
"description": "Audita el código seleccionado en busca de vulnerabilidades OWASP Top 10 y fuga de datos",
"mode": "ask",
"context": {
"selection": true,
"codebase": true,
"currentDir": false,
"openTabs": false
},
"prompt": "Realiza una auditoría exhaustiva de seguridad sobre el código seleccionado.\n\nVerifica los siguientes vectores de riesgo:\n1. Vulnerabilidades de inyección (SQL, NoSQL, comandos de sistema, plantillas o XSS).\n2. Fallos de autorización, control de acceso roto y elevación de privilegios.\n3. Referencias directas inseguras a objetos (IDOR) y falta de validación de entradas.\n4. Claves de API, credenciales o datos personales expuestos en código o registros.\n5. Manejo incorrecto de excepciones que exponga el rastreo de pila interno.\n\nFormato de salida obligatorio: [Severidad: Alta/Media/Baja] | [Vulnerabilidad] | [Línea afectada] | [Sugerencia de corrección y Diff]."
},
"doc-api": {
"description": "Inserta documentación TSDoc estandarizada para funciones o interfaces",
"mode": "insert",
"context": {
"selection": true,
"codebase": false,
"currentDir": false,
"openTabs": false
},
"prompt": "Genera un bloque de documentación TSDoc profesional para la función o interfaz seleccionada:\n1. Escribe un resumen conciso de una línea seguido de los detalles de funcionamiento.\n2. Declara todas las etiquetas @param con tipos exactos y descripciones claras.\n3. Declara @returns detallando el tipo de retorno y sus condiciones.\n4. Declara @throws listando cada error o excepción posible.\n5. Agrega un bloque @example funcional representativo.\n6. Genera el resultado en formato JSDoc/TSDoc listo para ser insertado justo encima del código."
}
}
}
Gobernanza y evolución del flujo de trabajo
Para consolidar el valor de .vscode/cody.json, los equipos de desarrollo deben adoptar ciertas pautas operativas:
1. Tratar los prompts como código ejecutable (Prompts as Code)
Las instrucciones en .vscode/cody.json forman parte del activo técnico de la organización. Cualquier incorporación o modificación debe gestionarse mediante Pull Requests convencionales, someterse a revisión por pares y validarse con linters de JSON en la integración continua (CI) para impedir errores sintácticos.
2. Moderar el uso de contexto global
Configurar "codebase": true de forma indiscriminada introduce llamadas de red innecesarias y ralentiza las respuestas. Es aconsejable limitar la búsqueda en toda la base de código a comandos que requieran resolver dependencias entre archivos, priorizando "selection": true para ediciones locales.
3. Escalamiento hacia la Prompt Library de Sourcegraph
Cuando una organización gestiona decenas de repositorios y microservicios, mantener archivos .vscode/cody.json idénticos en cada uno puede ocasionar desfases de versión. Para estos casos, Sourcegraph Enterprise y Cody (a partir de la versión v1.30) ofrecen la Prompt Library (Biblioteca de Prompts) en la interfaz web.
Los equipos pueden validar y ajustar sus comandos en .vscode/cody.json a nivel de repositorio. Posteriormente, los líderes técnicos pueden promover esos prompts probados a la biblioteca central de la organización. De este modo se habilitan etiquetas temáticas, prompts destacados (Promoted Prompts) y menciones dinámicas con @ (@selection, @file, @repo), permitiendo un acceso unificado desde múltiples entornos como VS Code y JetBrains.