OpenCode Enterprise: Implementación para Platform Engineering

1. Introducción a OpenCode

¿Qué es OpenCode y para qué sirve?

• Refactorizar módulos enteros.
• Escribir tests unitarios basados en la implementación actual.
• Debuggear errores leyendo el stack trace y el código fuente.

Diferencias con otras herramientas similares

Requisitos previos del sistema

• Sistema Operativo: Windows 10/11, macOS (Intel/Apple Silicon) o Linux (Ubuntu/Debian/Fedora).
• Node.js: Versión 18 o superior (necesario para ejecutar el CLI).
• Git: Instalado y configurado (OpenCode usa Git para gestionar cambios).
• Proveedor de IA: Una clave API válida (OpenAI, Anthropic, o un endpoint local compatible).

2. Instalación Paso a Paso

Método de instalación recomendado

Comandos por Sistema Operativo

npm install -g opencode

La forma más sencilla de instalar OpenCode es mediante el script de instalación.

curl -fsSL https://opencode.ai/install | bash

Por qué global: El flag -g instala la herramienta en todo el sistema. Si no lo usas, solo podrás ejecutar OpenCode dentro de la carpeta donde lo instalaste, lo cual es poco práctico.

Verificación de instalación

opencode --version

Solución de Errores Comunes de Instalación

• Causa: No tienes permisos para escribir en la carpeta global de Node.
• Solución: No uses sudo. Configura los permisos de npm correctamente:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g opencode

• Causa: Tu versión de Node es antigua (< 18).
• Solución: Actualiza a Node 20 LTS desde nodejs.org

• Causa: La carpeta npm no está en el PATH.
• Solución: Reinicia PowerShell como Administrador o reinstala Node.js con la opción «Add to PATH».

3. Configuración Inicial y Autenticación

Primeros Pasos: Iniciar Sesión

opencode auth login

Múltiples Providers 

# Configurar primario y fallback
opencode config set primary_provider anthropic
opencode config set fallback_provider openai
opencode config set azure_endpoint "https://tu-recurso.openai.azure.com/"

Variables de Entorno vs Configuración Persistentes

# .env - AÑADIR A .gitignore OBLIGATORIAMENTE
OPENAI_API_KEY=sk-proj-1234567890abcdef1234567890abcdef1234567890abcdef
ANTHROPIC_API_KEY=sk-ant-api03-1234567890abcdef-1234567890abcdef-1234567890abcdef
GITHUB_TOKEN=ghp_1234567890abcdefghijklmnopqrstuvwxyz12
AZURE_OPENAI_KEY=1234567890abcdef1234567890abcdef
AZURE_OPENAI_ENDPOINT=https://mi-empresa.openai.azure.com/

Método B: Configuración global (recomendado)

# Configura claves de forma segura (encriptadas en el keyring del sistema)
opencode config set providers.openai.api_key "sk-proj-1234567890abcdef1234567890abcdef1234567890abcdef" --global
opencode config set providers.anthropic.api_key "sk-ant-api03-1234567890abcdef-1234567890abcdef-1234567890abcdef" --global
opencode config set providers.azure.endpoint "https://mi-empresa.openai.azure.com/" --global
opencode config set providers.azure.api_key "1234567890abcdef1234567890abcdef" --global

# Configura el modelo por defecto
opencode config set defaults.model "claude-3-5-sonnet-20241022" --global
opencode config set defaults.fallback_model "gpt-4o" --global
opencode config set defaults.max_tokens 4096 --global

Método C: Configuración enterprise avanzada (múltiples modelos) Archivo ~/.opencode/config.json:

