Contexto para Agentes LLM

Guia para Agentes de IA

Este documento esta optimizado para ser consumido por Large Language Models (LLMs) como Claude, GPT, Gemini, etc.

Como Usar Esta Documentacion

Para RAG (Retrieval Augmented Generation)

  • Cada seccion esta diseñada para ser un chunk independiente (~500-1200 tokens)
  • Los bundles en /library/infra-handbook/bundles/ contienen markdown consolidado
  • Usar marcadores de seccion (##, ###) para delimitar chunks

Bundles Disponibles

Bundle Contenido Tokens aprox.
convenciones.md Estandares de codigo y estilo ~800
infraestructura.md VPS, servicios, deployment ~3000
debug-troubleshooting.md Debugging y resolucion ~600
diseno-estilo.md Diseño visual y branding ~900

Endpoints de Datos

  • Estado de servicios: https://infra.illanes00.cl/status.json
  • Esta documentacion: https://docs.illanes00.cl
  • Indice JSON: https://docs.illanes00.cl/index.json

Reglas Criticas para Desarrollo

Reglas NO Negociables
  1. TypeScript obligatorio - No JavaScript puro en proyectos nuevos
  2. No Docker para proyectos nuevos (usar systemd + venv)
  3. FastAPI para APIs Python
  4. Tailwind CSS para estilos (nunca CSS-in-JS)
  5. Conventional Commits en ingles

Resumen de Infraestructura

VPS (Virtual Private Servers)

VPS Proposito Repos
vps-dev Desarrollo, staging, 58 repos La mayoria de proyectos
vps-control Panel admin, monitoring, runners Admin, Grafana, Prometheus
vps-deploy Produccion, 17 repos desplegados Sitios publicos activos

Servicios Clave

Servicio URL Descripcion
Documentacion https://docs.illanes00.cl Esta wiki (Quarto)
Monitor https://infra.illanes00.cl Dashboard de estado
Admin https://admin.illanes00.cl Panel de administracion
API https://api.illanes00.cl API comun (FastAPI)
Auth https://auth.illanes00.cl Authentik SSO
Static https://static.illanes00.cl Archivos estaticos

Stack Tecnologico

  • Reverse Proxy: Caddy con certificados via Cloudflare DNS-01
  • Auth: Authentik (OAuth2/OIDC)
  • Monitoring: Grafana, Prometheus, Netdata
  • Bases de datos: PostgreSQL 14, Redis, SQLite (dev)
  • Bot: Telegram bot para notificaciones

Archivos de Referencia Rapida

Para obtener contexto completo, leer en orden:

  1. /srv/projects/AGENT-CONTEXT.md - Resumen ejecutivo global
  2. Este documento - Detalles de documentacion
  3. Bundles especificos segun la tarea

Convenciones de Codigo

Python (Backend)

# Ejemplo de estructura correcta
from __future__ import annotations
from fastapi import FastAPI

app = FastAPI(title="mi-servicio")

@app.get("/healthz")
def healthz() -> dict[str, bool]:
    return {"ok": True}
  • Version: Python 3.10+ (preferido 3.11)
  • Framework: FastAPI para APIs
  • Linting: Ruff (reemplaza flake8)
  • Formatting: Black (line-length: 100)
  • Type hints: OBLIGATORIOS

TypeScript (Frontend y Node)

// Ejemplo de configuracion correcta
// tsconfig.json: strict: true
export const config = {
  semi: true,
  singleQuote: true,
  printWidth: 100,
  tabWidth: 2,
  trailingComma: 'none'
} as const;
  • Version: Node.js 18+
  • Modo: ES Modules ("type": "module")
  • TypeScript: Strict mode SIEMPRE
  • Frameworks: Next.js 14, Vite + React

Endpoints Obligatorios

Toda API debe implementar:

GET /healthz  -> {"ok": true}
GET /readyz   -> {"ok": true}
GET /version  -> {"name": "...", "sha": "..."}

Colores Institucionales

--ep-primary: #1a365d;    /* Azul oscuro */
--ep-secondary: #c53030;  /* Rojo */
--ep-accent: #2b6cb0;     /* Azul medio */

Creacion de Proyectos Nuevos

python /srv/projects/infra-tools/new_project.py \
  --slug mi-proyecto \
  --port 81XX \
  --domain mi-proyecto.illanes00.cl \
  --register-monitor

NO HACER (Anti-patterns)

Evitar estos errores comunes
  1. Usar JavaScript puro (siempre TypeScript)
  2. Crear Dockerfiles para proyectos nuevos
  3. Hardcodear credenciales o tokens
  4. Usar CSS-in-JS (usar Tailwind)
  5. Crear proyectos fuera de /srv/projects/
  6. Commitear archivos .env
  7. Ignorar type hints

Actualizaciones

Este archivo se sincroniza con /srv/projects/AGENT-CONTEXT.md. Para informacion en tiempo real: