Conceptos fundamentales

Dropstone es una herramienta de codificación agéntica que se ejecuta en tu terminal. Puede leer código, ejecutar comandos, planificar cambios, editar archivos y verificar el resultado. Esta página cubre las ideas fundamentales que solo necesitas aprender una vez: el bucle en el que opera el agente, a qué puede acceder, cómo funcionan las sesiones, cómo se gestiona el contexto y cómo los permisos te mantienen en control.

El bucle agéntico

Cuando le das una tarea a Dropstone, trabaja en tres fases: recopilar contexto, tomar acción y verificar resultados. Las fases se combinan entre sí. Dropstone utiliza herramientas en todo momento, ya sea leyendo archivos para entender tu código, editando para hacer cambios o ejecutando pruebas para comprobar su trabajo.

El bucle se adapta a lo que pides. Una pregunta sobre tu base de código podría solo necesitar recopilar contexto. Una corrección de errores recorre las tres fases. Una refactorización grande podría implicar una verificación intensiva. Dropstone decide qué requiere cada paso basándose en lo que aprendió del paso anterior, encadenando docenas de acciones y corrigiendo el rumbo en el camino.

Tú también eres parte de este bucle. Puedes interrumpir en cualquier momento para redirigir, añadir contexto o pedir un enfoque diferente. Dropstone trabaja de forma autónoma pero sigue siendo receptivo a tus aportaciones.

El bucle agéntico está impulsado por dos componentes: el modelo que razona y las herramientas que actúan.

Modelos

Dropstone utiliza modelos de codificación diseñados específicamente. Hay tres niveles, cada uno ajustado para un tipo diferente de trabajo:

Cambia de nivel con /effort low, /effort medium, /effort high o /effort xhigh durante una sesión, o usa Ctrl+T para alternar entre ellos. Cuando esta guía dice "Dropstone decide" o "Dropstone elige", es el modelo el que está razonando.

Herramientas

Las herramientas son lo que hace agéntico a Dropstone. Sin herramientas, el modelo solo puede producir texto. Con ellas, puede actuar: leer tu código, editar archivos, ejecutar comandos, buscar en la web e interactuar con servicios externos. Cada resultado de herramienta se retroalimenta en el bucle, informando la siguiente decisión.

Las herramientas integradas se dividen en cinco categorías:

Dropstone elige qué herramientas usar según tu prompt y lo que aprende en el camino. Cuando dices "arregla las pruebas que fallan", podría:

1. Ejecutar la suite de pruebas para ver qué está fallando
2. Leer la salida de errores
3. Buscar los archivos fuente relevantes
4. Leer esos archivos para entender el código
5. Editarlos para corregir el problema
6. Ejecutar las pruebas de nuevo para verificar

Cada uso de herramienta devuelve información que informa el siguiente paso. Eso es el bucle agéntico en la práctica.

Las herramientas integradas son la base. Puedes ampliar lo que Dropstone conoce con skills, conectarte a servicios externos con servidores MCP y delegar trabajo a subagentes. Para la lista completa de herramientas integradas, consulta Herramientas integradas.

A qué puede acceder Dropstone

Cuando ejecutas dropstone en un directorio, el agente obtiene acceso a:

• Tu proyecto. Archivos en tu directorio de trabajo y subdirectorios, además de otros archivos con tu permiso.
• Tu terminal. Cualquier comando que pudieras ejecutar tú mismo: herramientas de compilación, git, gestores de paquetes, utilidades del sistema, scripts. Si puedes hacerlo desde la línea de comandos, Dropstone también puede.
• Tu estado de git. Rama actual, cambios sin confirmar, archivos en el área de preparación e historial de commits recientes.
• Tu AGENTS.md. Un archivo markdown en la raíz del repositorio donde escribes convenciones específicas del proyecto, comandos de compilación, advertencias y cualquier cosa que Dropstone deba saber en cada sesión.
• Extensiones que configures. Servidores MCP para servicios externos, skills para flujos de trabajo y subagentes para trabajo delegado.

Debido a que Dropstone ve todo tu proyecto, puede trabajar en todo él. Cuando le pides "arregla el error de autenticación", busca archivos relevantes, lee varios para entender el contexto, realiza ediciones coordinadas entre ellos, ejecuta pruebas para verificar y hace commit si se lo pides. Esto es diferente de los asistentes de código en línea que solo ven el archivo actual.

Sesiones

Cada sesión interactiva se guarda localmente. Cada mensaje, uso de herramienta y resultado se escribe en un registro de sesión, lo que hace posible deshacer, reanudar y bifurcar trabajo pasado.

Las sesiones son independientes. Una sesión nueva comienza con una ventana de contexto fresca, sin memoria de conversaciones anteriores. El conocimiento persistente pertenece en AGENTS.md, no en el historial de conversación.

Reanudar o bifurcar sesiones

Reanudar con dropstone --continue (o dropstone -c) reabre la sesión más reciente en el directorio actual y añade mensajes nuevos a ella. Reanudar una sesión específica por id usa dropstone --session <id>.

# Continuar la última sesión en este directorio
dropstone -c

# Reanudar una sesión específica
dropstone --session 7f3a82b1

# Bifurcar una sesión existente en una conversación nueva
dropstone --session 7f3a82b1 --fork

Bifurcar copia el historial en un id de sesión nuevo, dejando el original intacto. Útil cuando quieres explorar una dirección alternativa sin perder el hilo original.

La ventana de contexto

