Saltar a contenido

Guía para Agentes IA

Normas para que agentes de IA (como Claude Code, GitHub Copilot) trabajen efectivamente en el Sistema A3, el ERP interno de A Terceros Inmobiliaria.

Nota Importante: Este es software privado y confidencial. Los agentes IA deben seguir las mismas políticas de seguridad que los desarrolladores humanos.

Contexto del Proyecto

Factor Valor
Lenguaje principal Python 3.11
Framework backend Django 3.2
Frontend HTML templates, JavaScript + jQuery, CSS
Comportamiento UI SPA simulada con gestor de ventanas (static/js/js.js)
Base de datos PostgreSQL 12.3+
Estructura Monolito con múltiples apps Django
Despliegue Heroku

Arquitectura SPA

El sistema funciona como una Single-Page Application simulada:

  • Script central: static/js/js.js (gestor de ventanas)
  • Navegación: Mediante apertura de "ventanas" que cargan contenido vía AJAX
  • No usar React, Vue o frameworks modernos sin aprobación
  • Mantener el comportamiento SPA existente

Estructura del Proyecto

sistema-a3/
├── manage.py
├── requirements.txt
├── .env
├── a3ceros/           # App principal (settings, urls)
├── inventario/        # Módulo de propiedades
├── apartados/         # Módulo de ventas
├── clientes/          # Módulo de clientes
├── tickets/           # Módulo de tickets
├── ... (más apps)
├── static/
│   ├── css/
│   └── js/
│       └── js.js      # ⚠️ CRÍTICO: Gestor SPA
└── templates/
    └── base.html

Reglas para Agentes IA

1. Python

✅ Hacer: - Formatear con black --line-length 90 - Ordenar imports con isort - Agregar docstrings en funciones públicas - Seguir convenciones Django - Registrar nuevas apps en INSTALLED_APPS

❌ NO hacer: - Cambiar estructura de carpetas sin consultar - Introducir nuevos frameworks sin aprobación - Ignorar el ORM de Django (no SQL crudo) - Hardcodear secrets

2. JavaScript

✅ Hacer: - Mantener compatibilidad con static/js/js.js - Documentar funciones nuevas - Usar jQuery existente - Seguir estilo funcional

❌ NO hacer: - Renombrar o refactorizar js.js sin aprobación - Introducir bundlers (Webpack, Vite) sin consultar - Romper navegación SPA - Usar ES6 modules (el proyecto usa scripts globales)

3. CSS

✅ Hacer: - Seguir convenciones existentes - Agregar comentarios para estilos complejos

❌ NO hacer: - Introducir Tailwind/Bootstrap sin aprobación - Cambiar estructura de archivos CSS

4. Testing

✅ Hacer: - Agregar tests con pytest - Usar model-bakery para fixtures - Tests unitarios y de integración

❌ NO hacer: - Ignorar tests al agregar código nuevo - Commitear código que rompa tests existentes

5. Pull Requests

El agente debe generar PRs con:

Título: feat/fix/docs: descripción corta

Descripción mínima: 

## Resumen
1-2 líneas del cambio.

## Cambios
- Lista de cambios
- Bullet points

## Checklist
- [ ] Código compila
- [ ] No se rompen flujos SPA
- [ ] Imports ordenados (isort)
- [ ] Código formateado (black)
- [ ] Tests pasan
- [ ] Documentación actualizada
- [ ] No hay secretos
- [ ] requirements.txt actualizado (si aplica)
- [ ] Migraciones creadas (si aplica)

6. Migraciones

Si tocas modelos:

python manage.py makemigrations
python manage.py migrate

Incluir migraciones en el PR.

7. Dependencias

Si agregas dependencias:

  1. Agregarlas a requirements.txt
  2. Justificar en el PR
  3. Verificar compatibilidad

8. Seguridad

✅ Hacer: - Validar inputs del usuario - Usar Django ORM (previene SQL injection) - CSRF tokens en forms POST - Permisos en views (@login_required)

❌ NO hacer: - SQL queries crudos - Almacenar passwords en texto plano - Exponer secrets

Comandos Útiles

# Formatear código
black --line-length 90 .
isort .

# Tests
pytest

# Migraciones
python manage.py makemigrations
python manage.py migrate

# Servidor local
python manage.py runserver

# Shell Django
python manage.py shell

Escenarios Comunes

Agregar Nuevo Modelo

  1. Crear modelo en app/models.py
  2. Hacer migraciones
  3. Actualizar admin (si aplica)
  4. Agregar serializer (si hay API)
  5. Agregar tests

Agregar Nueva Vista

  1. Crear vista en app/views.py
  2. Agregar URL en app/urls.py
  3. Crear template
  4. Agregar permisos
  5. Agregar tests

Agregar Endpoint API

  1. Crear serializer en app/serializers.py
  2. Crear viewset en app/viewsets.py
  3. Registrar en router
  4. Documentar
  5. Agregar tests

CI/CD

Actualmente no hay pipeline CI/CD formal.

Tests pueden ejecutarse manualmente o en GitHub (si existe workflow).

Contacto

Si el agente encuentra ambigüedades o necesita decisiones arquitectónicas, debe:

  1. Dejar comentario en el código
  2. Agregar TODO con explicación
  3. Mencionar en la descripción del PR

Resumen para Agentes:

  1. Django monolítico, no microservicios
  2. SPA simulada con js.js (NO tocar sin aprobación)
  3. Formatear con black + isort
  4. Tests con pytest
  5. PRs descriptivos con checklist
  6. No introducir frameworks sin consultar
  7. Seguir estructura existente

Si el agente sigue estas reglas, el código será mergeable y no romperá el sistema.