Integración con Anthropic Claude Code

Guía técnica para gobernar flujos interactivos y de terminal con Claude Code utilizando RAPID OS v3.

---

1. Qué es Claude Code y cómo encaja con RAPID OS

Claude Code es una herramienta de desarrollo en línea de comandos de Anthropic diseñada para operar directamente sobre bases de código mediante herramientas de edición, búsqueda y ejecución de comandos.

Encaje con RAPID OS: Claude Code opera como el agente ejecutor externo. RAPID OS opera como el marco de gobernanza, definiendo la especificación previa, controlando el riesgo arquitectónico y evaluando mediante evidencia determinista que todo lo prometido se haya cumplido antes de dar por buena la tarea.

---

2. Configuración en RAPID OS

RAPID OS incluye el identificador de perfil claude:

rapid harness show claude

Perfil declarativo:

• context.consume: supported
• repository.read: supported
• workspace.current: supported
• Otras capacidades: marcadas como unknown hasta que el entorno local las configure explícitamente en el proyecto.

---

3. Configuración en Claude Code

1. Inicia sesión en Claude Code siguiendo las guías oficiales (claude login).
2. Concede permisos para ejecutar tests locales y editar archivos según las políticas de tu equipo.
3. Asegura que Claude Code lea el archivo .rapid-os/standards/ para alinearse con los estándares arquitectónicos del proyecto.

---

Flujo principal: shortcuts

La forma recomendada de trabajar con Claude Code es con los shortcuts /rapid-<modo>. Los 9 shortcuts, el bucle que siguen, la aprobación humana y los errores frecuentes están en la guía de shortcuts.

Instalación

rapid init --shortcuts                                # al inicializar el proyecto
rapid shortcuts install --harness claude              # en un proyecto ya inicializado
rapid shortcuts install --harness claude --hooks      # además, los hooks (sección 6)

Genera .claude/skills/rapid-*/SKILL.md (los 9 shortcuts; documentación de skills). Tras actualizar Rapid OS, vuelve a ejecutar rapid shortcuts install.

Primer paso: /rapid-init (onboarding)

El punto de entrada de un proyecto es /rapid-init: conduce el onboarding (rapid setup next), te pregunta el stack de cada componente, la arquitectura, los servicios y los documentos, y revisa contigo los borradores antes de cerrar. Después usas /rapid-feature y los demás modos. Ver Primer proyecto.

Para tener /rapid-init y los demás shortcuts en todos tus proyectos sin instalarlos en cada uno, instálalos en tu carpeta de usuario (~/.claude/skills/); el instalador de Rapid OS te lo pregunta al terminar:

rapid shortcuts install --global --harness claude

Los shortcuts y los hooks ejecutan rapid desde el shell del agente: si no está en el PATH, rapid init y rapid doctor avisan con RAPID1414 (aviso, no error). Ver la guía de shortcuts.

Invocación

Escribe /rapid- en Claude Code y elige un shortcut, o lánzalo directamente:

/rapid-feature añadir exportación CSV al informe mensual

• Claude Code es el único harness que ejecuta la línea !`rapid next --json` antes de enviar el prompt; si ese comando falla, el skill se aborta, así que rapid debe estar en el PATH.
• allowed-tools pre-aprueba solo rapid next, start, check, task, finish y status (y attach en /rapid-research); nunca approve ni abort.
• /rapid-approve lleva disable-model-invocation y no aprueba: te da el comando para tu terminal. Aprueba siempre en tu propia terminal, no con el modo ! de Claude Code (RAPID1310).

---

Modo avanzado (comandos v3)

Los comandos v3 (rapid spec, rapid run, rapid evidence, rapid eval…) siguen disponibles para CI, depuración y auditoría, y tampoco hace falta usarlos a mano en el día a día. Las secciones 4 y 5 conservan el flujo manual completo.

4. Flujo de Trabajo Gobernado

1. Crear Spec y Run en RAPID OS:

