ARTICULO

SOP: Configuración de Reglas y Contexto para AI Coding Agents

Procedimiento operativo para configurar reglas y contexto persistente en AI coding agents. Para Hermes, Cursor, Claude Code o Copilot.

2026-06-02

Paso 1: Crear el archivo de reglas del proyecto

Cada proyecto debe tener un archivo de reglas en su raíz:

HerramientaArchivo
Hermes AgentAGENTS.md
Cursor.cursorrules
Claude CodeCLAUDE.md
Copilot.github/copilot-instructions.md

Contenido mínimo:

markdown

Arquitectura

  • Lenguaje: Python 3.11+
  • Framework: FastAPI
  • Base de datos: PostgreSQL

Convenciones

  • Nombres de variables en snake_case
  • Clases en PascalCase
  • Type hints obligatorios

Archivos intocables

  • /config/production.py
  • /migrations/
  • /.env
  • /secrets/

Librerías permitidas

  • pydantic, sqlalchemy, httpx, pytest
  • NO: requests (usar httpx), selenium

Paso 2: Mantener un archivo de contexto vivo

Crear CONTEXT.md en la raíz del proyecto. Actualizarlo al final de cada sesión:

markdown

Decisiones tomadas

  • 2026-06-02: migramos autenticación de JWT a OAuth2
  • 2026-05-28: cambiamos ORM de SQLAlchemy 1.4 a 2.0

Tareas completadas

  • [x] Endpoint de login
  • [x] Rate limiting

Próximos pasos

  • [ ] Refresh token rotation
  • [ ] Tests de integración para auth

Lo que NO hay que tocar

  • El módulo de pagos está congelado hasta Q3
  • No migrar a async hasta revisar compatibilidad de librerías

Paso 3: Configurar el agente para que cargue las reglas

En Hermes Agent: el archivo AGENTS.md se carga automáticamente al iniciar una sesión en ese directorio.

En Cursor/Claude Code: verificar que .cursorrules o CLAUDE.md estén en la raíz. El agente los lee al iniciar.

Paso 4: Alcance de archivos por sesión

Antes de cada sesión, definir explícitamente qué archivos puede tocar el agente:

cd proyecto/
echo "auth/" > .agent-scope

Regla: si el agente intenta modificar un archivo fuera del scope, detener y revisar.

Paso 5: Verificación post-sesión

Al terminar cada sesión:

  1. Revisar git diff — verificar que solo se modificaron los archivos esperados
  2. Actualizar CONTEXT.md con las decisiones tomadas y próximos pasos
  3. Si el agente tocó algo que no debía, agregarlo a "Archivos intocables" en las reglas

Mantenimiento

  • Revisar reglas del proyecto cada 2 semanas
  • Podar contexto viejo (más de 30 días) del CONTEXT.md
  • Cada nuevo miembro del equipo hereda las reglas automáticamente
— Ariel Di Stefano

Compartir este artículo

Preguntas frecuentes

¿Cómo configuro reglas para un AI coding agent en mi proyecto?
Tenés que crear un archivo de reglas en la raíz del proyecto según la herramienta que uses: AGENTS.md para Hermes Agent, .cursorrules para Cursor, CLAUDE.md para Claude Code, o .github/copilot-instructions.md para Copilot. Ahí definís arquitectura, convenciones, archivos intocables y librerías permitidas. Así el agente sigue siempre las mismas pautas.
¿Qué va dentro de un archivo .cursorrules?
En .cursorrules ponés las instrucciones que el agente de Cursor debe respetar: lenguaje, framework, base de datos, convenciones de código, archivos que no puede tocar y librerías permitidas. También podés incluir reglas de estilo y ejemplos de código válido. Cuanto más específico seas, mejor va a responder el agente.
¿Qué es CONTEXT.md y para qué sirve?
CONTEXT.md es un archivo vivo que guarda el estado actual del proyecto, decisiones tomadas y pendientes para la próxima sesión. Lo actualizás al final de cada jornada para que el agente de IA arranque con toda la información del contexto. Evita que repita preguntas o pierda el hilo del trabajo.
¿Cómo mantengo el contexto de un agente de IA sin perder lo avanzado?
Actualizá un CONTEXT.md al final de cada sesión con lo hecho, lo que falta, problemas encontrados y decisiones de arquitectura. También sincronizá el archivo de reglas del proyecto si cambian las convenciones. Así el agente retoma el trabajo sin fricciones y no necesita que le expliques todo de nuevo.

Versioná las reglas y el contexto como código

Las reglas del agente no son apuntes personales: son parte del proyecto. Incluí AGENTS.md, CONTEXT.md y .agent-scope en el repositorio, así todo el equipo trabaja con el mismo estándar y el agente arranca en cualquier máquina con la misma base. Además, al versionar las reglas tenés historial de cambios: podés ver exactamente cuándo se decidió congelar el módulo de pagos o por qué se migró a OAuth2. Si el agente alucina o rompe algo, el problema casi siempre es un contexto desactualizado; con un git diff de las reglas lo detectás rápido.

También necesitás un proceso de revisión para modificar esas reglas. No cualquiera debería tocar CLAUDE.md o AGENTS.md a mano. Proponé un PR con el cambio y explicá qué problema de comportamiento estás resolviendo. Por ejemplo: "agregar regla para no usar requests, porque el agente la eligió en la última tarea". Al revisar los cambios mantenés el archivo ajustado y evitás que se convierta en un cajón de sastre con instrucciones contradictorias. Y si en el equipo hablan en voseo, pedile al agente que también lo use en su output: la documentación y los comentarios quedan consistentes con la forma en que se comunican.

Por último, separá las reglas globales de las del proyecto. Las globales, como tono, formato de respuesta o estilo, viven en la config de tu editor o en el home del agente. Las del proyecto, en la raíz del repo. Si tenés reglas específicas para un módulo, subilas a la carpeta correspondiente en vez de inflar AGENTS.md con todo junto. Mantené cada archivo de reglas por debajo de las 150 líneas; si lo superás, es señal de que necesitás dividirlo por área. Así el agente carga solo lo necesario y no pierde contexto en detalles que no le sirven para la tarea actual.

Te puede interesar

Más artículos relacionados: