Passer au contenu principal
Cette page couvre les modèles éprouvés pour obtenir les meilleurs résultats d’Embedder, rassemblés auprès des ingénieurs qui l’utilisent dans un large éventail d’environnements. Le facteur le plus important est la durée de la séance. À mesure qu’une session s’allonge, Embedder accumule l’historique des conversations, le contenu des fichiers et les sorties de commandes. Lorsqu’il y a trop de contexte accumulé, Embedder peut perdre la trace des instructions précédentes, commettre davantage d’erreurs ou se comporter de manière incohérente. Garder la concentration des séances est le moyen le plus efficace de maintenir la précision. Utilisez ce guide comme point de départ. Faites attention à ce qui fonctionne et à ce qui ne fonctionne pas.

​
Aidez Embedder à vérifier son travail

Incluez les tests ou les résultats attendus afin qu’Embedder puisse se vérifier.
Embedder fonctionne mieux lorsqu’il peut vérifier son propre travail. Sans critères de réussite clairs, elle peut générer des solutions qui semblent correctes mais qui échouent en pratique. Dans ces cas-là, vous devenez la seule source de commentaires et chaque erreur nécessite une révision et une intervention manuelles.
StratégieAvantAprès
Fournir des critères de vérification”implémenter une fonction qui lit un capteur de température""implémentez read_temperature(). Lorsque le capteur renvoie la valeur brute 0x0190, la fonction doit renvoyer 25,0°C. Incluez des tests unitaires avec des lectures I²C simulées et vérifiez les sorties pour [0x0000 -> 0,0°C, 0x0190 -> 25,0°C, 0x0320 -> 50,0°C]. Les tests doivent réussir.”
S’attaquer aux causes profondes, pas aux symptômes”la construction échoue""la construction échoue avec cette erreur : [coller l’erreur]. corrigez-la et vérifiez que la construction réussit. résolvez la cause première, ne supprimez pas l’erreur”
Votre vérification peut prendre de nombreuses formes, comme une suite de tests, un linter ou une commande Bash qui valide la sortie. Investissez du temps pour rendre ces contrôles fiables et approfondis, car une vérification solide permet d’obtenir des résultats cohérents et fiables.

​
Explorez et planifiez, puis codez

Séparez la recherche et la planification de la mise en œuvre pour améliorer les résultats.
Laisser Embedder passer directement au codage peut produire un code qui résout le mauvais problème. Utilisez le Mode Plan pour séparer la recherche et la planification de l’exécution. Le flux de travail recommandé comporte quatre phases :
1

Explore

Entrez en mode Planification. Embedder lit les fichiers et répond aux questions sans apporter de modifications.
Embedder (Plan Mode)
Read /firmware/src and explain how GPIO, UART, and the main loop are initialized. 
Also check how the board clock and pin configuration are set up.
2

Plan

Demandez à Embedder de créer un plan de mise en œuvre détaillé.
Embedder (Plan Mode)
I want to add a feature that blinks an LED at 1 Hz and prints "alive" over UART every second.
What files need to change? How should the timer interrupt be configured?
Create a step-by-step implementation plan and list tests to verify it works on hardware.
Lorsqu’Embedder a fini de créer un plan, vous pouvez soit l’approuver et poursuivre l’exécution, soit lui donner votre avis sur les éléments à modifier. Vous pouvez éditer manuellement le plan en vous rendant au .embedder/plans dans votre répertoire de projets.
3

Implement

Revenez en mode Act et laissez Embedder coder, en vérifiant par rapport à son plan.
Embedder (Act Mode)
Implement the LED blink + UART heartbeat from your plan. 
Configure a hardware timer interrupt.
Add a small test or debug log to confirm the ISR fires every 1 second.
Build the firmware and fix any compile errors.
4

Commit

Demandez à Embedder de s’engager avec un message descriptif et de créer un PR.
Embedder (Act Mode)
Commit with a descriptive message and open a PR.
Le mode Plan peut améliorer les résultats, mais il n’est pas toujours nécessaire et peut ralentir un travail simple. Lorsque la tâche est simple et de portée limitée, comme corriger un petit bug, ajouter une instruction de débogage ou effectuer un changement de nom mineur, il est généralement plus rapide d’exécuter la modification immédiatement. Une étape de planification dédiée est plus efficace pour les situations plus complexes, en particulier lorsque la solution n’est pas claire, que la mise à jour touche plusieurs parties de la base de code ou que vous travaillez avec du code inconnu.

​
Fournir un contexte spécifique dans les invites

