opencodeagents.mdconfiguracionequiposproviders

Configuración Avanzada de OpenCode: AGENTS.md, Providers Personalizados y Flujos de Equipo

Published on June 24, 2026By Binary Core

Cuando pasas de usar OpenCode individualmente a implementarlo en un equipo técnico, necesitas configuraciones avanzadas: archivos AGENTS.md estandarizados, providers alternativos, skills reutilizables y flujos consistentes.

Este tutorial asume que ya tienes OpenCode instalado y dominas el flujo Plan/Build para desarrollo de features. Aquí profundizamos en la personalización profesional.

AGENTS.md: El Cerebro de tu Proyecto

El archivo AGENTS.md en la raíz del proyecto le dice a OpenCode cómo trabajar en tu código. Un buen AGENTS.md reduce prompts repetitivos y estandariza la calidad.

Estructura recomendada

markdown
# AGENTS.md

## Project Identity

- **Stack:** Next.js 15, TypeScript, Prisma, PostgreSQL
- **Testing:** Vitest, Playwright
- **Styling:** Tailwind CSS, shadcn/ui
- **Architecture:** Clean Architecture + Feature-based folders

## Developer Commands

```bash
npm install          # Instalación de dependencias
npm run dev          # Desarrollo local
npm run build        # Build de producción
npm test             # Tests unitarios
npm run test:e2e     # Tests E2E con Playwright

Critical Gotchas

Nunca uses any en TypeScript — siempre unknown + type guards
E2E requieren build previo: npm run build antes de test:e2e
Todos los componentes UI deben ser accesibles (WCAG AA mínimo)
No commits sin tests que pasen

Code Conventions

TypeScript

Preferir tipos de dominio sobre primitivos (UserId vs string)
Usar Result<T, E> para operaciones que pueden fallar
Type guards reutilizables en @/lib/guards.ts

React

Server Components por defecto
"use client" solo cuando sea estrictamente necesario
Custom hooks en @/hooks/, no lógica en componentes

Testing

Estructura: Given-When-Then
Mocks en __mocks__/, factories en __tests__/factories/


### Variables de entorno y secretos

OpenCode puede leer `.env` pero nunca lo incluyas en prompts compartidos:

Usa DATABASE_URL desde el entorno, no hardcodees conexiones.


## Providers Personalizados

Mientras OpenCode Zen es conveniente, muchos equipos prefieren control total sobre sus LLM.

### Configuración de OpenAI

```bash
# En tu shell
export OPENAI_API_KEY=sk-...

Luego en OpenCode:

/connect
# Selecciona "openai"

Anthropic Claude

bash
export ANTHROPIC_API_KEY=sk-ant-...

Claude es especialmente bueno para:

Refactors complejos de arquitectura
Análisis de código con mucho contexto
Explicaciones didácticas

Ollama (Uso Local)

Para equipos con requisitos de privacidad o sin conexión:

bash
# Instala Ollama
ollama pull codellama:34b
ollama pull deepseek-coder:33b

/connect
# Selecciona "ollama"
# Elige el modelo que hayas descargado

Trade-offs de local:

Aspecto	Local (Ollama)	Cloud (OpenAI/Claude)
Costo	Hardware propio	Por token
Privacidad	100% local	Depende del provider
Calidad de código	Variable según modelo	Consistentemente alta
Latencia	Depende de GPU	~1-3 segundos
Contexto largo	Limitado (4K-8K)	Hasta 200K tokens

Skills y Workflows Reutilizables

Las Skills son plantillas de prompts que puedes reutilizar. Úsalas para patrones comunes en tu equipo.

Creando un Skill

Guarda en .opencode/skills/refactor-to-result-type.md:

markdown
---
description: Refactoriza funciones que retornan null/undefined para usar Result<T, E>
---

Refactoriza la función {{functionName}} en {{filePath}} para usar el patrón Result<T, E>.

Requisitos:
1. Cambiar el retorno de `{{oldReturnType}}` a `Result<{{oldReturnType}}, DomainError>`
2. Usar las factory functions `ok()` y `err()` de `@/lib/result.ts`
3. Actualizar todos los call sites para manejar el Result con `match()` o `unwrap()`
4. Añadir tests que cubran los casos de error

