# Configuración básica para programar con un agente de IA: Claude Code y OpenCode

Guía de Bitflow Solutions. Versión web: https://bitflow-solutions.com/guias-tecnicas/agente-ia-programar-claude-code-opencode/

## ¿Qué vas a aprender?

- Qué hace un **agente de programación** y en qué se diferencia de un chat.
- Instalar **Claude Code** y **OpenCode** en Windows y comprobar que funcionan.
- Conectar tu cuenta o el proveedor de modelos y elegir el modelo.
- Darle al agente el contexto de tu proyecto con `CLAUDE.md` o `AGENTS.md`.
- Configurar permisos para que no lea tus secretos ni ejecute lo que no quieras.
- Los comandos del día a día, cómo deshacer y cómo trabajar con seguridad.

## Requisitos previos

- **Windows 10** (versión 1809 o posterior) con **PowerShell**; los comandos equivalentes para macOS y Linux están en cada paso.
- Para **Claude Code**: un plan **Pro**, **Max**, **Team** o **Enterprise** de Claude, o una cuenta de **Claude Console** (API). El plan gratuito de Claude no incluye Claude Code.
- Para **OpenCode**: una cuenta de un proveedor de modelos (Anthropic, OpenAI, GitHub Copilot…) o modelos en tu equipo con Ollama (ver la guía de Ollama).
- **Git** (en Windows, Git for Windows, recomendado: Claude Code usa Git Bash si está instalado y, si no, PowerShell).
- Un proyecto en un repositorio Git, para poder revisar y deshacer los cambios del agente.

## Paso a paso

### Instalar Claude Code (Windows)

```powershell
# Instalador nativo (recomendado): no necesita Node.js y se actualiza solo
irm https://claude.ai/install.ps1 | iex

# Alternativa con WinGet (se actualiza con winget upgrade Anthropic.ClaudeCode)
winget install Anthropic.ClaudeCode

# Abre una terminal nueva y comprueba
claude --version
claude doctor
```

```bash
# macOS, Linux o WSL
curl -fsSL https://claude.ai/install.sh | bash
```

### Instalar OpenCode

```powershell
# Windows: descomprime el zip de OpenCode para Windows (x64 o ARM64) que enlaza opencode.ai/docs,
# por ejemplo en C:\herramientas\opencode, y añade esa carpeta a tu PATH de usuario:
$actual = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$actual;C:\herramientas\opencode", 'User')

# Abre una terminal nueva y comprueba
opencode --version
```

```bash
# macOS o Linux: script oficial
curl -fsSL https://opencode.ai/v2/install | bash

# o con Homebrew
brew install anomalyco/tap/opencode-v2

# o con npm (en cualquier sistema con Node.js)
npm install -g @opencode/cli

# Actualizar más adelante
opencode upgrade
```

### Iniciar sesión y elegir el modelo

```powershell
# Claude Code: entra en tu proyecto y arranca; la primera vez abre el navegador para iniciar sesión
cd C:\proyectos\mi-aplicacion
claude
claude auth status          # comprueba con qué cuenta estás conectado

# OpenCode: arranca y, dentro, conecta un proveedor y elige el modelo
opencode
#   /connect   -> eliges el proveedor (Anthropic, OpenAI, GitHub Copilot, Ollama…) e introduces las credenciales
#   /models    -> eliges el modelo

# OpenCode también desde la línea de comandos
opencode auth login
opencode auth list
opencode models
```

### AGENTS.md / CLAUDE.md de ejemplo

```markdown
# Mi aplicación

## Comandos
- Instalar dependencias: npm install
- Ejecutar las pruebas: npm test
- Comprobar el estilo: npm run lint

## Convenciones
- TypeScript estricto; nada de any.
- Cada cambio de lógica va con su prueba.
- No toques los archivos de la carpeta migrations/ sin pedirlo.

## Antes de terminar
- Ejecuta npm test y npm run lint y corrige lo que falle.
```

### Permisos en Claude Code (.claude/settings.json)