Plus vos instructions sont précises, moins vous aurez besoin de corrections.
Embedder peut souvent déduire votre intention, mais il n’a pas de connaissance implicite de vos objectifs ou de vos hypothèses. Soyez explicite et précis dans vos instructions. Référencez les fichiers exacts à modifier, indiquez les contraintes ou exigences éventuelles et créez un lien vers des exemples ou des modèles pertinents à suivre.
StratégieAvantAprès
Étendez la tâche. Spécifiez quel fichier, quel scénario et vos préférences de test.”Ajouter des tests pour uart.c""Écrivez un test au niveau matériel pour drivers/uart.c qui vérifie la gestion du dépassement de tampon RX. Simulez plus de 256 octets arrivant dos à dos et garantissez l’absence de corruption de la mémoire. Évitez les simulations ; utilisez le harnais de test HAL existant.”
Pointez vers les sources. Dirigez Embedder vers la source qui peut répondre à une question.”Pourquoi le pilote SPI est-il si compliqué ?""Lisez drivers/spi.c et son historique git et résumez l’évolution du pilote SPI. Expliquez toutes les contraintes matérielles qui ont influencé la conception.”
Référencez les modèles existants. Pointez Embedder vers les modèles de votre base de code.”Ajouter un pilote de capteur I2C""Regardez comment drivers/adc.c et drivers/uart.c structurent les fonctions init/config/read. Suivez le même modèle pour implémenter drivers/i2c_temp_sensor.c. Faites correspondre la dénomination, la gestion des erreurs et le style ISR. N’introduisez pas de nouveaux frameworks.”
Décrivez le symptôme. Fournissez le symptôme, l’emplacement probable et à quoi ressemble « corrigé ».”Corriger le bug des LED""La LED d’état arrête de clignoter de manière aléatoire après environ 10 minutes. Probablement lié au timer ISR dans src/timer.c. Reproduisez avec une boucle de longue durée, ajoutez une journalisation pour confirmer les interruptions manquées, puis corrigez afin que la LED maintienne un clignotement stable de 1 Hz pendant plus de 30 minutes.”
Des invites vagues peuvent en fait être très utiles lorsque vous explorez ou êtes ouvert aux suggestions. Demander « Quels bogues y a-t-il dans ce fichier ? peut faire apparaître des choses que vous n’auriez pas trouvées autrement.

​
Fournir du contexte

Vous pouvez fournir des données riches à Embedder de plusieurs manières :
  • Fichiers de référence avec @ au lieu de décrire où se trouve le code.
  • Documentation de référence dans l’espace de travail de votre projet.
  • Donnez les URL pour la documentation et les références en ligne.

​
Configurez votre environnement

Une petite quantité de configuration initiale peut rendre Embedder beaucoup plus efficace à chaque session. Prendre le temps de configurer votre environnement et de fournir le bon contexte aide l’agent à travailler de manière plus précise, cohérente et efficace dès le départ.

​
Ecriture d’un fichier EMBEDDER.md

Exécutez /init pour générer un fichier de démarrage EMBEDDER.md basé sur la structure actuelle de votre projet.
Embedder lit automatiquement un fichier EMBEDDER.md au début de chaque session. Utilisez ce fichier pour définir des détails importants tels que les commandes bash courantes, les conventions de codage et les directives de flux de travail. Cela fournit un contexte persistant qui ne peut pas être déduit de manière fiable de la seule base de code. La commande /init analyse votre projet pour identifier les systèmes de build, les frameworks de test et les modèles récurrents. Cela crée un point de départ solide que vous pouvez ensuite personnaliser et affiner. Aucune structure stricte n’est requise pour le EMBEDDER.md, mais elle doit rester concise et facile à comprendre. Visez des instructions claires et lisibles par l’homme plutôt qu’une longue documentation.
Embedder.md
# Code style
- Follow the project’s C or C++ style guide and keep functions small and single purpose
- Use consistent naming for peripherals and drivers such as uart_init, spi_write, adc_read
- Avoid dynamic allocation in firmware. Prefer static or stack memory

