Claude Code es una herramienta de codificación agéntica que lee tu base de código, edita archivos, ejecuta comandos y trabaja directamente con git. Para un desarrollador solo en una única terminal, no necesita ningún tipo de gestión: describes el trabajo, lo ves suceder y revisas el diff. Ese ciclo es rápido, y nada en esta guía te pide que renuncies a él.
La brecha aparece cuando un equipo depende de él. Cinco desarrolladores ejecutando sesiones de Claude Code producen resultados reales, pero el trabajo vive en terminales privadas. Nadie puede responder a las preguntas sobre las que se apoya un equipo: quién pidió este cambio, quién lo está ejecutando ahora mismo, qué hizo realmente la ejecución y quién aceptó el resultado antes de que se fusionara. La ejecución es excelente; el registro del trabajo no existe.
La gestión de proyectos con Claude Code es la práctica de gestionar ese trabajo como trabajo de proyecto rastreado y revisable: una incidencia se convierte en una Tarea con alcance definido, la Tarea se asigna a un Agente que ejecuta a través de Claude Code, la ejecución se lleva a cabo en un worktree aislado en una máquina que tú controlas, y el resultado vuelve a una persona para su revisión. Esta guía recorre ese arco con Sharkly, que no es un sustituto de Claude Code. Añade la capa compartida de tareas, contexto, control y revisión en torno a la herramienta que tu equipo ya utiliza.
TL;DR
Para gestionar el trabajo de Claude Code como trabajo de proyecto, redacta la incidencia como una Tarea con alcance definido, con un objetivo, límites y criterios de aceptación; asígnala a un Agente cuyo Runtime sea Claude Code; deja que la ejecución se realice en una Computadora conectada en un worktree de git aislado mientras el progreso se transmite en tiempo real; después revisa la evidencia en la Tarea y acepta, solicita cambios o reasigna. Claude Code realiza la ejecución. Sharkly gestiona la asignación, el contexto, el progreso, los bloqueos, los resultados y la revisión humana a su alrededor, de modo que las ejecuciones en paralelo sigan siendo visibles para todo el equipo en lugar de desaparecer en terminales privadas. Las sesiones de terminal individuales siguen siendo la herramienta adecuada para trabajo rápido, local y de bajo riesgo.
Qué aporta una Tarea gestionada a una sesión básica de Claude Code
Una sesión básica y una Tarea gestionada ejecutan el mismo Claude Code por debajo. La diferencia está en todo lo que rodea a la ejecución, y se divide en cuatro capacidades que una terminal no puede ofrecer.
Visibilidad compartida. Una Tarea mantiene los requisitos, el estado de la tarea, la discusión, los registros de ejecución y la revisión en un solo lugar, en lugar de repartirlos entre prompts y sesiones privadas. Un compañero de equipo puede abrir SH-214 y ver qué se pidió, qué se está ejecutando y qué ha vuelto.
Propiedad. Una Tarea separa la responsabilidad humana de la ejecución del Agente. Una persona es responsable del resultado; un Agente o un Crew es el asignado de la ejecución. Ambos quedan registrados, así que «quién es responsable de esto» siempre tiene respuesta.
Evidencia para la revisión. Cada ejecución genera un rastro de ejecución: cuándo comenzó, qué herramientas invocó, por qué se encoló y cómo terminó. El informe del Agente se conserva como un comentario vinculado a ese rastro. La revisión deja de ser «confiar en quien haya estado mirando la terminal» y pasa a ser «leer el registro».
Ejecuciones en paralelo sin colisiones. Cada Tarea recibe un directorio aislado, y el trabajo respaldado por un repositorio puede usar un worktree de git independiente por ejecución, de modo que varias Tareas pueden modificar la misma base de código a la vez. La mecánica del paralelismo tiene su propia guía: cómo ejecutar varios agentes de Claude Code en paralelo.
Un límite honesto antes del recorrido. No todas las sesiones de Claude Code necesitan esto. Usa un Agent Chat independiente, o una sesión de terminal normal, para explorar una pregunta, dar forma a un plan o hacer un cambio local rápido. Usa una Tarea cuando el trabajo necesite propiedad, estado, historial de ejecución o revisión.
Paso 1: Convierte la incidencia en una Tarea que un Agente pueda ejecutar
El arco comienza antes de que se ejecute ningún agente. Claude Code planifica un enfoque a partir de lo que le entregas, así que una Tarea vaga produce una ejecución segura de sí misma en la dirección equivocada.
Un título de Tarea útil nombra el resultado en lugar del tema. La descripción debe incluir lo que una persona nueva, o un Agente, necesitaría para proceder: por qué importa el trabajo; qué queda dentro y fuera del alcance; archivos, enlaces o comportamientos observados que sean relevantes; restricciones y decisiones ya tomadas; y cómo se revisará su finalización.
Ese último punto es el que los flujos de trabajo individuales se saltan. Escribir «hecho significa que la lógica de reintento tiene una prueba que falla con el comportamiento anterior» en la descripción le da al revisor una lista de verificación y al Agente un objetivo. Mantén el objetivo estable, el alcance y los criterios de aceptación en la descripción; usa los comentarios para la discusión.
La categoría de estado también importa aquí: una Tarea en Backlog está aparcada, y asignarle un Agente no inicia la ejecución. Eso es una característica. Puedes dar forma a un lote de Tareas, asignarlas todas y liberar cada una de forma deliberada sacándola de Backlog cuando esté lista.
Si tus incidencias ya viven en otro sitio, no tienes que rehacer tu proceso desde cero. Las integraciones de Sharkly incluyen Jira, Slack y GitHub, así que los rastreadores existentes se mantienen en su sitio mientras la ejecución pasa a ser asignable y rastreable. La disciplina de redactar trabajo que los agentes puedan ejecutar forma parte de un cambio más amplio que cubrimos en qué es la codificación agéntica.
Paso 2: Asígnala a un Agente cuyo Runtime sea Claude Code
En Sharkly, no asignas trabajo directamente a Claude Code. Lo asignas a un Agente, y el Runtime de ese Agente es Claude Code. La distinción merece la pena.
Un Agente es una configuración de trabajo guardada, no un prompt puntual: sus instrucciones, Runtime, Skills, repositorios, variables de entorno y ajustes de ejecución determinan cómo gestiona el trabajo. Una persona configura una vez un Agente «Backend Fixer», lo comparte con el Space, y todo el equipo asigna trabajo a la misma configuración probada en lugar de que cada desarrollador improvise prompts. Desglosamos el concepto por completo en Agentes en Sharkly, explicados.
El Runtime es la herramienta de agente concreta disponible en una Computadora. Cuando conectas una máquina, un pequeño servicio local detecta las herramientas de agente compatibles instaladas allí y reporta cada una como un Runtime; una instalación de Claude Code aparece como un Runtime disponible en el momento en que el servicio puede verla.
Tres hechos sobre esta configuración mantienen las expectativas bien alineadas:
- El Agente sigue el modelo predeterminado del Runtime. Sharkly no muestra ni promete un nombre de modelo, y no hay selector de modelo ni control de profundidad de razonamiento en el Agente. Para cambiar de modelo, cambia la configuración en el propio Claude Code.
- El uso del modelo es de tipo bring-your-own. Las ejecuciones consumen la suscripción de Claude o la clave API ya configurada en Claude Code en esa Computadora. La cuota del modelo depende de las herramientas de codificación con IA, los planes y las cuentas de API que conecte tu equipo.
- La asignación es explícita. Abres el control de Asignado de la Tarea y eliges el Agente, igual que asignarías un ticket a un colega. La persona responsable queda registrada por separado.
Para trabajo pequeño y bien definido, asigna la Tarea directamente a un Agente. Usa un Crew, un grupo reutilizable de Personas y Agentes coordinado por un Agente líder, solo cuando el líder necesite de verdad interpretar el objetivo y reunir los resultados de los demás miembros en una sola Tarea. La versión paso a paso de una primera asignación está en cómo asignar tu primera tarea a un agente de IA.
Paso 3: Ejecución en una Computadora, en un worktree aislado
Cuando la Tarea sale de Backlog y el Agente está listo, Sharkly encola la ejecución y la envía a la Computadora seleccionada: tu portátil, un servidor remoto o un contenedor. El servicio local de esa máquina recibe la ejecución, prepara el directorio de la tarea, inicia Claude Code y transmite el progreso de vuelta. Tu código, tus credenciales y tu instalación de Claude Code nunca salen del hardware que controlas.
Vale la pena enunciar claramente la separación de responsabilidades: el Agente define cómo debe gestionarse el trabajo; la Computadora proporciona el host y los recursos locales; el Runtime realiza la sesión de agente propiamente dicha; la Tarea sigue siendo el registro compartido.
Para el trabajo con repositorios, el modo de directorio de trabajo recomendado es Temporary: cada Tarea recibe un directorio aislado, y el servicio local puede preparar un worktree de git nuevo por ejecución a partir de los datos del repositorio en caché. Dos Tareas que tocan el mismo repositorio escriben en dos directorios distintos del disco, y por eso las ejecuciones en paralelo no se pisan entre sí. Ese primitivo se trata en cómo usar worktrees de git con agentes de codificación con IA. El modo Specified, un único directorio local configurado que las ejecuciones reutilizan, existe para las excepciones honestas: un repositorio muy grande, cachés locales costosas o herramientas ligadas a una única ruta.
Mientras Claude Code trabaja, la ejecución pasa por estados visibles: en cola, despachada, en ejecución y, después, completada, fallida o cancelada. El estado de ejecución es independiente del estado de la Tarea, y esa separación resulta útil: una Tarea puede permanecer In Progress mientras su Agente trabaja, espera una respuesta humana o informa de un error, y nadie tiene que consultar una terminal para saber cuál es el caso.
Paso 4: El progreso y los bloqueos vuelven a la Tarea
Todo lo que el equipo necesita ver vuelve a un único lugar. El informe del Agente se guarda como un comentario vinculado a su rastro de ejecución. Activity muestra los comentarios y los cambios de la tarea en una sola línea temporal. Executions contiene el historial de ejecuciones: origen del desencadenante, horas de inicio y fin, llamadas a herramientas y detalles del fallo.
Los bloqueos salen a la superficie en lugar de estancarse en silencio. Un Agente puede dejar una Tarea esperando una respuesta o una revisión humana, y el trabajo bloqueado alimenta Inbox, la cola personal que separa las Tareas que requieren tu atención de las actualizaciones de menor prioridad. La diferencia es estructural: una sesión estancada espera hasta que por casualidad revises la pestaña, mientras que una Tarea bloqueada avisa a la persona responsable de que está bloqueada.
Continuar el trabajo es un comentario, no una sesión nueva. Un comentario válido en una Tarea que sigue asignada al Agente inicia una ejecución de seguimiento con el contexto acumulado de la Tarea, y los comentarios rápidos se agrupan para que no generes ejecuciones pendientes duplicadas.
Paso 5: Revisión humana y aceptación
El arco termina donde debe: con una persona. Los Agentes investigan, ejecutan, prueban e informan. Las personas marcan la dirección, otorgan autoridad y aceptan el resultado.
La revisión en una Tarea gestionada consiste en leer evidencia, no en volver a ver una sesión. El revisor contrasta el informe del Agente con los criterios de aceptación escritos en el Paso 1: ¿se mantuvo dentro del alcance?, ¿ejecutó las comprobaciones relevantes?, ¿aportó evidencia para sus conclusiones?, ¿registró la incertidumbre en lugar de adivinar? El rastro de ejecución está ahí para cuando el resumen no basta.
La aceptación toma entonces uno de tres caminos honestos. Aceptar el trabajo y mover la Tarea a un estado completado. Solicitar cambios con un comentario concreto, lo que inicia una ejecución de seguimiento con todo el contexto. O decidir que la ejecución salió mal: cancelarla, leer el registro de ejecución y reintentar o asignar el trabajo a un Agente diferente.
Nada de esto sustituye tu revisión de git. Claude Code crea ramas, escribe commits y abre pull requests a través de tu alojamiento de git habitual, y tu revisión de fusión se queda donde está. La Tarea añade lo que la página del PR no puede ver: la solicitud original, la evidencia de la ejecución y la aceptación registrada.
Sesión individual vs Tarea gestionada
| Pregunta | Sesión individual de Claude Code | Tarea gestionada de Sharkly |
|---|---|---|
| ¿Quién pidió esto? | Tu memoria | Descripción de la Tarea, con alcance y criterios de aceptación |
| ¿Quién está trabajando en ello? | Quien sea dueño de la terminal | Persona responsable más un Agente como asignado de la ejecución |
| ¿Qué está pasando ahora mismo? | Mirar la terminal | Estado de ejecución en la Tarea, los tableros e Inbox |
| ¿Qué hizo la ejecución? | El historial de desplazamiento, hasta que se cierra la pestaña | Rastro de ejecución y comentarios persistidos |
| ¿Pueden dos ejecuciones compartir un repositorio? | Solo si configuras los worktrees a mano | Un worktree aislado por Tarea de forma predeterminada |
| ¿Quién aprobó el resultado? | Nadie lo registra | Revisión y aceptación en la Tarea |
| ¿Puede el equipo reutilizar la configuración? | Los prompts viven con una sola persona | Agentes y Skills compartidos en el Space |
La columna izquierda no es la columna equivocada. Es la herramienta adecuada para la exploración y las correcciones rápidas. La columna derecha merece la pena cuando el trabajo necesita ser visible, revisable y paralelo.
De una Tarea a un proyecto gestionado
Todo lo anterior escala de una Tarea a un plan sin cambiar de forma. Las Tareas se agrupan en Projects cuando varias sirven a un mismo resultado, y en Sprints cuando la pregunta es qué se entrega en este periodo de tiempo. Las Views guardan las preguntas que un equipo hace repetidamente, como las Tareas que esperan revisión.
Esa es toda la tesis de este flujo de trabajo. El apalancamiento del equipo no viene de abrir más chats de IA; viene de compartir roles, reglas, contexto y flujos de trabajo. Dónde encaja esta disciplina en el panorama general es el tema de nuestra guía principal, qué es la gestión de proyectos con agentes de IA.
Empieza más pequeño de lo que parezca necesario. Conecta una Computadora, confirma que Claude Code aparece como un Runtime disponible, crea un Agente con un rol acotado y asígnale una Tarea de bajo riesgo con criterios de aceptación reales. Revisa el resultado como revisarías el primer pull request de un compañero nuevo. La documentación de Sharkly cubre cada concepto con más profundidad.
Preguntas frecuentes
¿Sharkly sustituye a Claude Code?
No. Sharkly no es un sustituto de Claude Code, Codex u otras herramientas de ejecución. Claude Code realiza la ejecución: lee la base de código, edita archivos, ejecuta comandos y trabaja con git. Sharkly añade la capa de equipo a su alrededor, gestionando la asignación, el contexto de las tareas, el progreso, los bloqueos, los resultados y la revisión humana.
¿Necesito una suscripción de modelo aparte para ejecutar Claude Code a través de Sharkly?
No. El uso del modelo sigue funcionando a través de las suscripciones o claves API ya configuradas en Claude Code en tus Computadoras conectadas. La cuota del modelo depende de las herramientas de codificación con IA, los planes y las cuentas de API que conecte tu equipo.
¿Puedo seguir usando Claude Code directamente en la terminal?
Sí, y deberías hacerlo. Una sesión directa o un Agent Chat independiente es la herramienta adecuada para explorar una pregunta, dar forma a un plan o hacer un cambio local rápido. Pasa a una Tarea cuando el trabajo necesite propiedad, estado, historial de ejecución o revisión.
¿Qué ocurre cuando falla una ejecución?
La ejecución se marca como fallida en la Tarea, y el registro de ejecución anota el título junto con los detalles técnicos originales del servicio del modelo. La guía de solución de problemas de Sharkly asigna los casos comunes, como límites de velocidad, cuota agotada y errores de autenticación, a los siguientes pasos, y enlaza la propia referencia de errores de Claude Code. Reintenta después de corregir la causa, o asigna la Tarea a otro Agente.
¿Pueden ejecutarse varias Tareas de Claude Code en el mismo repositorio a la vez?
Sí. En el modo de directorio de trabajo Temporary, cada Tarea se ejecuta en su propio directorio aislado, y las ejecuciones respaldadas por un repositorio pueden recibir cada una un worktree de git nuevo, de modo que las Tareas concurrentes no escriben en un checkout compartido. Los límites de concurrencia del Agente y la Computadora acotan cuántas se ejecutan a la vez.