{
  "version": "1.0",
  "active_profile": "enterprise",
  "profiles": {
    "enterprise": {
      "providers": {
        "openai": {
          "api_key": "sk-proj-1234567890abcdef1234567890abcdef1234567890abcdef",
          "organization": "org-empresa123",
          "base_url": "https://api.openai.com/v1",
          "timeout": 60
        },
        "anthropic": {
          "api_key": "sk-ant-api03-1234567890abcdef-1234567890abcdef-1234567890abcdef",
          "base_url": "https://api.anthropic.com",
          "timeout": 60
        },
        "github_copilot": {
          "enabled": true,
          "oauth_token": "ghu_1234567890abcdefghijklmnopqrstuvwxyz123456",
          "default_model": "claude-3-5-sonnet-20241022",
          "models": {
            "claude-3-5-sonnet-20241022": { "max_tokens": 8192 },
            "gpt-4o": { "max_tokens": 4096 },
            "gpt-4o-mini": { "max_tokens": 4096 }
          }
        },
        "azure_openai": {
          "api_key": "1234567890abcdef1234567890abcdef",
          "endpoint": "https://mi-empresa.openai.azure.com/",
          "deployment": "gpt-4o-enterprise",
          "api_version": "2024-08-01-preview"
        }
      },
      "defaults": {
        "primary_provider": "anthropic",
        "fallback_provider": "openai",
        "model": "claude-3-5-sonnet-20241022",
        "fallback_model": "gpt-4o",
        "max_tokens": 4096,
        "temperature": 0.2,
        "context_window": 200000,
        "timeout": 120
      },
      "security": {
        "encrypt_keys": true,
        "keyring_backend": "auto",
        "allow_insecure_local_storage": false
      }
    },
    "local": {
      "providers": {
        "ollama": {
          "enabled": true,
          "endpoint": "http://localhost:11434",
          "model": "codellama:70b",
          "timeout": 300
        }
      },
      "defaults": {
        "primary_provider": "ollama",
        "model": "codellama:70b"
      }
    }
  },
  "logging": {
    "level": "info",
    "file": "~/.opencode/logs/opencode.log",
    "max_size": "100MB",
    "max_age": 30,
    "compress": true
  }
}

Configuración por proyecto (prioridad alta) Archivo .opencode/config.json en la raíz del proyecto (sobrescribe la global):

{
  "extends": "~/.opencode/config.json",
  "project": {
    "name": "mi-plataforma-terraform",
    "type": "platform-engineering"
  },
  "defaults": {
    "model": "claude-3-5-sonnet-20241022",
    "max_tokens": 8192
  },
  "context": {
    "include": ["terraform/**/*.tf", "k8s/**/*.yaml", "docs/**/*.md"],
    "exclude": ["**/.terraform/**", "**/*.tfstate*", "**/secrets/**"]
  }
}

Modos de Operación

opencode
# Inicia chat interactivo con contexto persistente

opencode --zen "Generar tests para src/auth.ts"
# Ejecuta y sale, sin preguntas interactivas
# Ideal para: pre-commit hooks, scripts de automatización

opencode --verbose
# Muestra: tokens usados, tiempo de respuesta, archivos leídos

opencode --dry-run "Refactorizar a TypeScript"
# Muestra qué haría pero no modifica archivos

4. Arquitectura Multi-Agente Enterprise

Estructura de Carpetas Enterprise

mi-plataforma/
├── .opencode/
│   ├── agents/                    # Definiciones JSON de cada agente
│   │   ├── orchestrator.json
│   │   ├── code.json
│   │   └── run.json
│   ├── skills/                    # Skills técnicos específicos
│   │   ├── terraform-guardian.json
│   │   └── k8s-gitops.json
│   ├── policies/                  # Reglas de gobernanza
│   │   └── security-baseline.md
│   └── audit/                     # Logs de auditoría
├── opencode.json                  # Configuración raíz
└── src/

Configuración Raíz: opencode.json

Ejemplo A: Configuración Balanceada (Recomendada para equipos medianos)