```json
{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}
```

### Permisos y modelo en OpenCode (opencode.json)

```json
{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-5-5",
  "permissions": [
    { "action": "shell", "resource": "npm test*", "effect": "allow" },
    { "action": "read", "resource": "*.env", "effect": "deny" },
    { "action": "read", "resource": "*.env.*", "effect": "deny" }
  ]
}
```

### Comandos del día a día

| Qué quieres hacer | Claude Code | OpenCode |
|---|---|---|
| Conversación nueva | /clear | /new |
| Cambiar de modelo | /model | /models |
| Señalar un archivo | @ruta | @ruta |
| Comando de la terminal | ! | ! |
| Interrumpir | Esc | Esc |
| Deshacer | Esc Esc o /rewind | /undo, /redo |
| Resumir el contexto | /compact | Ctrl+X C |
| Sesiones anteriores | /resume | /sessions |
| Planificar sin editar | Shift+Tab (modo plan) | Shift+Tab (agente Plan) |

```powershell
# Una petición sin abrir la interfaz (útil en scripts)
claude -p "Explica qué hace la carpeta src/servicios"
opencode run "Explica qué hace la carpeta src/servicios"

# Retomar el trabajo
claude -c                    # la última conversación de esta carpeta
claude -r "nombre-o-id"      # una sesión concreta
```

### Revisar los cambios con Git

```powershell
# Antes de empezar: deja el repositorio limpio
git status
git switch -c agente/nueva-funcionalidad

# Al terminar: revisa todo lo que ha cambiado antes de confirmarlo
git diff
git add -p
```

## Errores habituales

- **«claude» no se reconoce como comando**: La carpeta del instalador no está en el PATH. Comprueba que existe `%USERPROFILE%\.local\bin\claude.exe` con `Test-Path "$env:USERPROFILE\.local\bin\claude.exe"`, añádela a tu PATH de usuario como en el paso 3 (con esa carpeta) y abre una terminal nueva.
- **«opencode» no se reconoce como comando**: La carpeta donde descomprimiste el zip no está en el PATH, o la terminal es anterior al cambio. Revisa la ruta del paso 3 y abre una terminal nueva.
- **Claude Code no encuentra Git Bash**: Busca dónde está Git con `where.exe git` e indica la ruta de `bash.exe` en `settings.json`: `"env": { "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe" }`.
- **Sesión caducada o «Not logged in»**: En Claude Code, vuelve a iniciar sesión con `/login` o `claude auth login` y comprueba que la hora de tu equipo es correcta. En OpenCode, vuelve a conectar el proveedor con `/connect` y revisa con `opencode auth list`.
- **No funciona detrás del proxy de la empresa**: Define el proxy antes de instalar y de arrancar: `$env:HTTPS_PROXY = 'http://proxy.ejemplo.com:8080'` y lo mismo con `HTTP_PROXY`. OpenCode también admite `NO_PROXY` y `NODE_EXTRA_CA_CERTS` para la CA de la empresa.
- **Claude Code no encuentra archivos al buscar**: Instala ripgrep (`winget install BurntSushi.ripgrep.MSVC`), añade `"USE_BUILTIN_RIPGREP": "0"` en el bloque `env` de `settings.json` y comprueba con `claude doctor`.
- **El agente ha leído o modificado algo que no debía**: Deshaz el cambio (`/rewind` en Claude Code, `/undo` en OpenCode, o `git restore`) y añade la regla de `deny` que faltaba. Con `/permissions` revisas en Claude Code las reglas activas.

## Siguientes pasos

- Usar modelos en tu propio equipo con Ollama, sin enviar el código fuera (ver la guía de Ollama).
- Acordar con el equipo un `CLAUDE.md` o `AGENTS.md` común y la revisión obligatoria del código que genera el agente.
- Conectar herramientas externas con servidores MCP (en OpenCode, `opencode mcp add`).
- Usar el agente en pipelines con `claude -p` u `opencode run` (ver la guía de CI/CD con GitHub Actions).
