Compétence de Base CarryCtx

CarryCtx offre une continuité de contexte et d'état de projet de première classe pour les agents d'IA de codage. Il permet aux agents de gérer des tâches, de suivre la progression granulaire, de créer des points de contrôle, de maintenir des graphes de dépendances AST, d'exécuter des serveurs MCP stdio, d'appliquer des préréglages de workflow et de préserver le contexte de manière transparente entre les redémarrages de session et les arbres de travail Git.

Quand l'utiliser

Utilisez les commandes CarryCtx lorsque :

Vous démarrez une nouvelle tâche ou session : Enregistrez l'identité de l'agent, démarrez la session et restaurez le contexte (carryctx resume).
Vous gérez des tâches de projet : Créez, réclamez, démarrez, terminez, bloquez ou annulez des tâches (carryctx task ...).
Vous suivez la progression granulaire : Enregistrez des éléments structurés todo, block, risk et note.
Vous sauvegardez l'état / créez un point de contrôle : Capturez le progrès actuel, le statut Git et le travail restant avant de terminer une session ou de changer de focus.
Vous explorez le graphe de code : Scannez les dépendances des modules AST (carryctx graph scan) et exportez des diagrammes Mermaid/DOT/ASCII (carryctx graph export).
Vous intégrez des outils agent IA (MCP) : Exposez le contexte du projet à Cursor / Windsurf / AGY via le serveur stdio du Protocole de Contexte de Modèle (carryctx mcp).
Vous normalisez les workflows (Préréglages) : Listez, inspectez et appliquez des plans de travail, des règles de codage et des personas d'agent (carryctx preset ...).
Vous travaillez sur des tâches parallèles : Créez et isolez des tâches dans des arbres de travail Git dédiés (carryctx worktree ...).
Vous diagnostiquez des problèmes de santé : Exécutez carryctx doctor pour détecter les tâches orphelines, les hooks manquants et les problèmes de base de données.
Vous nettoyez les anciennes données : Utilisez carryctx project prune pour supprimer les tâches terminées et alléger la base de données.
Vous produisez des analyses d'agent : Utilisez carryctx stats pour auditer les durées de session, les métriques de tâche et exporter des rapports Markdown/CSV.
Vous recherchez un travail antérieur par contenu : Utilisez carryctx search "<query>" pour trouver des tâches, des éléments de progression, des points de contrôle ou des décisions par mot-clé, sans écrire de SQL ni fouiller les messages de commit.

Prérequis

Installez l'interface en ligne de commande CarryCtx (cargo install carryctx ou binaire pré-compilé).
Initialisez CarryCtx dans le dépôt du projet : carryctx init.

Référence Rapide