{
  "version": "enterprise-v1",
  "project": {
    "name": "nirvana-platform",
    "type": "platform-engineering"
  },
  "agent": {
    "nv-orchestrator": {
      "mode": "primary",
      "model": "claude-3-5-sonnet-20241022",
      "fallback_model": "gpt-4o",
      "max_tokens": 4096,
      "description": "Coordina y delega tareas. Nunca hace trabajo técnico directo.",
      "prompt": "Lee .opencode/policies/security-baseline.md. Analiza la petición y delega al sub-agente adecuado.",
      "include": ["*.md", "**/README.md"],
      "exclude": ["**/*.tfstate*", "**/.terraform/**"]
    },
    "nv-code": {
      "mode": "subagent",
      "model": "claude-3-5-sonnet-20241022",
      "description": "Generación de Terraform, K8s, Ansible. Especialista en IaC.",
      "prompt": "Valida sintaxis con 'terraform validate' antes de proponer cambios. Nunca hardcodees secrets.",
      "include": ["terraform/**/*.tf", "k8s/**/*.yaml"],
      "constraints": {
        "bash_allowed_commands": ["terraform validate", "terraform fmt", "terraform plan"],
        "bash_blocked_commands": ["terraform apply", "terraform destroy"],
        "require_approval": true,
        "approval_threshold": "high"
      }
    },
    "nv-run": {
      "mode": "subagent",
      "model": "gpt-4o-mini",
      "description": "Ejecución controlada de comandos. Solo lectura por defecto.",
      "prompt": "Agente de ejecución. Whitelist estricto. Requiere aprobación para mutaciones.",
      "constraints": {
        "bash_allowed_commands": ["kubectl get", "kubectl describe", "az aks show"],
        "bash_blocked_commands": ["kubectl delete", "kubectl apply", "terraform apply"],
        "require_approval": true,
        "approval_threshold": "high"
      }
    },
    "nv-fast": {
      "mode": "subagent",
      "model": "gpt-4o-mini",
      "description": "Tareas mecánicas: commits, exploración, linting.",
      "prompt": "Operaciones Git y exploración de código. Rápido y económico.",
      "max_tokens": 2048
    }
  },
  "security": {
    "secret_scanning": true,
    "audit_log": ".opencode/audit/session.log",
    "verbose": true,
    "timestamps": true,
    "color": "auto"
  },
  "context": {
    "include": ["**/*.tf", "**/*.yaml", "**/*.md"],
    "exclude": ["**/.git/**", "**/.terraform/**", "**/*.tfstate*"],
    "always_read": ["COMPLIANCE.md", ".opencode/policies/security-baseline.md"]
  }
}

• fallback_model: Modelo de respaldo si el primario falla (rate limit, caída).
• max_tokens: Límite hard de tokens (control de costos).
• include/exclude: Control granular del contexto (evita enviar tfstate o secrets a la IA).
• always_read: Archivos inyectados en CADA prompt (políticas de seguridad).
• bash_allowed_commands: Whitelist de comandos shell permitidos.
• bash_blocked_commands: Blacklist explícita (defensa en profundidad).
• require_approval: Forzar confirmación humana.
• approval_threshold: low/medium/high según el riesgo.

Ejemplo B: Configuración GitHub Copilot Enterprise (Para organizaciones con licencia Copilot)

