L'outil d'édition de texte

Claude connaît un outil d’édition de texte dont Anthropic fournit le schéma : vous n’avez pas à le décrire. Il lui permet de lire des fichiers et des dossiers, de remplacer un passage, de créer un fichier ou d’insérer des lignes, comme un développeur dans son éditeur. Le schéma vient d’Anthropic, mais l’exécution reste à votre charge.

Un outil à schéma Anthropic

C’est la deuxième famille d’outils de la leçon 31 : Anthropic publie le schéma, votre application exécute. L’intérêt est la fiabilité. D’après la documentation, Claude a été entraîné sur un grand nombre de trajectoires réussies avec ces signatures exactes : il appelle ces outils plus sûrement, et se rattrape mieux après une erreur, qu’avec un outil maison équivalent.

Déclarer l’outil

Une seule entrée dans tools, sans description ni schéma :

text_editor_tool = {
    "type": "text_editor_20250728",
    "name": "str_replace_based_edit_tool",
}

La version text_editor_20250728 vaut pour les modèles Claude 4 et suivants, c’est-à-dire pour tous les modèles actuels. La version antérieure, text_editor_20250124, visait les modèles Claude 3, aujourd’hui retirés : la fonction du cours officiel qui choisissait la version selon le nom du modèle n’a plus d’utilité. Un paramètre facultatif, max_characters, demande à votre code de tronquer l’affichage des gros fichiers à cette longueur. L’outil ajoute environ 974 jetons d’entrée à chaque requête sur les modèles Claude 4.7 et suivants, et 745 sur les modèles plus anciens.

Les quatre commandes

La commande undo_edit des premières versions a disparu avec les versions pour Claude 4 : pour revenir en arrière, c’est à votre application de garder des copies.

L’exécution vous revient

Claude demande par exemple {"command": "str_replace", "path": "main.py", "old_str": "for num in range(2, n)", "new_str": "for num in range(2, n):"}. Votre code réalise l’opération et renvoie le résultat. Voici une implémentation minimale de deux commandes :

from pathlib import Path

ROOT = Path("projet").resolve()

def safe_path(path):
    p = (ROOT / path).resolve()
    if not p.is_relative_to(ROOT):
        raise ValueError(f"chemin hors du dossier de travail : {path}")
    return p

def text_editor(command, path, **params):
    p = safe_path(path)
    if command == "view":
        if p.is_dir():
            return "\n".join(sorted(child.name for child in p.iterdir()))
        if not p.exists():
            raise ValueError(f"fichier introuvable : {path}")
        lines = p.read_text(encoding="utf-8").splitlines()
        start, end = params.get("view_range", [1, -1])
        end = len(lines) if end == -1 else end
        return "\n".join(f"{n}: {line}" for n, line in enumerate(lines[start - 1:end], start))
    if command == "str_replace":
        text = p.read_text(encoding="utf-8")
        count = text.count(params["old_str"])
        if count != 1:
            raise ValueError(f"old_str trouvé {count} fois : il doit l'être exactement une fois")
        p.write_text(text.replace(params["old_str"], params["new_str"]), encoding="utf-8")
        return "Remplacement effectué."
    raise ValueError(f"commande non prise en charge : {command}")

TOOLS["str_replace_based_edit_tool"] = text_editor

L’outil se branche sur la boucle de la leçon 38 comme les autres : une entrée dans TOOLS, et text_editor_tool dans la liste des outils. Les numéros de ligne ajoutés par view ne sont pas obligatoires, mais la documentation les juge essentiels pour que Claude se serve correctement de view_range et d’insert_line.

Les précautions

La documentation insiste sur quatre points, que l’implémentation ci-dessus applique en partie :

1. Limiter l’accès au dossier de travail : safe_path refuse tout chemin qui en sort, comme ../../etc/passwd.
2. Garder des copies des fichiers avant de les modifier, puisque undo_edit n’existe plus.
3. Exiger une correspondance unique pour str_replace, pour ne jamais modifier le mauvais passage.
4. Renvoyer des erreurs claires, comme « fichier introuvable », qui repartent vers Claude avec is_error.

Pourquoi l’utiliser

L’outil sert dès qu’une application doit modifier des fichiers sous la conduite de Claude : corriger un bogue, refactoriser, ajouter de la documentation ou des tests, sur un serveur ou dans une chaîne d’intégration continue, sans éditeur. Il reproduit dans votre application ce que font les éditeurs de code assistés par l’IA, en gardant le contrôle de tout ce qui touche au disque.

À vous de jouer

Compléter l’éditeur. Ajoutez les commandes create et insert à text_editor, ainsi qu’une copie de sauvegarde avant chaque modification. Créez un dossier projet contenant un main.py avec une erreur de syntaxe, puis demandez à l’assistant : « Corrige l’erreur de syntaxe de main.py ». Suivez dans l’historique les commandes demandées.

Sources officielles : The text edit tool (Claude Academy) · Text editor tool (documentation Claude : versions, commandes, précautions, jetons) · How tool use works (outils à schéma Anthropic)

Points clés à retenir

• Le schéma est fourni par Anthropic, l’exécution reste à votre charge.
• text_editor_20250728 et le nom str_replace_based_edit_tool valent pour tous les modèles actuels.
• Quatre commandes : view, str_replace, create, insert ; undo_edit n’existe plus.
• Limitez les chemins au dossier de travail, gardez des copies, exigez une correspondance unique.
• L’outil coûte environ 974 jetons d’entrée par requête sur les modèles récents.