Ejemplo de resultado esperado:
```typescript
// Antes:
async function findUser(id: string): Promise<User | null>

// Después:
async function findUser(id: string): Promise<Result<User, NotFoundError>>


### Usando un Skill

/skill refactor-to-result-type functionName: getAccountBalance filePath: @src/services/AccountService.ts


## MCP Servers: Integración con Infraestructura

Los **Model Context Protocol (MCP)** servers permiten que OpenCode interactúe con herramientas externas.

### Configuración básica

En `.opencode/mcp.json`:

```json
{
  "servers": [
    {
      "name": "database",
      "command": "npx",
      "args": ["@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    },
    {
      "name": "filesystem",
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    }
  ]
}

Consultando la base de datos

Con el MCP server configurado:

Muestra el esquema de la tabla transactions y genera 
un tipo TypeScript que coincida exactamente.

Flujos de Equipo Estandarizados

Pre-commit con OpenCode

bash
#!/bin/bash
# .git/hooks/pre-commit

# Ejecutar typecheck
npm run type-check || exit 1

# Ejecutar lint
npm run lint || exit 1

# Ejecutar tests unitarios
npm run test:unit || exit 1

PR Review asistida

Antes de abrir un PR, pide a OpenCode:

Revisa este cambio como si fueras un senior engineer:
1. ¿Hay lógica de negocio que debería estar en tests?
2. ¿Algún tipo de TypeScript podría ser más restrictivo?
3. ¿Hay código duplicado que podría extraerse?
4. ¿Las dependencias nuevas son necesarias?
5. ¿El naming sigue las convenciones del proyecto?

Contexto: @AGENTS.md
Archivos modificados: @src/services/PaymentService.ts @src/components/PaymentForm.tsx

Onboarding de nuevos desarrolladores

El AGENTS.md documentado permite que OpenCode onbordee automáticamente:

Eres un nuevo desarrollador en este proyecto. Basándote en 
@AGENTS.md, explícame:
1. Cómo levantar el entorno local
2. La estructura de carpetas y qué va dónde
3. Cómo correr tests y qué cobertura esperamos
4. El flujo para hacer un cambio de principio a fin

Debugging con OpenCode Avanzado

Análisis de errores de CI

Pega el error del log de CI:

Este test falla en CI pero pasa localmente:

Error: connect ECONNREFUSED 127.0.0.1:5432


El test está en @tests/integration/database.test.ts.
¿Qué configuración de CI podría faltar?

Optimización de performance

Analiza @src/components/DataTable.tsx y sugiere optimizaciones 
para renderizar 10,000 filas sin lag. Considera:
- Virtualización
- Memoización
- Lazy loading de datos

Seguridad

Revisa @src/api/auth.ts y @src/middleware/auth.ts por 
vulnerabilidades de seguridad comunes:
- Inyección SQL
- XSS
- CSRF
- JWT mal configurados
- Secrets en código

Métricas de Uso en Equipo

Rastrea cómo el equipo usa OpenCode:

/metrics

Muestra:

Tokens consumidos por proyecto
Tiempo ahorrado vs desarrollo manual
Tasa de éxito de prompts (ejecuciones sin /undo)
Features más comúnmente solicitadas

Troubleshooting de Configuración

Problema	Diagnóstico	Solución
OpenCode no respeta convenciones	AGENTS.md no cargado	Verifica ubicación en raíz y formato markdown
MCP server no conecta	Permisos o puerto	Revisa logs con `/status` y firewall
Skills no disponibles	Ruta incorrecta	Confirma `.opencode/skills/*.md`
Provider lento o falla	Rate limits	Configura retries o cambia de modelo
Contexto insuficiente	Archivos grandes	Usa `@` para referenciar específicamente

Migración de Contexto entre Proyectos

Si tu stack es consistente entre proyectos, copia el AGENTS.md base y ajusta:

bash
# Template reutilizable
cp ~/templates/AGENTS.md ./AGENTS.md
# Editar Project Identity y rutas específicas

Conclusión: OpenCode como Infraestructura

A este nivel, OpenCode deja de ser una herramienta individual y se convierte en infraestructura de equipo:

Onboarding automatizado vía AGENTS.md
Consistencia de código mediante skills y convenciones
Revisión asistida por IA antes de PRs humanos
Integración con tu stack via MCP servers

En Binary Core, mantenemos un repositorio templates/ con AGENTS.md y skills para cada stack que usamos (Next.js/PostgreSQL, Python/FastAPI, Rust/Actix). Cada nuevo proyecto hereda estas configuraciones y el equipo es productivo desde el día uno.

El tiempo invertido en configurar OpenCode profesionalmente se paga con intereses: desarrolladores más rápidos, código más consistente y menos tiempo en revisiones de estilo.

¿Tienes dudas sobre configuraciones específicas? El comando /help advanced dentro de OpenCode tiene referencias detalladas de cada feature.

Serie completa:

Instalación y primeros pasos
Flujo de trabajo Plan/Build
Configuración avanzada (este artículo)

Binary Core

Equipo Binary Core

← Back to blog