{
  "agent": {
    "nv-orchestrator": {
      "mode": "primary",
      "model": "claude-3-5-sonnet-20241022",
      "fallback_model": "gpt-4o",
      "description": "Coordina y delega tareas de Platform Engineering a sub-agentes especializados. Nunca ejecuta código ni comandos directamente.",
      "prompt": "Eres el orquestador principal del sistema de Platform Engineering. Tu función es analizar solicitudes, determinar la complejidad y riesgo, y delegar al sub-agente adecuado. REGLAS: 1) NUNCA escribas código ni ejecutes comandos directamente. 2) SIEMPRE lee .opencode/policies/security-baseline.md al inicio. 3) Delega a: nv-think (arquitectura/seguridad), nv-code (IaC/manifests), nv-run (validación/lectura), nv-fast (tareas mecánicas). 4) Valida que el contexto incluya los archivos necesarios antes de delegar. 5) Resume la respuesta del sub-agente antes de presentarla al usuario."
    },
    "nv-think": {
      "mode": "subagent",
      "model": "claude-3-opus-20240229",
      "fallback_model": "claude-3-5-sonnet-20241022",
      "max_tokens": 8192,
      "description": "Razonamiento profundo: planificación de migraciones, análisis de seguridad, decisiones arquitectónicas, evaluación de riesgos.",
      "prompt": "Eres un sub-agente de arquitectura y análisis profundo. Tu objetivo es pensar antes de actuar. REGLAS: 1) Carga el SKILL.md indicado por el orquestador. 2) Analiza trade-offs, riesgos de seguridad, compliance y costos. 3) Genera diagramas de arquitectura en Mermaid cuando sea necesario. 4) Valida contra .opencode/policies/security-baseline.md. 5) NUNCA propongas soluciones que violen las políticas de seguridad. 6) Si detectas un riesgo crítico, alerta al orquestador para escalar a aprobación humana."
    },
    "nv-code": {
      "mode": "subagent",
      "model": "claude-3-5-sonnet-20241022",
      "fallback_model": "gpt-4o",
      "max_tokens": 4096,
      "description": "Generación de código, manifests Kubernetes, Terraform, Ansible, Pulumi, scripts de automatización. Especialista en IaC y GitOps.",
      "prompt": "Eres un sub-agente de generación de código e infraestructura. Especialista en Terraform, Kubernetes, y GitOps. REGLAS: 1) Carga el SKILL.md indicado. 2) SIEMPRE valida sintaxis antes de entregar (terraform validate, kubeconform, etc.). 3) NUNCA hardcodees secrets, passwords o tokens. Usa variables sensibles. 4) Incluye tags de costo obligatorios (Environment, Owner, Project, CostCenter). 5) Genera código idempotente y modular. 6) Si detectas un 'forces replacement' en Terraform, advierte EXPLÍCITAMENTE. 7) Prioriza recursos managed de cloud sobre self-hosted."
    },
    "nv-run": {
      "mode": "subagent",
      "model": "gpt-4o",
      "description": "Ejecución controlada de comandos: validaciones técnicas, operaciones de lectura sobre infraestructura, verificación de estado.",
      "prompt": "Eres un sub-agente de ejecución con privilegios limitados. Tu función es validar, no mutar. REGLAS: 1) Carga el SKILL.md indicado. 2) SOLO ejecuta comandos de la whitelist: terraform plan/validate/fmt, kubectl get/describe/logs/top, helm template/lint, az/aws/gcloud read-only. 3) NUNCA ejecutes: terraform apply/destroy, kubectl apply/delete, helm install/upgrade, rm -rf. 4) Si necesitas ejecutar un comando bloqueado, solicita aprobación explícita al orquestador. 5) Captura y analiza el output de los comandos. 6) Reporta errores con contexto completo.",
      "constraints": {
        "bash_allowed_commands": [
          "terraform plan",
          "terraform validate",
          "terraform fmt",
          "terraform show",
          "terraform state list",
          "terraform state show",
          "kubectl get",
          "kubectl describe",
          "kubectl logs",
          "kubectl top",
          "kubectl config current-context",
          "helm template",
          "helm lint",
          "helm get values",
          "az account show",
          "az aks show",
          "az resource list",
          "aws sts get-caller-identity",
          "aws configure list",
          "gcloud config list",
          "docker images",
          "docker ps",
          "git status",
          "git log --oneline -10",
          "git diff --stat"
        ],
        "bash_blocked_commands": [
          "terraform apply",
          "terraform destroy",
          "terraform force-unlock",
          "kubectl apply",
          "kubectl delete",
          "kubectl create",
          "kubectl patch",
          "kubectl edit",
          "kubectl exec",
          "kubectl port-forward",
          "helm install",
          "helm upgrade",
          "helm uninstall",
          "helm rollback",
          "az aks delete",
          "aws ec2 terminate-instances",
          "gcloud compute instances delete",
          "docker rm",
          "docker rmi -f",
          "rm -rf",
          "sudo",
          "chmod 777",
          "curl *|*sh",
          "wget *|*sh"
        ],
        "require_approval": true,
        "approval_threshold": "high"
      }
    },
    "nv-fast": {
      "mode": "subagent",
      "model": "gpt-4o-mini",
      "description": "Tareas rápidas y mecánicas de bajo riesgo: exploración de repositorios, operaciones Git, GitHub CLI, linting básico.",
      "prompt": "Eres un sub-agente de operaciones mecánicas. Optimizado para velocidad y bajo costo. REGLAS: 1) Carga el SKILL.md indicado. 2) Tareas permitidas: git add/commit/push/branch, gh pr create/list, exploración de directorios, búsqueda de archivos, linting con herramientas locales. 3) NUNCA modifiques código funcional sin pasar por nv-code. 4) NUNCA ejecutes comandos de infraestructura (deja eso a nv-run). 5) Sé conciso en tus respuestas.",
      "max_tokens": 2048,
      "cost_optimization": {
        "cache_context": true,
        "compress_history": true
      }
    }
  },
  "security": {
    "secret_scanning": true,
    "audit_log": ".opencode/audit/session.log",
    "verbose": true,
    "timestamps": true,
    "color": "auto"
  },
  "context": {
    "include": ["**/*.tf", "**/*.yaml", "**/*.yml", "**/*.json", "**/*.md", "**/*.sh"],
    "exclude": [
      "**/.git/**",
      "**/.terraform/**",
      "**/*.tfstate*",
      "**/crash.log",
      "**/node_modules/**",
      "**/vendor/**",
      "**/secrets/**",
      "**/*.pem",
      "**/*.key"
    ],
    "always_read": [
      "README.md",
      "ARCHITECTURE.md",
      "COMPLIANCE.md",
      ".opencode/policies/security-baseline.md"
    ]
  }
}