# Workflow
- Always build the firmware after changes and fix all compiler warnings
- Flash and verify on real hardware or simulation before marking tasks complete
- Run targeted unit tests or hardware specific tests instead of the full suite for faster iteration
EMBEDDER.md est chargé au début de chaque session, incluez donc uniquement les informations qui s’appliquent largement à l’ensemble de votre projet. Gardez le fichier court et ciblé. Pour chaque ligne, demandez-vous : « Si cela manquait, Embedder ferait-il des erreurs ? » Si la réponse est non, supprimez-le. Un EMBEDDER.md surdimensionné ou encombré dilue les conseils importants et rend plus probable qu’Embedder néglige vos instructions réelles.
InclureExclure
Commandes Embedder ne peut pas devinerTout ce qu’Embedder peut voir dans le code ou la documentation
Règles de style de code uniquesConventions linguistiques standard
Instructions de test et testeurs préférésDocumentation détaillée de l’API (lien vers la documentation à la place)
Étiquette du référentielDes informations qui changent fréquemment
bizarreries de l’environnement de développement (vars d’environnement obligatoires)Descriptions fichier par fichier de la base de code
Problèmes courants ou comportements non évidentsDes pratiques évidentes comme « écrire du code propre »
Si Embedder continue de faire quelque chose que vous avez explicitement interdit, votre EMBEDDER.md est probablement trop long et la règle est enterrée. S’il pose des questions auxquelles on répond déjà dans le dossier, la formulation est probablement ambiguë ou peu claire. Traitez EMBEDDER.md comme du code : examinez-le lorsque le comportement ne va pas, élaguez régulièrement les lignes inutiles ou redondantes et testez les modifications pour confirmer que le comportement d’Embedder change réellement. Vous pouvez également améliorer l’observance en mettant clairement l’accent sur « IMPORTANT » ou « VOUS DEVEZ ». Vérifiez le fichier dans git afin que votre équipe puisse contribuer, car les petites améliorations s’accumulent au fil du temps et rendent le document de plus en plus précieux.

​
Fournir de la documentation

Exécutez /peripheral pour modifier la documentation périphérique associée à votre projet
De nombreuses plates-formes et périphériques disposent d’une documentation pré-indexée. Si vous constatez qu’Embedder se trompe sur votre carte ou vos périphériques, envisagez de télécharger une documentation supplémentaire via la console Web. Si vous avez ajouté votre propre plate-forme ou périphérique, assurez-vous de télécharger une documentation suffisante et à jour. Vous pouvez ajouter plus de documentation pour votre plate-forme ou vos périphériques en utilisant la commande /console et en téléchargeant plus de documentation dans la section projets de l’application Web.

​
Utiliser les outils CLI

Dites à Embedder d’utiliser des outils tels que gh, west ou openocd lors de l’interaction avec des services externes.
Le moyen le plus efficace d’interagir avec les services externes consiste à utiliser les outils CLI. Si vous utilisez GitHub, installez la CLI gh. Embedder sait comment l’utiliser pour créer des problèmes, ouvrir des demandes d’extraction et lire des commentaires. Sans gh, Embedder peut toujours utiliser l’API GitHub, mais les requêtes non authentifiées atteignent souvent les limites de débit. Embedder est également excellent pour apprendre les outils CLI qu’il ne connaît pas déjà. Essayez des invites comme Use 'cli-tool --help' to learn about more about the cli tool, then use it to solve A, B, C.

​
Posez des questions sur votre base de code

Posez à Embedder des questions que vous poseriez à un employé ou à un ingénieur senior.
Lors de l’intégration dans une nouvelle base de code, utilisez Embedder pour l’apprentissage et l’exploration. Vous pouvez poser à Embedder des questions que vous poseriez à un autre ingénieur :
  • Comment fonctionne la journalisation des erreurs ?
  • Comment lire les données du capteur utilisé dans ce projet ?
  • Que fait le handle_sample() à la ligne 134 du foo.c ?
  • Quels cas extrêmes le TIMER_CTRL traite-t-il ?
  • Pourquoi ce code appelle le foo1() au lieu du foo2() à la ligne 173 ?
Cela peut considérablement accélérer l’intégration et réduire la charge des autres ingénieurs.

​
Gérez votre session

Les conversations sont persistantes et les modifications apportées au cours de celles-ci peuvent être inversées.

​
Corriger le parcours tôt et souvent

Corrigez Embedder tôt et souvent.
Embedder fonctionne mieux avec une boucle de rétroaction étroite. La correction d’Embedder produit rapidement de meilleures solutions à un rythme plus rapide.
  • Esc : Arrêter l’Embeder en cours d’action avec la touche Esc. Le contexte est préservé, vous pouvez donc rediriger.
  • Ctrl + z (2x) ou /rewind : Appuyez sur Ctrl + z (2x) ou exécutez /rewind pour ouvrir le menu de rembobinage et restaurer la conversation précédente et l’état du code.
  • Ctrl + z or /undo : Appuyez sur Ctrl + z ou exécutez /undo pour qu’Embeder annule sa modification la plus récente.
  • /clear : Réinitialiser le contexte entre des tâches non liées. De longues sessions avec un contexte non pertinent peuvent réduire les performances.
