Conceitos principais

O Dropstone é uma ferramenta de codificação agêntica que roda no seu terminal. Ele pode ler código, executar comandos, planejar mudanças, editar arquivos e verificar o resultado. Esta página cobre as ideias principais que você só precisa aprender uma vez: o loop em que o agente opera, o que ele pode acessar, como as sessões funcionam, como o contexto é gerenciado e como as permissões mantêm você no controle.

O loop agêntico

Quando você dá uma tarefa ao Dropstone, ele trabalha em três fases: coletar contexto, agir e verificar resultados. As fases se misturam. O Dropstone usa ferramentas o tempo todo, seja lendo arquivos para entender seu código, editando para fazer mudanças ou rodando testes para verificar o trabalho.

O loop se adapta ao que você pede. Uma pergunta sobre seu codebase pode precisar apenas de coleta de contexto. Uma correção de bug percorre as três fases. Uma refatoração grande pode envolver verificação pesada. O Dropstone decide o que cada etapa exige com base no que aprendeu na etapa anterior, encadeando dezenas de ações e corrigindo o rumo ao longo do caminho.

Você também faz parte desse loop. Você pode interromper a qualquer momento para redirecionar, adicionar contexto ou pedir uma abordagem diferente. O Dropstone trabalha de forma autônoma, mas permanece responsivo à sua entrada.

O loop agêntico é alimentado por dois componentes: o modelo, que raciocina, e as ferramentas, que agem.

Modelos

O Dropstone usa modelos de codificação feitos sob medida. Há três níveis, cada um ajustado para um tipo diferente de trabalho:

Alterne os níveis com /effort low, /effort medium, /effort high ou /effort xhigh durante uma sessão, ou Ctrl+T para percorrê-los. Quando este guia diz "o Dropstone decide" ou "o Dropstone escolhe", é o modelo fazendo o raciocínio.

Ferramentas

As ferramentas são o que torna o Dropstone agêntico. Sem ferramentas, o modelo só pode produzir texto. Com ferramentas, ele pode agir: ler seu código, editar arquivos, executar comandos, pesquisar na web e interagir com serviços externos. Cada resultado de ferramenta alimenta o loop, informando a próxima decisão.

As ferramentas integradas se enquadram em cinco categorias:

O Dropstone escolhe quais ferramentas usar com base no seu prompt e no que aprende ao longo do caminho. Quando você diz "corrija os testes que estão falhando", ele pode:

1. Rodar a suíte de testes para ver o que está falhando
2. Ler a saída de erro
3. Buscar os arquivos-fonte relevantes
4. Ler esses arquivos para entender o código
5. Editá-los para corrigir o problema
6. Rodar os testes novamente para verificar

Cada uso de ferramenta retorna informações que informam o próximo passo. Esse é o loop agêntico na prática.

As ferramentas integradas são a base. Você pode estender o que o Dropstone conhece com skills, conectar-se a serviços externos com servidores MCP e delegar trabalho a subagentes. Para a lista completa de ferramentas integradas, veja Ferramentas Integradas.

O que o Dropstone pode acessar

Quando você executa dropstone em um diretório, o agente ganha acesso a:

• Seu projeto. Arquivos no seu diretório de trabalho e subdiretórios, além de outros arquivos com sua permissão.
• Seu terminal. Qualquer comando que você mesmo poderia executar: ferramentas de build, git, gerenciadores de pacotes, utilitários do sistema, scripts. Se você pode fazer pela linha de comando, o Dropstone também pode.
• Seu estado do git. Branch atual, mudanças não commitadas, arquivos em staging e histórico recente de commits.
• Seu AGENTS.md. Um arquivo markdown na raiz do repositório onde você escreve convenções específicas do projeto, comandos de build, pegadinhas e qualquer coisa que o Dropstone deva saber em toda sessão.
• Extensões que você configura. Servidores MCP para serviços externos, skills para fluxos de trabalho e subagentes para trabalho delegado.

Como o Dropstone vê todo o seu projeto, ele pode trabalhar nele de ponta a ponta. Quando você pede para "corrigir o bug de autenticação", ele busca arquivos relevantes, lê vários para entender o contexto, faz edições coordenadas entre eles, roda testes para verificar e faz commit se você pedir. Isso é diferente de assistentes de código inline que só veem o arquivo atual.

Sessões

Toda sessão interativa é salva localmente. Cada mensagem, uso de ferramenta e resultado é gravado em um registro de sessão, o que torna possível desfazer, retomar e bifurcar trabalhos passados.

As sessões são independentes. Uma nova sessão começa com uma janela de contexto limpa, sem memória de conversas anteriores. Conhecimento persistente pertence ao AGENTS.md, não ao histórico da conversa.

Retomar ou bifurcar sessões

Retomar com dropstone --continue (ou dropstone -c) reabre a sessão mais recente no diretório atual e anexa novas mensagens a ela. Retomar uma sessão específica por id usa dropstone --session <id>.

# Continuar a última sessão neste diretório
dropstone -c

# Retomar uma sessão específica
dropstone --session 7f3a82b1

# Bifurcar uma sessão existente em uma nova conversa
dropstone --session 7f3a82b1 --fork

Bifurcar copia o histórico para um novo id de sessão, deixando o original intacto. Útil quando você quer explorar uma direção alternativa sem perder o fio original.

