Cómo dar a un agente de coding con IA conocimiento fiable del dominio

Un agente de coding general puede escribir una respuesta plausible y aun así omitir el detalle que importa en tu stack: una API que cambió el mes pasado, un límite del repositorio que no debe cruzarse o una convención que mantiene estable producción. La solución no siempre es un prompt más largo. Un patrón mejor es darle orientación de dominio pequeña y reutilizable, junto con una definición de terminado que se pueda comprobar.

1. Separa las reglas del proyecto de los procedimientos del dominio

Empieza con dos capas. La primera es un contrato breve del repositorio: qué es el proyecto, cómo está organizado, qué comandos lo construyen y prueban, qué archivos están fuera de límites y qué significa “terminado”. La documentación de JetBrains sobre el comportamiento de los agentes describe archivos como AGENTS.md y CLAUDE.md como instrucciones que viajan con el repositorio y pueden compartirse entre herramientas.

Mantén esta capa estable y operativa. Debe contestar preguntas necesarias en toda tarea: dónde está la lógica de dominio, cómo ejecutar las comprobaciones y qué no editar. Si una regla solo sirve para un flujo, colócala en una skill separada.

La segunda capa es conocimiento del dominio: una receta enfocada para una tarea repetida, como migrar la navegación de Android, cambiar un esquema de base de datos o preparar una versión. Una skill debe tener un disparador claro, pocos pasos y validación explícita. Así el contexto habitual sigue siendo pequeño y la ayuda especializada aparece solo cuando corresponde.

2. Escribe una skill alrededor de una laguna de conocimiento

Una buena skill existe porque el modelo se equivoca de forma repetida o pierde tiempo redescubriendo algo. La filosofía de Android Skills propone una prueba útil: las skills oficiales cubren lagunas verificables, sobre todo cuando cambian las APIs o el equipo usa una arquitectura propia. También recomienda descargar skills de fuentes reputadas, no de colecciones enormes y sin probar que podrían contener instrucciones maliciosas.

Por ejemplo:

---
name: navigation-upgrade
description: Use when changing the app's Navigation 3 setup or upgrading its related APIs.
---

Before editing:
1. Inspect the current dependency versions and existing navigation tests.
2. Read the project's navigation conventions.
3. Confirm the target API in the approved platform documentation.

While editing:
- Make the smallest vertical change that satisfies the requested behavior.
- Do not replace the navigation architecture without approval.
- Preserve existing deep-link and back-stack behavior unless the task says otherwise.

Done means:
- The focused tests pass.
- The relevant build or lint command passes.
- The response names changed files, checks run, and unresolved risks.

El ejemplo es deliberadamente estrecho. No pega un manual entero en cada prompt; indica cuándo aplicar el procedimiento, qué inspeccionar, qué límites importan y cómo demostrar que terminó. Sustituye los checks específicos por comandos y convenciones reales de tu repositorio.

3. Haz que el agente inspeccione antes de actuar

Los agentes de coding combinan una petición con el contexto del entorno, razonan sobre él y ejecutan acciones como editar, probar y construir. Ese es el flujo descrito en AWS Prescriptive Guidance. Tus instrucciones deben hacer visibles esas fases.

Una petición práctica tiene cuatro partes:

1. Contexto: función, directorios relevantes y restricciones.
2. Plan: lista de archivos y checks antes de editar.
3. Cambio: la implementación mínima para cumplir los criterios de aceptación.
4. Evidencia: tests, lint, build, capturas o comprobaciones manuales exactas.

Esto evita que el agente empiece desde una sola frase, descubra tarde la arquitectura y compense con una reescritura amplia. Inspeccionar no es ceremonia: es cómo obtiene el contexto del que dependen sus decisiones.

4. Dale un ciclo de feedback corto

La orientación de dominio explica el proyecto, pero los checks ejecutables dicen si el cambio funciona. La guía actual de TDD de VS Code separa una fase red con un test que falla, una fase green con la implementación mínima y una fase refactor que mejora la estructura manteniendo los tests verdes.

No necesitas tres agentes elaborados. En una tarea pequeña pide primero un test fallido o de caracterización. Después permite la implementación. Termina con un test enfocado y las puertas de calidad normales del proyecto. Si el agente no pasa el check, es información sobre el requisito o el entorno, no una razón para esconder el fallo en un resumen demasiado seguro.

5. Revisa y retira la orientación

Trata una skill como infraestructura de ingeniería versionada. Revísala cuando cambia el framework, cuando el agente repite un error o cuando un check se vuelve ruidoso. La guía de Android Skills considera las skills candidatas a deprecación: los modelos mejoran, algunas instrucciones dejan de hacer falta y las APIs nuevas crean lagunas nuevas.

Un ciclo de mantenimiento sencillo:

• Conserva una tarea de ejemplo que use la skill.
• Registra los archivos esperados y comandos de validación.
• Ejecútala después de cambiar la skill o el modelo.
• Elimina instrucciones que ya no hagan falta.
• Mantén las acciones sensibles a seguridad opt-in y revisables.

El objetivo no es que el agente suene más experto, sino que el comportamiento correcto sea reproducible. Un contrato breve del repositorio, un procedimiento de dominio bien activado y una definición de terminado ejecutable forman un camino desde el contexto hasta el cambio y la evidencia.