Si vous avez corrigé Embedder plus de deux fois sur le même problème au cours d’une même session, le contexte est encombré d’approches ayant échoué. Exécutez /clear et recommencez avec une invite plus spécifique qui intègre ce que vous avez appris. Une session propre avec une meilleure invite surpasse presque toujours une longue session avec des corrections accumulées.

​
Gérer le contexte de manière agressive

Exécutez /clear entre des tâches non liées pour réinitialiser le contexte.
Embedder compresse automatiquement l’historique des conversations pendant les longues sessions, préservant ainsi le code et les décisions importantes tout en libérant de l’espace. Lors de sessions plus longues, la fenêtre contextuelle d’Embedder peut se remplir d’informations non pertinentes. Cela réduit les performances et distrait parfois Embedder.
  • Utilisez /clear fréquemment entre les tâches pour réinitialiser entièrement la fenêtre contextuelle
  • Lorsque la compression automatique se déclenche, Embedder résume ce qui compte le plus, y compris les modèles de code, les états des fichiers et les décisions clés
  • Pour plus de contrôle, vous pouvez exécuter /compress pour choisir quand la compression se produit
  • Personnalisez le comportement de compression dans EMBEDDER.md avec des instructions telles que "When compressing, make sure to keep track of the full list of modified files" pour vous assurer que tout contexte important survit au résumé

​
Utiliser des sous-agents pour l’enquête

Déléguer la recherche au "use subagents to investigate X". Ils explorent dans un contexte distinct, gardant votre conversation principale propre pour la mise en œuvre.
Les sous-agents sont l’un des outils les plus efficaces pour maintenir la concentration des sessions. Lorsqu’Embedder recherche une base de code, il lit de nombreux fichiers, ce qui peut ralentir les performances lors de longues sessions. Les sous-agents effectuent la tâche dans une fenêtre contextuelle distincte et renvoient des résumés : 
Use subagents to investigate how our firmware initializes the CAN peripheral, handles message TX/RX interrupts, 
and whether we already have reusable CAN drivers I should build on instead of writing new code.
Le sous-agent explore la base de code, lit les fichiers pertinents et rend compte de ses résultats, le tout sans encombrer votre conversation principale.

​
Revenir aux points de contrôle précédents

Chaque action effectuée par Embedder crée un point de contrôle. Vous pouvez restaurer la conversation et le code à un état antérieur.
Intégrez automatiquement les points de contrôle avant les modifications. Exécutez le /undo pour annuler la dernière modification ou le /rewind pour ouvrir le menu du point de contrôle. Au lieu de planifier soigneusement tous vos mouvements, vous pouvez dire à Embedder d’essayer quelque chose et si cela ne fonctionne pas, rembobinez et essayez-le d’une autre manière.
Les points de contrôle suivront uniquement les modifications apportées par Embedder.

​
Reprendre les conversations

Exécutez /history pour reprendre une conversation là où vous l’avez laissée.
Embedder conserve une copie des conversations localement. Lorsqu’une tâche s’étend sur plusieurs sessions (vous démarrez une fonctionnalité, êtes interrompu, revenez le lendemain), vous n’avez pas besoin de réexpliquer le contexte.

​
Évitez les pièges

Voici quelques conseils utiles pour éviter les erreurs courantes.
  • Exécuter /clear entre des tâches non liées. Sinon, vous risquez de gonfler votre fenêtre contextuelle avec de nombreuses informations non pertinentes.
  • Exécutez /clear après des échecs. Si Embedder fait quelque chose de mal, après deux ou trois corrections échouées, exécutez /clear et écrivez une meilleure invite initiale intégrant ce que vous avez appris, car le contexte sera pollué par des approches échouées.
  • Ajoutez une documentation supplémentaire. Si Embedder semble mal comprendre certains aspects de votre matériel. Envisagez de télécharger de la documentation supplémentaire ou de remplacer la documentation actuelle.
  • Élaguez EMBEDDER.md souvent. Si EMBEDDER.md est trop long, Embedder en ignorera une grande partie car les règles importantes se perdront dans le bruit. Moins il y a de directives dans EMBEDDER.md, plus Embedder se concentrera sur le respect de ces directives.
  • Définissez les tâches et utilisez des sous-agents. Si vous demandez à Embedder d‘“explorer” quelque chose et de ne pas le réduire, Embedder peut finir par remplir son contexte rapidement. Étendez les tâches ou utilisez des sous-agents pour préserver le contexte.
Last modified on March 5, 2026