Planning with Files : conserver le contexte d’un agent sur disque
Planification persistante basée sur des fichiers pour les agents de codage IA et les tâches de longue durée. Plans de réduction anti-crash, récupération de session après /clear et compactage, réinjection par tour contre la pourriture du contexte, porte d'achèvement déterministe. À la manière de Manus. Claude Code, Codex, Cursor, Kiro, OpenCode et plus de 60 agents via le standard Agent Skills.
En bref
- De quoi s’agit-il ?
- Ce que Planning with Files : conserver le contexte d’un agent sur disque permet, ses limites et les vérifications adaptées à son usage.
- À qui s’adresse-t-il ?
- Convient aux lecteurs dont le besoin correspond précisément au périmètre de Planning with Files : conserver le contexte d’un agent sur disque. Ne convient pas à ceux qui déduisent une garantie de production d’une simple démonstration.
- Puis-je l’utiliser commercialement ?
- Oui. MIT est une licence permissive : vous pouvez utiliser, modifier et vendre un logiciel qui en dépend, à condition de conserver les mentions de droit d’auteur et de licence.
- Est-il encore maintenu ?
- Oui. Les derniers commits datent d’il y a 1 jour.
- En quel langage est-il écrit ?
- Principalement Python, d’après les statistiques de langage de GitHub.
Ces réponses reposent sur les données GitHub du projet (dernière synchronisation le 15 septembre 2026) et sur notre analyse. Elles ne constituent pas un avis juridique.
ANALYSE OPEN SOURCE APPROFONDIE
Planning with Files : conserver le contexte d’un agent sur disque : L'approche de planification par fichiers
planning-with-files est une compétence pour les agents de codage IA qui place l'état de planification sur le disque au lieu de le laisser uniquement dans la fenêtre de contexte. Pour une tâche, la compétence crée trois fichiers Markdown : task_plan.md suit les phases et les cases à cocher, findings.md accumule les notes de recherche et les décisions, et progress.md contient le journal de session et les résultats de test. Le README décrit le principe central comme traitant la fenêtre de contexte comme la RAM et le système de fichiers comme le disque : tout ce qui est important est écrit sur le disque. Les fichiers sont réinjectés au début de chaque tour, donc un /clear, un crash ou une compaction du contexte ne détruit pas le plan.
Planning with Files : conserver le contexte d’un agent sur disque : Ce qui change après /clear
L'exemple avant-après du README montre l'échec habituel : une nouvelle session sans fichiers de plan dit qu'elle n'a pas de contexte et demande à l'utilisateur de reformuler la tâche. Avec la compétence, l'agent reprend en lisant les fichiers depuis le disque. Le format d'injection est un bloc délimité par ===BEGIN PLAN DATA=== et ===END PLAN DATA===, écrit dans le contexte par un hook UserPromptSubmit à partir de task_plan.md. Le benchmark de récupération interne du projet rapporte qu'une nouvelle session avec les fichiers sur disque a repris en 5,0 tours en moyenne, contre 13,3 pour un agent brut sans méthode de planification. Le README qualifie ce benchmark d'interne, exécuté par l'auteur, et renvoie à docs/evals.md pour la méthode et les limites.
Planning with Files : conserver le contexte d’un agent sur disque : Voies d'installation et couverture des plateformes
Le README documente deux voies d'installation principales. Pour Claude Code, la voie plugin ajoute le dépôt comme marketplace et installe le plugin, qui fournit la compétence, les hooks et les commandes slash. Pour tout autre agent, la commande npx skills add installe la compétence via la norme Agent Skills, couvrant plus de 60 agents. Le README avertit que la voie compétence peut silencieusement se terminer sans hooks si la confiance du projet n'est pas acceptée ou si les hooks de frontmatter ne s'enregistrent pas lors des installations au niveau projet, et recommande la voie plugin pour les utilisateurs qui ont besoin des hooks, puis une vérification avec /plan-doctor. Le dépôt fournit également des miroirs par IDE pour Claude Code, Codex, Cursor, Kiro, OpenCode et d'autres plateformes.
Planning with Files : conserver le contexte d’un agent sur disque : Le mécanisme : fichiers, hooks et récupération
La compétence définit un flux de décision pour l'agent : créer les trois fichiers lorsqu'une tâche nécessite 3 étapes ou plus ou 5 appels d'outils ou plus, ajouter les informations apprises à findings.md, journaliser les actions dans progress.md, cocher les phases dans task_plan.md, et relire tous les fichiers après une réinitialisation du contexte. Les hooks de cycle de vie rendent ces étapes mécaniques : le README liste 5 hooks sur Claude Code, 7 sur Codex et 8 sur Pi, couvrant la réinjection du plan à chaque tour, les rappels après les écritures et une vérification d'achèvement avant l'arrêt. La récupération de session après /clear fonctionne en vérifiant le stockage de session de l'IDE actif, en trouvant quand les fichiers de plan ont été mis à jour pour la dernière fois, en extrayant la conversation après ce point et en affichant un rapport de rattrapage.
Planning with Files : conserver le contexte d’un agent sur disque : Les fonctionnalités v3 pour les tâches longues
La ligne v3 ajoute des fonctionnalités visant les exécutions agentiques de longue durée. Le mode autonome supprime la récitation du plan à chaque appel d'outil mais conserve l'injection au début du tour. Le mode gated ajoute une porte d'arrêt qui ne bloque que lorsque toutes les conditions d'achèvement sont simultanément remplies. Le rattrapage de session relit les fichiers de plan après /clear depuis le stockage de session de l'IDE. L'attestation de plan SHA-256 verrouille task_plan.md et refuse un plan altéré à l'injection. Un registre d'exécution enregistre les transitions de phase dans un fichier JSONL append-only. Des variables d'environnement contrôlent le comportement : PLANNING_DISABLED=1 ignore toute lecture de plan pour un appel, PLAN_ID épingle le terminal à un plan sous .planning, et PWF_INJECT=smart remplace la fenêtre d'injection fixe head -50 par l'objectif, la prochaine étape, la phase actuelle et les décisions récentes.
Planning with Files : conserver le contexte d’un agent sur disque : Les benchmarks rapportés dans le README
Le README rapporte une évaluation utilisant le framework skill-creator d'Anthropic : compétence v2.21.0, modèle claude-sonnet-4-6, datée 2026-03-06. La compétence a réussi 29 des 30 assertions objectivement vérifiables contre 2 sur 30 sans elle, a suivi le modèle à 3 fichiers dans 5 évaluations sur 5 contre 0 sur 5, a gagné 3 comparaisons A/B en aveugle sur 3 contre 0 sur 3, et a obtenu un score moyen de rubrique de 10,0 contre 6,8. Le README note que ce chiffre mesure la fidélité au modèle de fichiers, pas la dérive d'objectifs sur de longues exécutions autonomes, et que les modèles plus récents et le travail en mode autonome ne sont pas encore couverts. Un benchmark de récupération interne séparé, v1 daté 2026-07-06 et exécuté par l'auteur contre v3.4.0, a mesuré les tours pour reprendre après un effacement de contexte : 5,0 avec les fichiers, 13,3 pour un agent brut.
Planning with Files : conserver le contexte d’un agent sur disque : Contenu du dépôt et licence
La disposition du dépôt dans le README montre la compétence canonique sous skills/planning-with-files avec SKILL.md, scripts, templates et exemples, plus cinq variantes traduites, un chemin .agents/skills pour la norme Agent Skills, des répertoires miroirs par IDE, de la documentation, une suite de tests et des fichiers racine incluant LICENSE. Le projet est distribué sous licence MIT, copyright 2026 Ahmad Adi, qui accorde la permission d'utiliser, copier, modifier, fusionner, publier, distribuer, sous-licencier et vendre des copies, et déclare que le logiciel est fourni tel quel sans garantie d'aucune sorte, y compris la qualité marchande, l'adéquation à un usage particulier et la non-contrefaçon. Le texte de licence ne traite pas de la posture de sécurité du projet, des engagements de support ou de quoi que ce soit au-delà de cet avertissement.
Planning with Files repose sur trois fichiers Markdown qui donnent à un agent de codage un état persistant. Testez la création du plan, la reprise après interruption et la mise à jour du journal avec un petit dépôt réel. Le résultat à observer est la continuité entre les étapes, pas une promesse générale sur les agents.
Conclusion éditoriale
Convient aux lecteurs dont le besoin correspond précisément au périmètre de Planning with Files : conserver le contexte d’un agent sur disque. Ne convient pas à ceux qui déduisent une garantie de production d’une simple démonstration. Commencez par la vérification propre au dépôt décrite ici, observez ses entrées, ses sorties et ses erreurs, puis décidez sur cette base.
Notes de la communauté