rapid spec create --id spec-feature --title "Nueva funcionalidad" --mode feature --task "T001: Implementar funcionalidad" --status ready
rapid context --manifest
rapid run create --spec spec-feature --harness claude

2. Verificar y Registrar Baseline: Ejecuta la suite base de pruebas guardando el log auténtico como artefacto (base.log), registra la evidencia de baseline (conforme a la estructura de evidence_baseline.json) y reconoce la compuerta antes de activar el run:

python -m unittest discover -s tests -t . > base.log 2>&1
rapid evidence add --run <run-id> --input evidence_baseline.json
rapid run gate <run-id> gate.baseline acknowledged

3. Instruir a Claude Code: Pide a Claude Code en la terminal:

"Lee la especificación en .rapid-os/specs/spec-feature/spec.json y el contrato en .rapid-os/runs/<run-id>/contract.json. Implementa los cambios necesarios y corre la suite de pruebas."

4. Ejecución Externa: Claude Code edita los archivos y corre python -m unittest.

5. Captura e Ingesta de Evidencias: El desarrollador o el propio Claude Code invoca el CLI de RAPID OS para registrar el avance (ver la estructura canónica de cada archivo en el laboratorio Bajo el capó):

• evidence_files.json: evidencia de modificación de archivos (file_change).
• evidence_tests.json: resultados de pruebas aprobadas con su archivo de log adjunto (test_result).
• evidence_workspace.json: verificación de espacio de trabajo actual (workspace).
• evidence_review.json: revisión contractual aprobada (review).

rapid run status <run-id> active
rapid run task <run-id> T001 in_progress
rapid evidence add --run <run-id> --input evidence_files.json
rapid evidence add --run <run-id> --input evidence_tests.json
rapid evidence add --run <run-id> --input evidence_workspace.json
rapid evidence add --run <run-id> --input evidence_review.json
rapid run gate <run-id> gate.tests acknowledged
rapid run gate <run-id> gate.final-verification acknowledged
rapid run task <run-id> T001 done
rapid run status <run-id> finished

6. Evaluación:

rapid eval run --run <run-id> --write --require-pass

---

5. Problemas Frecuentes

• Claude Code edita sin correr pruebas: La evaluación marcará fail o unverified si no se aporta evidencia con test_result válido.
• Rutas no canónicas: Las rutas en los payloads de evidencia deben ser rutas relativas POSIX (ej. src/app.py, no rutas absolutas con C:\).

---

6. Hooks de Claude Code (refuerzo opcional del bucle)

Los hooks refuerzan el flujo principal con shortcuts; no forman parte del modo avanzado.

Los hooks de Claude Code ejecutan un comando en puntos del ciclo del agente (documentación oficial). Rapid OS aporta dos, rapid hook stop y rapid hook pre-tool, para que el agente no se detenga a mitad de un run, no lance comandos reservados a la persona y no edite .rapid-os/.

Los hooks los ejecuta Claude Code, no Rapid OS: Rapid OS sigue sin invocar agentes. Solo responden con una parada bloqueada o una herramienta denegada.

Instalación

rapid shortcuts install --harness claude --hooks
rapid shortcuts install --harness claude --hooks --dry-run --json   # ver qué cambiaría
rapid shortcuts remove --harness claude --hooks                      # quita solo lo propio

Fusiona en .claude/settings.json del proyecto un grupo Stop y un grupo PreToolUse (matcher Bash|PowerShell|Write|Edit|MultiEdit|NotebookEdit) cuyo comando es rapid con los argumentos hook stop / hook pre-tool (forma exec de Claude Code: sin shell, igual en Linux, macOS y Windows). No toca otras claves ni los hooks del usuario, hace una copia .bak y es idempotente. rapid init --shortcuts no instala hooks: hay que pedirlos con --hooks (en rapid init o en rapid shortcuts install).

