Concepts fondamentaux

Dropstone est un outil de codage agentique qui s'exécute dans votre terminal. Il peut lire du code, exécuter des commandes, planifier des modifications, éditer des fichiers et vérifier le résultat. Cette page couvre les idées fondamentales que vous n'avez besoin d'apprendre qu'une seule fois : la boucle dans laquelle l'agent évolue, ce à quoi il peut accéder, comment fonctionnent les sessions, comment le contexte est géré et comment les permissions vous gardent le contrôle.

La boucle agentique

Lorsque vous confiez une tâche à Dropstone, il travaille en trois phases : recueillir le contexte, agir et vérifier les résultats. Les phases se fondent les unes dans les autres. Dropstone utilise des outils tout au long du processus, qu'il s'agisse de lire des fichiers pour comprendre votre code, d'éditer pour apporter des modifications ou d'exécuter des tests pour vérifier son travail.

La boucle s'adapte à ce que vous demandez. Une question sur votre codebase peut ne nécessiter que la collecte de contexte. Une correction de bug passe par les trois phases. Une refonte importante peut impliquer une vérification approfondie. Dropstone décide de ce que chaque étape nécessite en fonction de ce qu'il a appris de l'étape précédente, enchaînant des dizaines d'actions et corrigeant sa trajectoire en cours de route.

Vous faites également partie de cette boucle. Vous pouvez interrompre à tout moment pour rediriger, ajouter du contexte ou demander une approche différente. Dropstone travaille de manière autonome mais reste réactif à vos entrées.

La boucle agentique est alimentée par deux composants : le modèle qui raisonne et les outils qui agissent.

Modèles

Dropstone utilise des modèles de codage spécialement conçus. Il existe trois niveaux, chacun adapté à un type de travail différent :

Changez de niveau avec /effort low, /effort medium, /effort high ou /effort xhigh pendant une session, ou Ctrl+T pour les parcourir. Lorsque ce guide dit « Dropstone décide » ou « Dropstone choisit », c'est le modèle qui effectue le raisonnement.

Outils

Les outils sont ce qui rend Dropstone agentique. Sans outils, le modèle ne peut produire que du texte. Avec des outils, il peut agir : lire votre code, éditer des fichiers, exécuter des commandes, rechercher sur le web et interagir avec des services externes. Chaque résultat d'outil est réinjecté dans la boucle, informant la décision suivante.

Les outils intégrés se répartissent en cinq catégories :

Dropstone choisit les outils à utiliser en fonction de votre invite et de ce qu'il apprend en cours de route. Lorsque vous dites « corrige les tests qui échouent », il pourrait :

1. Exécuter la suite de tests pour voir ce qui échoue
2. Lire la sortie d'erreur
3. Rechercher les fichiers source pertinents
4. Lire ces fichiers pour comprendre le code
5. Les éditer pour corriger le problème
6. Relancer les tests pour vérifier

Chaque utilisation d'outil renvoie des informations qui éclairent l'étape suivante. C'est la boucle agentique en pratique.

Les outils intégrés constituent la base. Vous pouvez étendre ce que Dropstone connaît avec des compétences, vous connecter à des services externes avec des serveurs MCP et déléguer du travail à des sous-agents. Pour la liste complète des outils intégrés, consultez Outils intégrés.

Ce à quoi Dropstone peut accéder

Lorsque vous exécutez dropstone dans un répertoire, l'agent accède à :

• Votre projet. Les fichiers de votre répertoire de travail et de ses sous-répertoires, ainsi que d'autres fichiers avec votre permission.
• Votre terminal. Toute commande que vous pourriez exécuter vous-même : outils de build, git, gestionnaires de paquets, utilitaires système, scripts. Si vous pouvez le faire depuis la ligne de commande, Dropstone le peut aussi.
• Votre état git. Branche actuelle, modifications non validées, fichiers indexés et historique des commits récents.
• Votre AGENTS.md. Un fichier markdown à la racine du dépôt où vous écrivez les conventions spécifiques au projet, les commandes de build, les pièges et tout ce que Dropstone doit savoir à chaque session.
• Les extensions que vous configurez. Serveurs MCP pour les services externes, compétences pour les flux de travail et sous-agents pour le travail délégué.

Parce que Dropstone voit l'ensemble de votre projet, il peut travailler à travers lui. Lorsque vous lui demandez de « corriger le bug d'authentification », il recherche les fichiers pertinents, en lit plusieurs pour comprendre le contexte, effectue des modifications coordonnées à travers eux, exécute des tests pour vérifier et valide si vous le demandez. Cela diffère des assistants de code en ligne qui ne voient que le fichier actuel.

Sessions

Chaque session interactive est enregistrée localement. Chaque message, utilisation d'outil et résultat est écrit dans un enregistrement de session, ce qui permet d'annuler, de reprendre et de forker des travaux passés.

Les sessions sont indépendantes. Une nouvelle session démarre avec une fenêtre de contexte vierge, sans mémoire des conversations précédentes. Les connaissances persistantes appartiennent à AGENTS.md, pas à l'historique de conversation.

Reprendre ou forker des sessions

Reprendre avec dropstone --continue (ou dropstone -c) rouvre la session la plus récente dans le répertoire actuel et y ajoute de nouveaux messages. Reprendre une session spécifique par identifiant utilise dropstone --session <id>.

# Continuer la dernière session dans ce répertoire
dropstone -c

# Reprendre une session spécifique
dropstone --session 7f3a82b1

# Forker une session existante dans une nouvelle conversation
dropstone --session 7f3a82b1 --fork

Le fork copie l'historique dans un nouvel identifiant de session, laissant l'original intact. Utile lorsque vous souhaitez explorer une direction alternative sans perdre le fil original.

La fenêtre de contexte

