ia-agent-test — Plugin de VS Code
Plugin para distribuir y mantener actualizado el agente AI de pruebas en cualquier proyecto. Estandariza las buenas prácticas del equipo a través de archivos Markdown que la IA de tu editor lee para entender cómo trabajar correctamente en el proyecto.
¿Qué hace este plugin?
Cuando lo instalas, el plugin es capaz de:
- Copiar la carpeta del agente con todos sus archivos
.md a tu proyecto la primera vez que lo inicializas
- Actualizar automáticamente esos archivos cada vez que abres un proyecto que ya fue inicializado, si hay una nueva versión del plugin disponible
- Remover la carpeta del agente del proyecto si ya no la necesitas
- No tocar ningún proyecto que no hayas inicializado previamente
Los archivos .md contienen instrucciones, buenas prácticas y contexto para que la IA de tu editor (Copilot, Cursor, etc.) entienda los estándares del equipo y trabaje bajo esas reglas.
Estructura de carpetas que genera en tu proyecto
Cuando inicializas el plugin en tu proyecto, aparece la siguiente estructura:
tu-proyecto/
└── .ai-agent-test/ ← generado por el plugin — no modificar
├── agents/ ← agentes generales para la IA
| └── best-practices.md ← buenas prácticas del equipo
├── instructions/ ← instrucciones generales para la IA
| └── instructions.md ← instrucciones generales para la IA
└── copilot-instructions.md ← archivo de copilot
⚠️ Importante: No modifiques manualmente los archivos dentro de .ai-agent-test. Son gestionados por el plugin y cualquier cambio manual será sobreescrito en la próxima actualización.
¿Se sube al repositorio git?
Sí. Se recomienda subir la carpeta .ai-agent-test al repositorio para que cualquier persona que clone el proyecto ya tenga el contexto del agente disponible sin necesidad de ejecutar el comando de inicialización. El plugin se encarga de mantener los archivos actualizados cuando haya una nueva versión.
Flujo completo de uso
Primera vez — Inicializar el agente en un proyecto
1. Instalar el plugin desde el Marketplace de VS Code
↓
2. Abrir el proyecto en VS Code
↓
3. Presionar Ctrl+Shift+P
↓
4. Escribir "Initialize Agent Test" y ejecutar
↓
5. La carpeta .ai-agent-test aparece en el proyecto con todos los archivos
Actualizaciones — Cuando hay una nueva versión del plugin
1. El autor actualiza los .md y publica una nueva versión del plugin
↓
2. VS Code notifica al usuario que hay una actualización disponible
↓
3. El usuario actualiza el plugin con un click
↓
4. La próxima vez que abra cada proyecto:
↓
¿El proyecto tiene .ai-agent-test?
/ \
SÍ NO
↓ ↓
Los archivos se No pasa nada.
actualizan Cuando el usuario quiera
automáticamente inicializar, ejecuta
el comando manualmente
Remover el agente de un proyecto
1. Presionar Ctrl+Shift+P
↓
2. Escribir "Remove Agent Test" y ejecutar
↓
3. Aparece confirmación: "¿Estás seguro de que quieres eliminar .ai-agent-test?"
↓
/ \
Sí, eliminar Cancelar
↓ ↓
Se elimina No pasa nada
.ai-agent-test
del proyecto
Ejemplo con múltiples proyectos
proyecto-1 ✅ tiene .ai-agent-test → se actualiza automáticamente
proyecto-2 ✅ tiene .ai-agent-test → se actualiza automáticamente
proyecto-3 ✅ tiene .ai-agent-test → se actualiza automáticamente
proyecto-4 ❌ no tiene .ai-agent-test → no pasa nada
Comandos disponibles
| Comando |
Cómo ejecutarlo |
Qué hace |
Initialize Agent Test |
Ctrl+Shift+P → escribir el nombre |
Copia la carpeta .ai-agent-test con todos los archivos al proyecto por primera vez |
Remove Agent Test |
Ctrl+Shift+P → escribir el nombre |
Pide confirmación y elimina la carpeta .ai-agent-test del proyecto si ya no la necesitas |
Explicación de cada función del código
activate(context)
¿Cuándo corre?
Cada vez que VS Code abre un proyecto con el plugin instalado. Es el punto de entrada — todo arranca desde aquí.
¿Qué hace?
Hace tres cosas:
- Llama a
checkAndUpdate automáticamente para revisar si el proyecto ya tiene el agente y necesita actualizarlo
- Registra el comando
Initialize Agent Test para que el usuario pueda ejecutarlo manualmente desde Ctrl+Shift+P cuando quiera inicializar el agente por primera vez
- Registra el comando
Remove Agent Test para que el usuario pueda eliminar el agente de un proyecto
Piénsalo como el main() del plugin.
initializeAgent(context)
¿Cuándo corre?
Solo cuando el usuario ejecuta el comando Initialize Agent Test manualmente desde Ctrl+Shift+P. Nunca corre de forma automática.
¿Qué hace paso a paso?
- Verifica que haya un proyecto abierto en VS Code. Si no hay ninguno, muestra un error y para
- Obtiene la ruta del proyecto abierto actualmente en el editor
- Obtiene la ruta de la carpeta
templates que viene empaquetada dentro del plugin, donde están guardados todos los archivos .md
- Llama a
copyFolder para copiar toda esa estructura al proyecto del usuario
- Muestra el mensaje de confirmación "✅ Agente AI inicializado en tu proyecto!"
¿Cuándo se usa?
Únicamente la primera vez que un desarrollador quiere incorporar el agente a su proyecto. A partir de ese momento las actualizaciones son manejadas automáticamente por checkAndUpdate.
removeAgent()
¿Cuándo corre?
Solo cuando el usuario ejecuta el comando Remove Agent Test manualmente desde Ctrl+Shift+P. Nunca corre de forma automática.
¿Qué hace paso a paso?
- Verifica que haya un proyecto abierto en VS Code. Si no hay ninguno, muestra un error y para
- Busca la carpeta
.ai-agent-test en el proyecto actual
- Si no la encuentra, muestra un aviso "⚠️ No se encontró .ai-agent-test en este proyecto" y para
- Si la encuentra, muestra un diálogo de confirmación preguntando si realmente desea eliminarla
- Si el usuario confirma, elimina la carpeta completa con todo su contenido
- Si el usuario cancela, no hace nada
¿Por qué pide confirmación?
Para evitar que alguien elimine el agente por accidente. Es una acción destructiva que no se puede deshacer fácilmente.
checkAndUpdate(context)
¿Cuándo corre?
Automáticamente cada vez que VS Code abre un proyecto, sin que el usuario tenga que hacer nada.
¿Qué hace paso a paso?
- Verifica que haya un proyecto abierto. Si no hay ninguno, para silenciosamente sin mostrar nada
- Construye la ruta donde debería estar
.ai-agent-test dentro del proyecto actual
- Pregunta internamente: ¿existe esa carpeta en este proyecto?
- SÍ existe — el proyecto ya fue inicializado anteriormente, por lo que copia los archivos nuevos encima de los existentes y muestra "🔄 Agente AI actualizado!"
- NO existe — el proyecto nunca fue inicializado, por lo que no hace absolutamente nada y espera a que el usuario ejecute el comando manual
La clave de esta función:
Es la que garantiza que si tienes varios proyectos, solo se actualicen los que el usuario decidió inicializar. Los demás permanecen intactos.
copyFolder(source, destination)
¿Cuándo corre?
No corre sola. Es llamada internamente por initializeAgent y checkAndUpdate para hacer el trabajo real de mover los archivos.
¿Qué hace paso a paso?
- Crea la carpeta de destino si no existe, incluyendo todas las carpetas intermedias que necesite
- Lee todos los elementos dentro de la carpeta origen — tanto archivos como subcarpetas
- Por cada elemento decide:
- Si es una subcarpeta — se llama a sí misma recursivamente para entrar y copiar su contenido también
- Si es un archivo — lo copia al destino sobreescribiendo cualquier versión anterior que ya existiera
¿Por qué sobreescribe sin preguntar?
Porque el usuario no debe modificar estos archivos. Siempre que haya una versión nueva en el plugin, esa versión gana sobre cualquier cosa que exista en el proyecto.
Es recursiva, lo que significa que no importa qué tan profunda sea la estructura de carpetas del agente, siempre la copiará completa nivel por nivel.
Diagrama de llamadas entre funciones
VS Code abre proyecto
↓
activate()
/ | \
↓ ↓ ↓
checkAnd registerCommand registerCommand
Update() ('initialize') ('remove')
↓ ↓ ↓
¿Existe Usuario ejecuta Usuario ejecuta
.ai-agent Initialize Remove
-test? Agent Test Agent Test
↓ ↓ ↓
SÍ initializeAgent() removeAgent()
↓ ↓ ↓
copyFolder() copyFolder() ¿Confirma?
(actualiza) (primera vez) / \
SÍ NO
↓ ↓
Elimina No hace
.ai-agent-test nada
Preguntas frecuentes
¿Puedo modificar los archivos .md dentro de .ai-agent-test?
No. Son gestionados por el plugin y se sobreescriben con cada actualización. Si quieres agregar instrucciones propias del proyecto, crea una carpeta separada fuera de .ai-agent-test.
¿Qué pasa si desinstalo el plugin?
La carpeta .ai-agent-test permanece en tus proyectos. El plugin no la elimina al desinstalarse. Si la quieres quitar, usa el comando Remove Agent Test antes de desinstalar.
¿El plugin funciona si no tengo ningún proyecto abierto?
Sí, se instala sin problema. Simplemente no hace nada hasta que abras un proyecto.
¿Funciona con múltiples proyectos abiertos al mismo tiempo en una sola ventana?
Actualmente actúa sobre el primer proyecto del workspace. Si trabajas con varios proyectos simultáneamente en una sola ventana de VS Code, se recomienda abrir cada uno en su propia ventana para que el plugin actúe correctamente sobre cada uno.
¿Qué pasa si tengo el plugin instalado pero no quiero el agente en un proyecto específico?
Simplemente no ejecutes el comando de inicialización en ese proyecto. El plugin nunca copia nada sin que el usuario lo haya pedido al menos una vez.
¿El comando Remove elimina sin preguntar?
No. Siempre muestra un diálogo de confirmación antes de eliminar para evitar borrados accidentales.
Versiones
| Versión |
Cambios |
| 1.0.0 |
Lanzamiento inicial — inicialización y actualización automática del agente de pruebas |
| 1.1.0 |
Nuevo comando Remove Agent Test — elimina el agente del proyecto con confirmación previa |