Action	Commande	Objectif
Configuration Agent	`carryctx agent register --name "$(whoami)" --provider "claude-code"`	Enregistrer l'identité de l'agent
Agent Actuel	`carryctx agent current`	Afficher l'identité active de l'agent
Démarrer Session	`carryctx session start`	Commencer une session de travail suivie
Reprendre Contexte	`carryctx resume`	Récupérer la tâche courante, la progression et les actions suivantes
Créer Tâche	`carryctx task create --title "..." [--depends-on CTX-0001]`	Définir une nouvelle tâche
Réclamer Tâche	`carryctx task claim CTX-0001`	Assigner la tâche à l'agent courant
Éditer Tâche	`carryctx task edit CTX-0001 [--title ...] [--priority ...] [--description ...]`	Mettre à jour le titre, la priorité ou la description de la tâche
Démarrer Tâche	`carryctx task start CTX-0001`	Marquer la tâche comme en cours
Suivre Progression	`carryctx progress <todo	block
Point de Contrôle	`carryctx checkpoint --done "..." --remaining "..."`	Sauvegarder un instantané d'état riche en sémantique
Scanne Graphe Code	`carryctx graph scan`	Extraire les dépendances AST dans une base SQLite
Exporter Graphe	`carryctx graph export --type <mermaid	dot
Serveur MCP Stdio	`carryctx mcp`	Lancer le serveur MCP stdio avec 6 outils agent
Appliquer Préréglage	`carryctx preset apply <preset_name>`	Injecter des SOP de workflow, des règles ou des personas
Arbre de Travail	`carryctx worktree create CTX-0001`	Créer un arbre de travail Git isolé pour la tâche
Terminer Session	`carryctx session end`	Terminer la session en toute sécurité avec un point de contrôle
Doctor	`carryctx doctor`	Diagnostiquer la santé du projet
Installer Hooks	`carryctx hooks install`	Point de contrôle automatique à chaque commit Git
Nettoyer Données	`carryctx project prune --older-than 30`	Supprimer les anciennes tâches terminées
Statistiques Agent	`carryctx stats [--markdown] [--output file.csv]`	Voir les métriques et exporter des rapports de performance
Décision	`carryctx decision add --title "..." --task CTX-0001`	Enregistrer une décision architecturale
Passation	`carryctx handoff create --target <agent> --task CTX-0001`	Transférer le travail entre agents
Pause Session	`carryctx session pause`	Mettre en pause le minuteur de session active
Reprendre Session	`carryctx session resume`	Reprendre une session en pause
Recherche	`carryctx search "" [--type task	progress

Comportement de Sortie (0.5.2+)

La sortie texte (le --format text par défaut) est compacte par conception : les commandes d'entité n'affichent qu'une ligne courte par enregistrement (Task created: CTX-0321, agent current n'affiche que le nom, les listes montrent display_id, le statut et un titre/résumé tronqué) afin que le contexte de l'agent reste réduit. Lorsque des enregistrements complets sont nécessaires :

--verbose (drapeau global) ou [output] verbose = true dans .carryctx/config.toml restaure l'enregistrement complet formaté.
--fields display_id,status,summary (drapeau global) ou la table [output.fields] par commande réduit les enregistrements à une liste d'autorisation en texte et JSON.
--format json renvoie toujours l'enveloppe complète.

La sortie JSON est inchangée et reste le contrat machine : chaque succès est une enveloppe unique sur stdout, chaque erreur une enveloppe unique sur stderr.

Workflow Standard de l'Agent

1. Initialisation de Session et Restauration de Contexte

Au début de toute interaction ou après un redémarrage d'agent :

# Enregistrer et définir l'identité si ce n'est pas déjà fait
carryctx agent current || carryctx agent register --name "claude" --provider "claude-code"

# Démarrer la session et charger le contexte actuel
carryctx session start
carryctx resume

Pour mettre en pause et reprendre des sessions :

carryctx session pause    # Mettre en pause la session active (le minuteur s'arrête)
carryctx session resume   # Reprendre une session en pause
carryctx session end      # Terminer la session avec un point de contrôle optionnel
carryctx session abandon  # Terminer la session sans point de contrôle

2. Analyse des Dépendances du Code (Sous-système Graphe)

Avant de modifier du code ou de refactoriser des modules :

# 1. Scannez les dépendances AST de la base de code
carryctx graph scan

# 2. Exportez un sous-graphe centré autour d'un module spécifique
carryctx graph export --type mermaid --focus "src/application/stats.rs" --depth 2

# 3. Exportez un aperçu architectural ASCII compact au niveau des modules
carryctx graph export --type ascii --compact

3. Préréglages de Workflow et Injection de Règles

Injectez des procédures opératoires standard ou des directives de codage :

# Lister les préréglages de workflow disponibles
carryctx preset list

# Appliquer un préréglage de workflow de correction de bogue standard au projet courant
carryctx preset apply workflows/bugfix

4. Cycle de Vie d'une Tâche

# Lister les tâches ouvertes
carryctx task list --status ready

# Réclamer et démarrer la tâche
carryctx task claim CTX-0001
carryctx task start CTX-0001

# Marquer la tâche comme terminée après vérification
carryctx task complete CTX-0001

5. Suivi Granulaire de la Progression

Au fur et à mesure de l'avancement, enregistrez des éléments de progression structurés :

carryctx progress todo "Écrire le test unitaire pour le middleware d'authentification"
carryctx progress todo "Implémenter la validation du jeton JWT"
carryctx progress block "Attente de confirmation des spécifications du point de terminaison API"
carryctx progress risk "Changement cassant dans la dépendance amont"
carryctx progress note "Utilisation d'un cache LRU pour optimiser les recherches de jetons"
# Marquer un todo comme terminé :
carryctx progress complete PX-0001

6. Création de Points de Contrôle

Sauvegardez l'état avant de terminer une session, de changer de tâche ou de passer le relais :

carryctx checkpoint \
  --done "Points de terminaison d'authentification backend terminés" \
  --remaining "Intégration du formulaire de connexion frontend" \
  --blocker "Aucun"

7. Parallélisme avec les Arbres de Travail

Lorsque vous travaillez sur des tâches indépendantes simultanément :

carryctx worktree create CTX-0002
# Bascule vers un répertoire d'arbre de travail isolé lié à CTX-0002

7a. Enregistrement des Décisions et Passations

Capturez les décisions architecturales et passez le travail entre agents :

# Enregistrer une décision architecturale (ADR) liée à une tâche
carryctx decision add --title "Utiliser SQLite pour le stockage" --task CTX-0001

# Lister ou rechercher des décisions
carryctx decision list
carryctx decision search --keyword SQLite

# Marquer une décision comme remplacée par une plus récente
carryctx decision supersede DEC-0001 --by DEC-0002

# Créer une passation pour transférer le travail à un autre agent
carryctx handoff create --target <agent-ulid> --summary "Implémenter l'API" --task CTX-0001

# Accepter, rejeter ou fermer une passation
carryctx handoff accept HO-0001
carryctx handoff reject HO-0001 --reason "Pas mon domaine"
carryctx handoff close HO-0001

7b. Recherche en Texte Intégral dans l'Historique du Projet

Trouvez un travail antérieur par son contenu, sans avoir à vous souvenir de la branche ou de la tâche concernée. Recherche dans les titres/descriptions de tâches, les éléments de progression, les notes de points de contrôle et les décisions, le tout classé par pertinence :

# Rechercher dans tout
carryctx search "markdown worker protocol"

# Limiter à un type d'entité
carryctx search "retry backoff" --type checkpoint

# Affiner par le statut de la tâche propriétaire ou l'agent propriétaire
carryctx search "auth" --status in_progress
carryctx search "auth" --owner claude-code

Chaque résultat inclut l'ID d'affichage de la tâche propriétaire, son statut et (lorsqu'il est connu) la branche sur laquelle elle a été travaillée — utilisez ceci avant de commencer un travail connexe pour éviter de dupliquer des problèmes déjà résolus, et avant une passation pour diriger l'agent récepteur vers le point de contrôle ou la décision exacte qui explique un choix antérieur.

8. Terminer la Session et Rapporter

# Terminer la session de travail
carryctx session end

# Exporter le rapport de statistiques du projet pour la description de la PR ou la documentation
carryctx stats --markdown --output /tmp/project_stats.md

9. Intégration du Protocole de Contexte de Modèle (MCP)

Pour connecter CarryCtx directement à Cursor / Windsurf / AGY :

{
  "mcpServers": {
    "carryctx": {
      "command": "carryctx",
      "args": ["mcp"]
    }
  }
}

Outils MCP exposés :

carryctx_graph_explorer : Interroger, scanner et exporter le Graphe de Contexte du projet
carryctx_context_manager : Gérer le contexte persistant, les points de contrôle et les instantanés d'état
carryctx_task_manager : Gérer les tâches du projet, les dépendances et les priorités
carryctx_progress_tracker : Gérer la progression des tâches, les notes et les bloqueurs
carryctx_decision_logger : Enregistrer et rechercher des enregistrements de décisions architecturales
carryctx_project_admin : Gérer la base de données du projet, les statistiques, l'archivage et la configuration

10. Débogage et Dépannage

Activez la journalisation de débogage structurée pour diagnostiquer les problèmes :

# Afficher les logs de débogage pour les opérations CarryCtx
export RUST_LOG=carryctx=debug
carryctx task list          # Voir la sortie de débogage avant les résultats de la commande

# Afficher uniquement les erreurs
export RUST_LOG=error
carryctx status

# Exécuter les diagnostics
carryctx doctor             # Vérifier la santé du projet
carryctx doctor --json      # Sortie de diagnostic lisible par machine

Meilleures Pratiques pour les Agents de Codage

Exécutez toujours carryctx resume au démarrage : Réoriente immédiatement l'agent vers la tâche et la progression en cours.
Scannez le graphe de code avant les grandes refontes : carryctx graph scan empêche les dépendances amont cassées.
Réclamez explicitement les tâches : Empêche l'exécution en double lorsque plusieurs agents travaillent sur le même dépôt.
Utilisez des éléments de progression structurés : Tenez todo, done et block à jour pendant les étapes d'exécution.
Créez un point de contrôle avant de vous arrêter : Créez toujours un point de contrôle avant de céder le contrôle ou de terminer un travail complexe en plusieurs étapes.
Exécutez carryctx doctor lors de la première utilisation ou après une mise à jour : Détecte les lacunes de configuration avant qu'elles ne provoquent des erreurs d'exécution.

CarryCtx Compétence de Base

Qu'est-ce que CarryCtx Compétence de Base ?

Demander à votre IA préférée

Documentation