rapid debe estar en el PATH del equipo donde corre Claude Code (por ejemplo con pipx install git+https://github.com/alyconr/Rapid-OS.git). Si no se resuelve, Claude Code lo trata como un error no bloqueante y el refuerzo deja de actuar; rapid doctor lo avisa con RAPID1339.

Qué hace Stop

Bloquea la parada con la razón (instructions más el comando exacto) mientras rapid next proponga run_baseline, activate, implement_task, verify o finish. No bloquea en author_spec, await_human_approval, blocked (tampoco cuando se propone rapid abort tras un --reject), done ni sin sesión.

Guarda de bucle: como máximo hooks.max_stop_blocks bloqueos consecutivos (3 por defecto) por sesión y acción; configurable en .rapid-os/config.json:

{ "hooks": { "max_stop_blocks": 3 } }

Claude Code aplica además su propio tope de continuaciones consecutivas.

Qué hace PreToolUse

Acción del agente	Resultado
rapid approve …, rapid run gate …, rapid run status …, rapid evidence add …, rapid spec status …, rapid abort	Denegado. Para approve el motivo da el comando exacto que la persona debe teclear en su terminal.
rapid status, next, check, task, attach, finish, start	Permitido.
Write, Edit, MultiEdit, NotebookEdit sobre .rapid-os/	Denegado.
Comandos de shell que escriben en .rapid-os/ (>, >>, tee, cp, mv, rm, sed -i, find -delete, …)	Denegado.
Quitar o redefinir CLAUDE_CODE_CHILD_SESSION o CLAUDECODE (env -u, env --unset, env -i, unset, prefijos VAR= o VAR=0, export, Remove-Item Env:, $env:VAR = …)	Denegado, con un motivo que remite a rapid next: esas variables son lo que hace que rapid approve se niegue a correr dentro de una sesión de agente.
rapid approve --help (o -h)	Permitido: solo imprime la ayuda.

También se detectan python -m rapid_os …, python rapid.py …, rutas absolutas al ejecutable, prefijos de entorno (VAR=1 rapid …), sudo/env/timeout, comandos que ejecutan una cadena (bash -c, bash -xc, script -qec, su -c, eval) y find … -exec, además de comandos encadenados o anidados (;, &&, ||, |, $(…), comillas invertidas). script merece mención aparte: da una terminal al comando, así que junto con env -u CLAUDE_CODE_CHILD_SESSION permitiría esquivar la comprobación de TTY de rapid approve; por eso se analiza igual que bash -c y se deniega quitar esas variables.

Defensa en profundidad en rapid approve. Los hooks no son la única barrera: rapid approve rechaza (RAPID1310) cuando falta un TTY, cuando CLAUDE_CODE_CHILD_SESSION vale 1 y, además, cuando algún proceso ancestro es el binario claude (se recorre la cadena de procesos padre con la biblioteca estándar). La detección por ascendencia es de mejor esfuerzo: un proceso que se desacopla de su padre (doble fork, setsid, nohup … &) pasa a colgar de init y deja de tener a claude como ancestro; junto al claude.exe renombrado y el pid reutilizado de un padre ya muerto, es un límite conocido. La regla sigue siendo que una persona apruebe en su propia terminal. Si la ascendencia no se puede leer, no se rechaza por ello y rapid doctor lo avisa (RAPID1319). Una persona que aprueba en su propia terminal no se ve afectada.

La detección de comandos es de mejor esfuerzo. Analiza la línea de comandos que ve el hook; no puede impedir que un agente decidido construya el comando en tiempo de ejecución ni que escriba en .rapid-os/ con un lenguaje de programación. Los hooks refuerzan el bucle, no sustituyen la regla de que una persona apruebe en su terminal (rapid approve exige TTY y falla con RAPID1310).

Worktrees y errores

• La resolución del proyecto sube desde el cwd del payload hasta el primer .rapid-os/. Si el cwd es el worktree de rapid start --worktree, se usa el ledger del repositorio principal (el que guarda workspace_path en session.json).
• Sin proyecto: sin salida y exit 0.
• Cualquier error interno, un stdin que no es JSON o un .rapid-os/ corrupto: sin salida, exit 0 y una línea en .rapid-os/scratch/hooks.log. Un hook nunca debe romper al agente.