A janela de contexto

A janela de contexto contém seu histórico de conversa, conteúdos de arquivos, saídas de comandos, AGENTS.md, skills carregadas e instruções do sistema. Conforme você trabalha, a janela enche. O Dropstone compacta conteúdo mais antigo automaticamente, mas instruções do início da conversa podem ser perdidas.

Algumas regras práticas:

• Coloque regras persistentes no AGENTS.md, não em mensagens de chat. A versão em mensagem de chat é compactada; a versão no AGENTS.md é recarregada a cada sessão.
• Skills carregam sob demanda. O Dropstone vê as descrições das skills no início da sessão, mas só carrega o conteúdo completo quando uma skill é invocada.
• Subagentes recebem contexto próprio e limpo. O trabalho deles não incha a conversa principal; quando terminam, retornam um resumo.

Segurança: checkpoints e permissões

O Dropstone tem dois mecanismos de segurança. Checkpoints permitem desfazer mudanças que o agente fez. Permissões controlam o que o agente pode fazer sem pedir.

Desfazer com checkpoints

Toda edição de arquivo é reversível. Antes de o Dropstone editar um arquivo, ele tira um snapshot do conteúdo atual. Se algo der errado, use /undo para voltar um ciclo de edição por vez, ou /redo para repetir um passo desfeito.

/undo            # reverter o último ciclo de edição
/redo            # repetir o passo desfeito mais recente

Os checkpoints são locais à sua sessão, separados do git. Eles cobrem apenas mudanças em arquivos. Ações que tocam sistemas remotos (bancos de dados, serviços implantados, APIs de rede) não podem ser checkpointadas, por isso o Dropstone pede antes de executar comandos com efeitos colaterais externos.

Controlar o que o Dropstone pode fazer

O Dropstone pede aprovação na primeira vez que quer executar uma ação sensível: editar um arquivo, rodar um comando de shell, chamar a rede. Aprove uma vez, e a mesma operação roda sem re-pedir pelo resto da sessão.

Use Tab para alternar entre dois modos de operação durante uma sessão:

• Modo build. O padrão. O Dropstone pode editar arquivos e executar comandos (sujeito a aprovação). Use isso quando quiser entregar a mudança.
• Modo plano. Somente leitura. O Dropstone pode investigar o codebase, coletar contexto e produzir um plano, mas não pode editar nem executar nada. Use isso quando quiser estudar o sistema antes de mudá-lo.

Para pré-aprovar comandos e pular o prompt completamente, liste-os na configuração de permissões do seu projeto. Por exemplo:

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

Para políticas em toda a organização, padrões mais granulares e como a resolução de escopo funciona, veja o Guia de Permissões.

Trabalhando efetivamente com o Dropstone

Alguns padrões que tendem a produzir melhores resultados.

É uma conversa

Você não precisa de um primeiro prompt perfeito. Comece com o que você quer, veja o que o agente faz e então corrija:

corrija o bug de login

não, o problema está no gerenciamento de sessão, não na validação do formulário

Você não está recomeçando. Você está iterando. Cada turno refina o entendimento do agente.

Interrompa e direcione

Você pode redirecionar o Dropstone a qualquer momento:

• Pressione Esc para parar imediatamente. A chamada de ferramenta atual é cancelada e o Dropstone aguarda sua próxima instrução.
• Digite uma correção e pressione Enter sem esperar. O Dropstone a lê assim que a ação atual termina e ajusta antes de decidir o próximo passo.

Seja específico desde o início

Quanto mais preciso for seu prompt inicial, menos correções você precisará. Referencie arquivos, mencione restrições, aponte padrões de exemplo:

o fluxo de checkout está quebrado para usuários com cartões expirados.
procure em src/payments/ pelo problema, especialmente no refresh de token.
escreva um teste que falha primeiro, depois corrija.

Prompts vagos funcionam, mas você gastará mais tempo direcionando. Prompts específicos como o acima geralmente têm sucesso na primeira tentativa.

Dê ao Dropstone algo para verificar

O agente tem melhor desempenho quando pode checar o próprio trabalho. Inclua casos de teste, saídas esperadas ou critérios de aceite:

implemente validateEmail. casos de teste:
  'user@example.com' -> true
  'invalid'           -> false
  'user@.com'         -> false
rode os testes depois.

Explore antes de implementar

Para problemas complexos, separe pesquisa de codificação. Alterne para o modo plano (Tab), faça o Dropstone estudar o código relevante, refine o plano por conversa e então volte ao modo build para executar:

leia src/auth/ e explique como lidamos com sessões hoje.
depois proponha um plano para adicionar suporte a OAuth.

Revise o plano, questione qualquer coisa com que discorde e então deixe o Dropstone implementar. Essa abordagem em duas fases produz resultados consistentemente melhores do que ir direto ao código.

Delegue, não dite

Trate o Dropstone como um colega capaz. Dê contexto e direção, depois confie que o agente descobrirá os detalhes:

o fluxo de checkout está quebrado para usuários com cartões expirados.
o código relevante está em src/payments/.
investigue e corrija.

Você não precisa especificar quais arquivos ler, quais comandos rodar ou em que ordem fazer as coisas. O Dropstone resolve isso a partir do prompt.

O que vem a seguir