La fenêtre de contexte contient votre historique de conversation, le contenu des fichiers, les sorties de commandes, AGENTS.md, les compétences chargées et les instructions système. Au fur et à mesure que vous travaillez, la fenêtre se remplit. Dropstone compacte automatiquement le contenu plus ancien, mais les instructions du début de la conversation peuvent être perdues.

Quelques règles de base :

• Placez les règles persistantes dans AGENTS.md, pas dans les messages de chat. La version du message de chat est compactée ; la version AGENTS.md est rechargée à chaque session.
• Les compétences se chargent à la demande. Dropstone voit les descriptions des compétences au début de la session mais ne charge le contenu complet que lorsqu'une compétence est invoquée.
• Les sous-agents disposent de leur propre contexte vierge. Leur travail ne gonfle pas la conversation principale ; une fois terminé, ils renvoient un résumé.

Sécurité : points de restauration et permissions

Dropstone dispose de deux mécanismes de sécurité. Les points de restauration vous permettent d'annuler les modifications apportées par l'agent. Les permissions contrôlent ce que l'agent peut faire sans demander.

Annuler avec des points de restauration

Chaque modification de fichier est réversible. Avant que Dropstone n'édite un fichier, il prend un instantané du contenu actuel. Si quelque chose tourne mal, utilisez /undo pour reculer d'un cycle d'édition à la fois, ou /redo pour rejouer une étape annulée.

/undo            # annuler le dernier cycle d'édition
/redo            # rejouer l'étape annulée la plus récente

Les points de restauration sont locaux à votre session, séparés de git. Ils ne couvrent que les modifications de fichiers. Les actions qui touchent des systèmes distants (bases de données, services déployés, API réseau) ne peuvent pas être restaurées, c'est pourquoi Dropstone demande avant d'exécuter des commandes ayant des effets externes.

Contrôler ce que Dropstone peut faire

Dropstone demande une approbation la première fois qu'il souhaite effectuer une action sensible : éditer un fichier, exécuter une commande shell, appeler le réseau. Approuvez une fois, et la même opération s'exécutera sans redemander pour le reste de la session.

Utilisez Tab pour basculer entre deux modes de fonctionnement pendant une session :

• Mode Build. Le mode par défaut. Dropstone peut éditer des fichiers et exécuter des commandes (sous réserve d'approbation). Utilisez-le lorsque vous souhaitez livrer la modification.
• Mode Plan. Lecture seule. Dropstone peut étudier le codebase, recueillir du contexte et produire un plan, mais ne peut ni éditer ni exécuter quoi que ce soit. Utilisez-le lorsque vous souhaitez étudier le système avant de le modifier.

Pour pré-approuver des commandes et ignorer complètement l'invite, listez-les dans la configuration des permissions de votre projet. Par exemple :

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

Pour les politiques à l'échelle de l'organisation, les motifs plus fins et le fonctionnement de la résolution de portée, consultez le guide des permissions.

Travailler efficacement avec Dropstone

Quelques schémas qui tendent à produire de meilleurs résultats.

C'est une conversation

Vous n'avez pas besoin d'une première invite parfaite. Commencez par ce que vous voulez, observez ce que fait l'agent, puis corrigez-le :

corrige le bug de connexion

non, le problème vient de la gestion des sessions, pas de la validation du formulaire

Vous ne repartez pas de zéro. Vous itérez. Chaque tour affine la compréhension de l'agent.

Interrompre et orienter

Vous pouvez rediriger Dropstone à tout moment :

• Appuyez sur Esc pour arrêter immédiatement. L'appel d'outil en cours est annulé et Dropstone attend votre prochaine instruction.
• Tapez une correction et appuyez sur Entrée sans attendre. Dropstone la lit dès que l'action en cours se termine et s'ajuste avant de décider de sa prochaine étape.

Soyez précis dès le départ

Plus votre invite initiale est précise, moins vous aurez besoin de corrections. Référencez les fichiers, mentionnez les contraintes, pointez vers des modèles d'exemple :

le flux de paiement est cassé pour les utilisateurs avec des cartes expirées.
cherche le problème dans src/payments/, surtout le renouvellement de jeton.
écris d'abord un test qui échoue, puis corrige-le.

Les invites vagues fonctionnent, mais vous passerez plus de temps à orienter. Les invites précises comme celle ci-dessus réussissent souvent du premier coup.

Donnez à Dropstone quelque chose à vérifier

L'agent donne de meilleurs résultats lorsqu'il peut vérifier son propre travail. Incluez des cas de test, des sorties attendues ou des critères d'acceptation :

implémente validateEmail. cas de test :
  'user@example.com' -> true
  'invalid'           -> false
  'user@.com'         -> false
exécute les tests après.

Explorer avant d'implémenter

Pour les problèmes complexes, séparez la recherche du codage. Passez en mode plan (Tab), faites étudier le code pertinent par Dropstone, affinez le plan par la conversation, puis repassez en mode build pour exécuter :

lis src/auth/ et explique comment nous gérons les sessions aujourd'hui.
propose ensuite un plan pour ajouter le support OAuth.

Examinez le plan, contestez tout ce avec quoi vous n'êtes pas d'accord, puis laissez Dropstone implémenter. Cette approche en deux phases produit des résultats nettement meilleurs que d'aller directement au code.

Déléguer, ne pas dicter

Traitez Dropstone comme un collègue compétent. Donnez du contexte et une direction, puis faites confiance à l'agent pour trouver les détails :

le flux de paiement est cassé pour les utilisateurs avec des cartes expirées.
le code pertinent est dans src/payments/.
enquête et corrige.

Vous n'avez pas besoin de spécifier quels fichiers lire, quelles commandes exécuter ou dans quel ordre procéder. Dropstone le détermine à partir de l'invite.

Et ensuite