La ventana de contexto contiene tu historial de conversación, contenidos de archivos, salidas de comandos, AGENTS.md, skills cargadas e instrucciones del sistema. A medida que trabajas, la ventana se llena. Dropstone compacta contenido antiguo automáticamente, pero las instrucciones del inicio de la conversación pueden perderse.

Algunas reglas generales:

• Pon reglas persistentes en AGENTS.md, no en mensajes de chat. La versión del mensaje de chat se compacta; la versión de AGENTS.md se recarga en cada sesión.
• Skills se cargan bajo demanda. Dropstone ve las descripciones de las skills al inicio de la sesión, pero solo carga el contenido completo cuando se invoca una skill.
• Subagentes obtienen su propio contexto nuevo. Su trabajo no infla la conversación principal; cuando terminan, devuelven un resumen.

Seguridad: checkpoints y permisos

Dropstone tiene dos mecanismos de seguridad. Los checkpoints te permiten deshacer cambios que el agente ha realizado. Los permisos controlan lo que el agente puede hacer sin preguntar.

Deshacer con checkpoints

Cada edición de archivo es reversible. Antes de que Dropstone edite un archivo, toma una instantánea del contenido actual. Si algo sale mal, usa /undo para retroceder un ciclo de edición a la vez, o /redo para reproducir un paso deshecho.

/undo            # revierte el último ciclo de edición
/redo            # reproduce el paso deshecho más reciente

Los checkpoints son locales a tu sesión, separados de git. Solo cubren cambios de archivos. Las acciones que tocan sistemas remotos (bases de datos, servicios desplegados, APIs de red) no pueden tener checkpoint, por eso Dropstone pregunta antes de ejecutar comandos con efectos secundarios externos.

Controla lo que Dropstone puede hacer

Dropstone pide aprobación la primera vez que quiere realizar una acción sensible: editar un archivo, ejecutar un comando de shell, hacer una llamada a la red. Aprueba una vez, y la misma operación se ejecuta sin volver a preguntar durante el resto de la sesión.

Usa Tab para alternar entre dos modos de operación durante una sesión:

• Modo Build. El predeterminado. Dropstone puede editar archivos y ejecutar comandos (sujeto a aprobación). Úsalo cuando quieras entregar el cambio.
• Modo Plan. Solo lectura. Dropstone puede investigar la base de código, recopilar contexto y producir un plan, pero no puede editar ni ejecutar nada. Úsalo cuando quieras estudiar el sistema antes de cambiarlo.

Para preaprobar comandos y omitir el prompt por completo, enuméralos en la configuración de permisos de tu proyecto. Por ejemplo:

{
  "permissions": {
    "allow": ["git status", "git diff", "npm test", "npm run lint"]
  }
}

Para políticas a nivel de organización, patrones más detallados y cómo funciona la resolución de alcance, consulta la guía de Permisos.

Trabajar eficazmente con Dropstone

Algunos patrones que tienden a producir mejores resultados.

Es una conversación

No necesitas un primer prompt perfecto. Empieza con lo que quieres, observa lo que hace el agente y luego corrígelo:

arregla el error de inicio de sesión

no, el problema está en el manejo de sesiones, no en la validación del formulario

No estás empezando de cero. Estás iterando. Cada turno refina la comprensión del agente.

Interrumpe y redirige

Puedes redirigir a Dropstone en cualquier momento:

• Presiona Esc para detenerte de inmediato. La llamada de herramienta actual se cancela y Dropstone espera tu siguiente instrucción.
• Escribe una corrección y presiona Enter sin esperar. Dropstone la lee tan pronto como la acción actual se completa y se ajusta antes de decidir su siguiente paso.

Sé específico desde el principio

Cuanto más preciso sea tu prompt inicial, menos correcciones necesitarás. Haz referencia a archivos, menciona restricciones, señala patrones de ejemplo:

el flujo de pago está roto para usuarios con tarjetas vencidas.
busca el problema en src/payments/, especialmente en la renovación de tokens.
escribe una prueba que falle primero, luego arréglalo.

Los prompts vagos funcionan, pero pasarás más tiempo redirigiendo. Los prompts específicos como el anterior a menudo tienen éxito en el primer intento.

Dale a Dropstone algo contra lo que verificar

El agente rinde mejor cuando puede comprobar su propio trabajo. Incluye casos de prueba, salidas esperadas o criterios de aceptación:

implementa validateEmail. casos de prueba:
  'user@example.com' -> true
  'invalid'           -> false
  'user@.com'         -> false
ejecuta las pruebas después.

Explora antes de implementar

Para problemas complejos, separa la investigación de la codificación. Cambia al modo plan (Tab), haz que Dropstone estudie el código relevante, refina el plan mediante conversación y luego vuelve al modo build para ejecutar:

lee src/auth/ y explica cómo manejamos las sesiones hoy.
luego propón un plan para añadir soporte OAuth.

Revisa el plan, objeta cualquier cosa con la que no estés de acuerdo y luego deja que Dropstone lo implemente. Este enfoque de dos fases produce resultados consistentemente mejores que ir directamente al código.

Delega, no dictes

Trata a Dropstone como un colega competente. Da contexto y dirección, y luego confía en que el agente resolverá los detalles:

el flujo de pago está roto para usuarios con tarjetas vencidas.
el código relevante está en src/payments/.
investiga y arréglalo.

No necesitas especificar qué archivos leer, qué comandos ejecutar ni en qué orden hacer las cosas. Dropstone lo resuelve a partir del prompt.

Qué sigue