5. Skills Especializados para Platform Engineering

Skill 1: Terraform Guardian

{
  "name": "terraform-guardian",
  "trigger": "tf-module",
  "description": "Genera módulos Terraform con validación de seguridad y cost estimation",
  "instruction": "Al activarse con 'tf-module':\n1. Genera estructura: main.tf, variables.tf (con validaciones), outputs.tf, README.md\n2. REGLAS DE SEGURIDAD:\n   - NUNCA hardcodees secrets\n   - Incluye tags de costo (Owner, Project, Environment)\n   - Usa data sources para recursos existentes\n3. Valida 'terraform fmt' y 'terraform validate' mentalmente\n4. Si detectas 'forces replacement', advierte EXPLÍCITAMENTE",
  "context_files": ["terraform/providers.tf"],
  "validation_hooks": ["terraform validate"]
}

opencode "tf-module: Crear Storage Account de Azure con soft-delete"

Skill 2: Kubernetes GitOps

{
  "name": "k8s-gitops",
  "trigger": "deploy-k8s",
  "description": "Genera manifests K8s con Kustomize y seguridad PSS",
  "instruction": "Al activarse con 'deploy-k8s':\n1. Estructura: base/ + overlays/{dev,prod}/\n2. SEGURIDAD:\n   - securityContext: runAsNonRoot, readOnlyRootFilesystem\n   - NUNCA uses 'latest' en imágenes\n   - Genera NetworkPolicy (deny-all por defecto)\n3. Secrets: Usa External Secrets Operator, nunca valores planos",
  "validation": {
    "kubeconform": true,
    "policy": "restricted"
  }
}

Skill 3: CI/CD Architect

{
  "name": "cicd-architect",
  "trigger": "pipeline",
  "description": "Diseña pipelines GitHub Actions con SAST y OIDC",
  "instruction": "Diseña workflow con:\n1. Fases: Lint → SAST (Semgrep/Trivy) → Build → Sign (Cosign) → Deploy\n2. Usa OIDC para auth cloud (nunca long-lived credentials)\n3. Pinnea acciones a SHA específicos, no tags @v2\n4. Incluye etapa de terraform plan en PRs"
}

Repositorios de Skills para OpenCode

6. Comandos de la CLI (Interfaz de Línea de Comandos)

Comandos Básicos

# Modo interactivo
opencode

# Ejecución directa (ZEN mode)
opencode --zen "Refactorizar auth.ts a clase"

# Ejecutar skill específico
opencode --skill terraform-guardian "Crear módulo VPC"

# Verificar configuración
opencode --check-config

Comandos Enterprise y Seguridad

# Ver contexto actual (debug)
opencode context --list

# Escanear secretos en el repo
opencode scan-secrets

# Ver audit log
opencode audit --session

# Ejecutar como sub-agente específico
opencode --agent nv-code "Generar Terraform"
opencode --agent nv-run --require-approval "terraform plan"

