Crear y mantener una herramienta de agentes de investigación que funcione en tu propio equipo

## Ejecutar la herramienta de investigación en el equipo del usuario y decidir lo que no hará Crea un entorno de investigación con prioridad local que se ejecute de forma predeterminada en el equipo del usuario, se instale mediante una vía pública documentada, almacene el estado duradero en archivos y en el control de versiones y permita completar todo el ciclo de investigación dentro del espacio de trabajo de un proyecto. Mantén un único entorno de ejecución como implementación autorizada, aunque se exponga mediante un lanzador ligero o varias interfaces. Usa prompts y habilidades especializadas para guiar la investigación mientras un servicio pequeño conserva, restaura y enruta el estado. Optimiza un núcleo específico en vez de una plataforma en expansión e indica los objetivos excluidos cuando una propuesta amplíe el entorno de ejecución, las herramientas públicas o la superficie de despliegue. ## Confiar en los archivos y el comportamiento actuales antes que en la memoria o planes viejos Comienza por los archivos que existen en la copia de trabajo actual, no por recuerdos ni por un plan antiguo. Lee la descripción general del producto, el índice de documentación, la arquitectura para responsables de mantenimiento, la guía de desarrollo, el conjunto mínimo de referencias del subsistema pertinente, la implementación y las pruebas relacionadas. Cuando las fuentes discrepen, da prioridad al comportamiento actual del entorno de ejecución y a las pruebas de contrato superadas; después, a la guía de todo el repositorio; luego, a la documentación canónica para responsables de mantenimiento y, por último, a las notas complementarias para colaboradores. Actualiza la documentación inexacta en el mismo cambio, en lugar de conservar una ruta, una afirmación sobre funciones o un flujo de trabajo obsoletos. Trata el comportamiento planificado y el implementado como afirmaciones diferentes. No describas un componente como disponible hasta que su implementación, configuración, integración, documentación y pruebas respalden por completo esa afirmación. ## Separar las reglas para quienes contribuyen al código de las reglas para la IA dentro de la herramienta Distingue las instrucciones para quienes contribuyen al repositorio de los prompts y las habilidades que gobiernan a un agente dentro del producto. Un contrato de ejecución puede exigir una herramienta pública concreta o una vía de ejecución restringida sin imponer la misma limitación a quienes mantienen y editan el repositorio. Conserva este límite siempre que cambie el comportamiento de un prompt, una habilidad, un comando o una herramienta. No reinterpretes un contrato de seguridad interno del producto como una regla de contribución al repositorio ni debilites el contrato de ejecución solo porque quienes mantienen el sistema dispongan de herramientas locales de desarrollo más amplias. ## Guardar cada proyecto de investigación en una carpeta con historial de versiones Trata cada proyecto de investigación como un único repositorio bajo control de versiones con una sola raíz absoluta. Mantén todo el contenido duradero de la investigación dentro de esa raíz y usa ramas o árboles de trabajo aislados para representar enfoques divergentes sin dividir el historial del proyecto entre ubicaciones sin relación. Mantén un contrato explícito del espacio de trabajo para el documento de alcance, el plan, el estado, el resumen, los artefactos, las líneas de base, los experimentos, la bibliografía, los traspasos, el manuscrito, la memoria y el estado privado de ejecución. Las cachés y los registros de ejecución pueden estar fuera del proyecto, pero no deben convertirse en la única copia de las evidencias de investigación. Cuando cambie la estructura del proyecto, actualiza conjuntamente el modelo de estructura, los servicios de persistencia, las instantáneas, los consumidores de la API, las interfaces de usuario, las pruebas y la documentación. No migres un consumidor mientras dejas a los demás con una estructura obsoleta. ## Mantener simple el programa de arranque y revisar lo que está en marcha antes de reiniciar Mantén el entorno de ejecución autorizado para la investigación en una sola capa de implementación y convierte los lanzadores del gestor de paquetes en adaptadores ligeros sobre ese entorno y los paquetes de interfaz precompilados. Los paquetes públicos de instalación deben contener los archivos y clientes compilados necesarios para iniciarse; no dependas de una compilación posterior a la instalación en el equipo del usuario para que funcione la vía admitida. Antes de depurar o reiniciar una instalación activa, examina el proceso en ejecución, la configuración efectiva, el supervisor o lanzador existente, el ejecutable real del entorno y la ruta del directorio principal indicada por un punto de comprobación de estado. Nunca deduzcas el directorio principal activo, la configuración ni el propietario del proceso a partir de un directorio predeterminado. Alinea los manifiestos de los paquetes, los metadatos del proyecto, la documentación pública y las expectativas sobre los paquetes de interfaz. Una vista previa o una simulación del paquete debe confirmar el conjunto de archivos distribuido antes de considerar terminado el empaquetado. ## Mantener pocas herramientas públicas para la IA y justificar cada nueva Limita la superficie pública de herramientas integradas a unas pocas responsabilidades estables: memoria duradera, artefactos versionados y ejecución duradera de comandos. Mantén el control de versiones detrás del límite de los artefactos y la ejecución del shell detrás del límite de ejecución, en lugar de añadir un espacio de nombres público nuevo para cada subsistema. Permite que los prompts definan las expectativas del flujo de trabajo y los contratos del sistema de archivos, y que las habilidades proporcionen el comportamiento de ejecución especializado. El servicio de estado debe seguir siendo ligero; evita incorporar un gran programador central de etapas cuando los contratos de prompts y habilidades puedan expresar claramente el flujo de trabajo. Cualquier propuesta de una herramienta pública nueva debe demostrar que ninguna responsabilidad existente puede contenerla, definir su modelo de persistencia y permisos, actualizar todos los clientes y añadir pruebas de contrato. La comodidad por sí sola no basta. ## Añadir nuevas conexiones con listas pequeñas y darlas por hechas solo cuando todo esté listo Usa registros pequeños para ejecutores de investigación, canales de comunicación, puentes de conectores, descubrimiento de habilidades, herramientas locales gestionadas y adaptadores opcionales. Prefiere interfaces coherentes de registro, consulta y listado a grandes ramas de despacho o condicionales específicos de un subsistema. No consideres implementada una integración hasta que estén presentes su adaptador de ejecución, los metadatos del registro, los valores predeterminados de configuración, la validación, la conexión con el servicio y la línea de comandos, la documentación visible para el usuario y las pruebas. La ausencia de una sola capa significa que la integración es parcial. Mantén los adaptadores opcionales fuera de la ruta principal e indica de forma explícita cuando no estén disponibles. Una entrada del registro debe mostrar capacidades y compatibilidad sin instalar dependencias de forma silenciosa, acceder a un servicio externo ni modificar la configuración local. ## Usar el mismo estado del proyecto y la misma conexión con el servicio (API) en el navegador y la terminal Exige que las interfaces de navegador y terminal utilicen la misma API de servicio, las mismas instantáneas de estado y el mismo modelo de eventos. Cuando cambie una ruta o un evento de la API, actualiza en el mismo cambio el servicio, todos los clientes, las suposiciones de navegación y las pruebas de contrato. Conserva rutas e identificadores estables orientados al proyecto en todas las interfaces. Las interfaces de usuario pueden presentar diseños diferentes, pero no deben inventar semánticas de estado independientes ni ocultar una transición que otra interfaz admitida necesite observar. Trata un canal de comunicación principal como una implementación del modelo genérico de canales y puentes. No permitas que un conector importante se convierta en un entorno de ejecución independiente con reglas propias de persistencia, gestión de errores o ciclo de vida. ## Definir las etapas de investigación, de la búsqueda a la escritura, sin forzar una sola línea recta Define una progresión canónica pequeña, como descubrimiento, establecimiento de la línea de base, formación de ideas, experimentación, análisis, redacción y finalización. Mantén la toma de decisiones como una actividad transversal, en vez de fingir que toda actividad importante constituye una única etapa lineal. Las auditorías de admisión, la preparación de figuras, la revisión y la réplica pueden existir como actividades especializadas, pero no las incluyas en la cadena predeterminada salvo que el código actual y los contratos de los prompts lo hagan realmente. Las etapas con nombre deben coincidir con los anclajes activos del sistema, las transiciones de estado y la documentación para el usuario. Mantén el comportamiento de las etapas en el prompt del sistema, los contratos específicos de prompts, el ensamblaje de prompts y las habilidades de etapa. Evita dispersar la semántica de las etapas entre los controladores del servicio, el código de las interfaces y condicionales improvisados. ## Separar las guías para usuarios de los documentos para desarrolladores Separa las guías para usuarios de las referencias de arquitectura y desarrollo para responsables de mantenimiento. La documentación pública debe explicar el comportamiento actual; los documentos de mantenimiento deben explicar los contratos, los puntos de extensión y los requisitos de cambios coordinados. No coloques planes temporales, listas de comprobación provisionales, rutas privadas ni notas de uso exclusivamente interno en el árbol de documentación pública. Mantén estables los nombres de los documentos enlazados, elimina las referencias a archivos eliminados y actualiza todas las traducciones que sigan manteniéndose cuando cambie un comportamiento visible para el usuario. Cuando un cambio afecte únicamente al mantenimiento interno, actualiza las referencias canónicas para responsables de mantenimiento sin fabricar un anuncio para usuarios. El alcance de la documentación debe corresponder al alcance del comportamiento. ## Mantener contraseñas y rutas personales fuera de los archivos compartidos y conservar los registros de investigación No incorpores al historial del repositorio rutas absolutas específicas de una estación de trabajo, credenciales, tokens, cachés locales, directorios de dependencias, resultados transitorios de compilación ni cachés de pruebas. Los paquetes de interfaz generados solo deben formar parte de un paquete público cuando el contrato de empaquetado lo exija de manera explícita. Mantén los registros duraderos de experimentos, las notas bibliográficas, las líneas de base, los artefactos y los manuscritos dentro del límite del proyecto y bajo control de versiones. Conserva las evidencias originales antes de resumirlas y nunca sustituyas un resultado reproducible por un mensaje de estado que solo exista en una interfaz. Antes de publicar, revisa los archivos públicos para detectar secretos filtrados, nombres de documentos obsoletos, referencias privadas y desviaciones en archivos generados. Que las pruebas terminen correctamente no justifica publicar contenido sensible o no reproducible. ## Revisar primero el código actual y hacer cambios pequeños Examina la implementación existente antes de proponer una abstracción nueva. Prefiere cambios pequeños y coherentes a refactorizaciones amplias y mixtas, consulta primero el conjunto mínimo de documentación pertinente y verifica la propuesta frente al código y las pruebas. Cuando el código y la documentación diverjan, corrige ambos en un único cambio de alcance limitado. No conserves referencias obsoletas solo porque existieron y no reinicies un servicio de investigación activo hasta identificar el entorno de ejecución, el proceso, la configuración y el directorio principal efectivos. Separa el diagnóstico de las modificaciones. Registra la señal observada, el comportamiento esperado, los consumidores afectados y la corrección mínima antes de cambiar el estado compartido. ## Actualizar pruebas y documentación junto con el código que cambias, sin tocar lo que no tiene relación Actualiza todas las capas afectadas directamente por el subsistema que se modifica: - estructura del proyecto o estado duradero: modelo de estructura, servicio de persistencia, instantáneas, consumidores de la API y pruebas de estado; - prompts o habilidades de etapa: fuentes de prompts, ensamblaje, definiciones de habilidades, instaladores replicados, pruebas de comportamiento y guías para usuarios; - memoria, artefactos o ejecución de comandos: implementaciones, límites públicos, pruebas de servicio y documentación de contratos; - ejecutores de investigación: adaptador, registro, valores predeterminados de configuración, validación, conexión con el servicio y la línea de comandos, guías y pruebas; - canales o puentes de conectores: valores predeterminados, validación, código de canales y puentes, guías de conectores y pruebas de integración; - herramientas locales gestionadas: registro, adaptador concreto, comportamiento de estado y resolución, guías para responsables de mantenimiento y pruebas; - superficie compartida de la API: enrutador, controladores, cliente de navegador, cliente de terminal, navegación y pruebas de contrato; - empaquetado: manifiestos, metadatos del proyecto, descripción pública, paquetes necesarios y verificación del contenido del paquete. No amplíes esta matriz a subsistemas no relacionados. Su propósito es lograr una integridad coordinada dentro del límite de impacto directo, no reescribir todo el repositorio. ## Probar la instalación documentada antes de dar el trabajo por terminado Ejecuta las comprobaciones pertinentes de unidad, integración, contrato, compilación, construcción de interfaces y empaquetado para la superficie modificada. Cuando cambie el comportamiento del lanzador o del empaquetado, inicia el sistema mediante la vía pública documentada y verifica el inicio directo del servicio únicamente como método de diagnóstico. Revisa las diferencias finales para detectar ediciones no relacionadas, archivos generados obsoletos, traducciones ausentes, afirmaciones de funciones sin respaldo y actualizaciones incompletas de clientes. Distingue el éxito local de una prueba de componente de la demostración de que funcionan la instalación y la interfaz admitidas. Usa la copia de trabajo real como fuente autorizada final. Si un archivo o comportamiento citado ya no existe, corrige la referencia y sus consumidores en lugar de conservar el error.