Flag	Descripción
--help / -h	Ayuda general
--version / -v	Versión instalada
--verbose	Logs detallados de tokens y contexto
--no-stream	Muestra respuesta completa al final
--dry-run	Simulación sin modificar archivos
--zen	Modo no interactivo (CI/CD)
--agent [nombre]	Forzar uso de agente específico
--skill [nombre]	Activar skill concreto

Creación de Alias (Bash/Zsh)

# ~/.bashrc o ~/.zshrc
alias oc='opencode'
alias oc-zen='opencode --zen'
alias oc-tf='opencode --skill terraform-guardian'
alias oc-k8s='opencode --skill k8s-gitops'
alias oc-safe='opencode --agent nv-run --require-approval'

7. Flujo de Trabajo Recomendado

Ciclo de Trabajo Seguro

# 1. Antes de empezar, commit de seguridad
git add .
git commit -m "checkpoint: antes de usar OpenCode"

# 2. Iniciar con contexto limpio
opencode context --clear

# 3. Trabajar con el orquestador
opencode "Necesito crear un módulo Terraform para PostgreSQL HA en Azure"

# 4. El orquestador delega:
#    - nv-think: Diseña arquitectura (zonas, SKU)
#    - nv-code: Genera código Terraform
#    - nv-run: Ejecuta terraform plan (modo lectura)

# 5. Revisar el diff antes de aplicar
git diff
# o
opencode --agent nv-run "terraform show plan.tfplan"

# 6. Solo si se aprueba explícitamente:
opencode --agent nv-run --approve "terraform apply"

Mejores Prácticas Enterprise

1. Commits Pequeños: Haz git commit antes de cualquier operación grande. Si la IA rompe algo: git reset --hard HEAD.
2. Contexto Limpio: No incluyas node_modules/, .terraform/ o *.tfstate en el contexto (usa exclude en opencode.json).
3. Revisión Humana: Nunca configures autoApply: true en producción. Usa siempre require_approval: true.
4. Separación de Agentes: Usa nv-code para escribir, nv-run para validar, nunca mezcles permisos.

---

8. Preguntas Frecuentes (FAQ) y Troubleshooting

Problema 1: «Error: Rate limit exceeded»

• Espera unos minutos o upgradea tu plan.
• Configura fallback_model en opencode.json para que cambie automáticamente de proveedor.
• Reduce max_tokens para disminuir el consumo.

Problema 2: «OpenCode ignora mis archivos»

opencode context --list  # Ver qué archivos carga

• Revisa include y exclude en opencode.json.
• Asegúrate de que los patrones glob (ej. src/**/*.ts) sean correctos.

Problema 3: «La IA escribe código que no compila»

• Añade package.json, go.mod, requirements.txt o versions.tf al always_read.
• Usa el skill específico para tu stack (ej. terraform-guardian valida sintaxis).

Problema 4: «El comando opencode no se encuentra»

# Reinstalar
npm install -g opencode

# Recargar PATH
hash -r  # Linux/macOS
# o reiniciar terminal en Windows

Problema 5: «Costos de API muy altos»

• Usa nv-fast (GPT-4o-mini) para tareas mecánicas.
• Limita max_tokens (ej. 2048 para tareas simples).
• Excluye archivos binarios/logs del contexto.

Problema 6: «OpenCode sugiere cambios que violan políticas de seguridad»

• Verifica que always_read incluya .opencode/policies/security-baseline.md.
• Usa opencode --verbose para confirmar que el archivo se inyecta en el prompt.

Anexos

Anexo A: Plantilla Mínima para Empezar

{
  "agent": {
    "nv-orchestrator": {
      "mode": "primary",
      "model": "claude-3-5-sonnet-20241022",
      "prompt": "Coordina tareas de Platform Engineering."
    },
    "nv-code": {
      "mode": "subagent",
      "model": "gpt-4o",
      "constraints": {
        "require_approval": true
      }
    }
  },
  "security": {
    "secret_scanning": true,
    "audit_log": ".opencode/audit.log"
  }
}

Anexo B: Integración Pre-commit

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: opencode-security
        name: Security Scan
        entry: opencode scan-secrets
        language: system
        pass_filenames: false

:wq!