Best Practices

Diese Seite beschreibt bewaehrte Muster, mit denen du die besten Ergebnisse aus Embedder herausholst. Die Empfehlungen stammen von Engineers, die Embedder in unterschiedlichsten Umgebungen einsetzen. Der wichtigste Faktor ist die Sitzungslaenge. Je laenger eine Sitzung dauert, desto mehr Konversationsverlauf, Dateiinhalte und Kommandoausgaben sammelt Embedder. Wird zu viel Kontext angehaeuft, kann Embedder fruehere Anweisungen schlechter verfolgen, mehr Fehler machen oder inkonsistent reagieren. Fokussierte Sitzungen sind der wirksamste Hebel fuer hohe Genauigkeit. Nutze diese Anleitung als Startpunkt. Beobachte genau, was gut funktioniert und was nicht.

Hilf Embedder, die eigene Arbeit zu verifizieren

Gib Tests oder erwartete Ausgaben an, damit Embedder seine Ergebnisse selbst pruefen kann.

Embedder liefert die besten Ergebnisse, wenn es seine Arbeit selbst verifizieren kann. Ohne klare Erfolgskriterien kann es Loesungen erzeugen, die richtig aussehen, in der Praxis aber scheitern. Dann bist du die einzige Rueckkopplungsschleife, und jeder Fehler braucht manuelle Pruefung und Nacharbeit.

Strategie	Vorher	Nachher
Verifizierungskriterien angeben	”implementiere eine funktion, die einen temperatursensor liest"	"implementiere read_temperature(). Wenn der Sensor den Rohwert 0x0190 liefert, soll die Funktion 25.0°C zurueckgeben. Fuege Unit-Tests mit gemockten I²C-Reads hinzu und verifiziere Ausgaben fuer [0x0000 -> 0.0°C, 0x0190 -> 25.0°C, 0x0320 -> 50.0°C]. Tests muessen bestehen.”
Ursachen statt Symptome adressieren	”der build schlaegt fehl"	"der build scheitert mit diesem fehler: [fehler einfuegen]. behebe ihn und verifiziere, dass der build erfolgreich ist. behebe die ursache und unterdruecke den fehler nicht.”

Deine Verifizierung kann viele Formen annehmen, zum Beispiel Testsuites, Linter oder Bash-Befehle, die Ausgaben validieren. Investiere in zuverlaessige und gruendliche Checks, denn starke Verifizierung sorgt fuer konsistente, belastbare Ergebnisse.

Erst analysieren und planen, dann coden

Trenne Recherche und Planung von der Umsetzung, um bessere Ergebnisse zu erzielen.

Wenn Embedder direkt mit dem Coden beginnt, loest es unter Umstaenden das falsche Problem. Nutze den Plan-Modus, um Analyse und Planung von der Ausfuehrung zu trennen. Der empfohlene Ablauf hat vier Phasen:

Analysieren

Wechsle in den Plan-Modus. Embedder liest Dateien und beantwortet Fragen, ohne Aenderungen vorzunehmen.

Embedder (Plan-Modus)

Lies /firmware/src und erklaere, wie GPIO, UART und die Main-Loop initialisiert werden.
Pruefe auch, wie Board-Takt und Pin-Konfiguration gesetzt werden.

Planen

Lass Embedder einen detaillierten Implementierungsplan erstellen.

Embedder (Plan-Modus)

Ich moechte ein Feature hinzufuegen, das eine LED mit 1 Hz blinken laesst
und jede Sekunde "alive" ueber UART ausgibt.
Welche Dateien muessen geaendert werden? Wie sollte der Timer-Interrupt konfiguriert werden?
Erstelle einen Schritt-fuer-Schritt-Plan und liste Tests auf, die auf Hardware verifizieren, dass es funktioniert.

Wenn der Plan fertig ist, kannst du ihn entweder freigeben und mit der Umsetzung fortfahren oder Feedback geben. Du kannst den Plan auch manuell in .embedder/plans in deinem Projektverzeichnis anpassen.

Umsetzen

Wechsle zurueck in den Act-Modus und lasse Embedder den Plan implementieren und verifizieren.

Embedder (Act-Modus)

Implementiere das LED-Blinken + UART-Heartbeat aus deinem Plan.
Konfiguriere einen Hardware-Timer-Interrupt.
Fuege einen kleinen Test oder Debug-Log hinzu, um zu bestaetigen, dass der ISR jede Sekunde ausloest.
Baue die Firmware und behebe etwaige Compile-Fehler.

Committen

Bitte Embedder, mit einer aussagekraeftigen Nachricht zu committen und einen PR zu erstellen.

Embedder (Act-Modus)

Erstelle einen Commit mit einer aussagekraeftigen Nachricht und oeffne einen PR.

Der Plan-Modus verbessert oft die Ergebnisse, ist aber nicht immer notwendig und kann einfache Arbeit verlangsamen. Wenn die Aufgabe klar und klein ist, etwa ein kleiner Bugfix, ein Debug-Statement oder ein Rename, ist die direkte Ausfuehrung meist schneller. Ein dedizierter Planungsschritt ist am wirksamsten bei komplexeren Situationen, besonders wenn die Loesung unklar ist, mehrere Teile der Codebasis betroffen sind oder du mit unbekanntem Code arbeitest.

Gib in Prompts praezisen Kontext

Je genauer deine Anweisungen sind, desto weniger Korrekturen brauchst du.

Embedder kann deine Absicht oft ableiten, hat aber kein implizites Wissen ueber deine Ziele oder Annahmen. Formuliere explizit und praezise. Verweise auf konkrete Dateien, nenne Randbedingungen und verlinke relevante Beispiele oder Muster.

Strategie	Vorher	Nachher
Aufgabe eingrenzen. Datei, Szenario und Testpraeferenzen nennen.	”Fuege Tests fuer uart.c hinzu"	"Schreibe einen hardware-nahen Test fuer drivers/uart.c, der RX-Buffer-Overflow prueft. Simuliere 256+ Bytes ohne Pause und stelle sicher, dass keine Speicherkorruption auftritt. Keine Mocks verwenden; vorhandenes HAL-Test-Harness nutzen.”
Auf Quellen zeigen. Embedder direkt zur passenden Informationsquelle lenken.	”Warum ist der SPI-Treiber so kompliziert?"	"Lies drivers/spi.c und die Git-Historie und fasse zusammen, wie sich der SPI-Treiber entwickelt hat. Erklaere, welche Hardware-Einschraenkungen das Design beeinflusst haben.”
Bestehende Muster referenzieren. Auf Muster in deiner Codebasis verweisen.	”Fuege einen I2C-Sensortreiber hinzu"	"Schau dir an, wie drivers/adc.c und drivers/uart.c init/config/read strukturieren. Folge dem gleichen Muster fuer drivers/i2c_temp_sensor.c. Uebernimm Naming, Fehlerbehandlung und ISR-Stil. Keine neuen Frameworks einfuehren.”
Symptom beschreiben. Symptom, vermutete Stelle und Erfolgsdefinition nennen.	”Behebe den LED-Bug"	"Die Status-LED hoert nach ~10 Minuten zufaellig auf zu blinken. Vermutlich haengt das mit dem Timer-ISR in src/timer.c zusammen. Reproduziere das mit einem Langzeittest, ergaenze Logging fuer verpasste Interrupts und behebe es so, dass die LED 30+ Minuten stabil mit 1 Hz blinkt.”

Unscharfe Prompts koennen trotzdem nuetzlich sein, wenn du explorativ vorgehst oder offen fuer Vorschlaege bist. Zum Beispiel kann “Welche Bugs sind in dieser Datei?” Dinge sichtbar machen, die dir sonst entgehen.

Kontext bereitstellen

Du kannst Embedder auf mehreren Wegen mit relevantem Kontext versorgen:

Dateien mit @ referenzieren, statt nur zu beschreiben, wo Code liegt.
Dokumentation in deinem Workspace referenzieren.
URLs angeben fuer Dokumentation und Online-Referenzen.

Umgebung einrichten

Ein wenig Setup vorab macht Embedder in jeder Sitzung deutlich effektiver. Wenn du Umgebung und Kontext sauber vorbereitest, arbeitet der Agent von Anfang an praeziser, konsistenter und effizienter.

Eine `EMBEDDER.md` schreiben

Fuehre /init aus, um eine Startversion von EMBEDDER.md basierend auf deiner Projektstruktur zu erzeugen.

Embedder liest zu Beginn jeder Sitzung automatisch eine EMBEDDER.md. Nutze diese Datei fuer wichtige Informationen wie haeufige Bash-Befehle, Coding-Konventionen und Workflow-Regeln. Das liefert persistenten Kontext, der sich nicht verlaesslich aus der Codebasis ableiten laesst. Der Befehl /init scannt dein Projekt auf Build-Systeme, Test-Frameworks und wiederkehrende Muster. Das ergibt eine starke Basis, die du anschliessend anpassen kannst. Es gibt keine strikte Struktur fuer EMBEDDER.md, aber sie sollte knapp und klar bleiben. Bevorzuge gut lesbare, konkrete Anweisungen statt langer Erklaertexte.

Embedder.md

# Code-Stil
- Halte dich an den C/C++-Stil des Projekts und halte Funktionen klein sowie auf eine Aufgabe fokussiert
- Verwende konsistentes Naming fuer Peripherie und Treiber wie uart_init, spi_write, adc_read
- Vermeide dynamische Allokation in Firmware. Bevorzuge statischen oder Stack-Speicher

# Workflow
- Baue die Firmware nach Aenderungen immer neu und behebe alle Compiler-Warnungen
- Flashe und verifiziere auf echter Hardware oder in der Simulation, bevor Aufgaben als fertig gelten
- Nutze zielgerichtete Unit- oder Hardware-Tests statt der gesamten Suite fuer schnellere Iteration

EMBEDDER.md wird zu Beginn jeder Sitzung geladen. Nimm deshalb nur Informationen auf, die breit fuer dein gesamtes Projekt gelten. Halte die Datei kurz und fokussiert. Frage dich pro Zeile: “Wenn das fehlen wuerde, macht Embedder dann wahrscheinlich Fehler?” Wenn nein, entferne es. Eine ueberladene EMBEDDER.md verwaessert wichtige Regeln und erhoeht die Chance, dass Embedder zentrale Hinweise uebersieht.

Einschliessen	Auslassen
Befehle, die Embedder nicht erraten kann	Alles, was Embedder bereits in Code oder Doku sieht
Projektspezifische Stilregeln	Standard-Konventionen der Programmiersprache
Testvorgaben und bevorzugte Test-Runner	Detaillierte API-Dokumentation (stattdessen verlinken)
Repo-Etikette	Informationen, die sich haeufig aendern
Dev-Umgebungsbesonderheiten (erforderliche Env Vars)	Datei-fuer-Datei-Beschreibungen der Codebasis
Haeufige Stolpersteine oder nicht offensichtliches Verhalten	Selbstverstaendliche Regeln wie “schreibe sauberen Code”

Wenn Embedder wiederholt etwas tut, das du explizit verboten hast, ist deine EMBEDDER.md vermutlich zu lang und die Regel geht unter. Wenn Fragen gestellt werden, die schon beantwortet sind, ist die Formulierung wahrscheinlich zu unklar. Behandle EMBEDDER.md wie Code: ueberpruefen, wenn Verhalten schlecht ist, regelmaessig kuerzen und Aenderungen testen, um zu sehen, ob sich das Verhalten wirklich verbessert. Du kannst die Regelbefolgung auch mit klaren Markern wie “IMPORTANT” oder “YOU MUST” staerken. Versioniere die Datei in Git, damit dein Team mitarbeiten kann. Kleine Verbesserungen summieren sich und machen die Datei ueber Zeit deutlich wertvoller.

Dokumentation bereitstellen

Fuehre /peripheral aus, um zu aendern, welche Peripherie-Dokumentation deinem Projekt zugeordnet ist.

Viele Plattformen und Peripheriekomponenten sind bereits vorindexiert. Wenn Embedder bei Board oder Peripherie danebenliegt, solltest du zusaetzliche Dokumentation ueber die Web-Konsole hochladen. Wenn du eigene Plattformen oder Peripherie hinzugefuegt hast, lade ausreichende und aktuelle Dokumentation hoch. Das geht ueber den Befehl /console und den Dokumenten-Upload im Projektbereich der Web-App.

CLI-Tools nutzen

Bitte Embedder, Tools wie gh, west oder openocd zu verwenden, wenn es mit externen Diensten interagiert.

Der effizienteste Weg fuer externe Dienste fuehrt ueber CLI-Tools. Wenn du GitHub nutzt, installiere gh. Embedder kann damit Issues erstellen, Pull Requests oeffnen und Kommentare lesen. Ohne gh kann Embedder zwar die GitHub-API nutzen, stoesst ohne Authentifizierung aber oft an Rate-Limits. Embedder lernt ausserdem gut neue CLI-Tools. Beispielprompt: Nutze 'cli-tool --help', um mehr ueber das Tool zu lernen, und loese dann A, B, C damit.

Fragen zur Codebasis stellen

Stelle Embedder die Fragen, die du auch einem Staff- oder Senior-Engineer stellen wuerdest.

Beim Onboarding in eine neue Codebasis kannst du Embedder sehr effektiv fuer Lernen und Exploration einsetzen. Beispiele:

Wie funktioniert Error-Logging hier?
Wie lese ich Daten vom in diesem Projekt verwendeten Sensor?
Was macht handle_sample() in Zeile 134 von foo.c?
Welche Edge-Cases behandelt TIMER_CTRL?
Warum ruft dieser Code in Zeile 173 foo1() statt foo2() auf?

Das beschleunigt das Onboarding deutlich und entlastet andere Engineers.

Sitzungen steuern

Konversationen sind persistent, und vorgenommenen Aenderungen koennen rueckgaengig gemacht werden.

Frueh und oft nachsteuern

Korrigiere Embedder frueh und oft.

Embedder funktioniert am besten mit enger Feedback-Schleife. Schnelle Korrekturen fuehren zu besseren Loesungen in kuerzerer Zeit.

Esc: Stoppt Embedder waehrend einer Aktion. Kontext bleibt erhalten, du kannst direkt umsteuern.
Ctrl + z (2x) oder /rewind: Oeffnet das Rewind-Menue und stellt einen frueheren Konversations- und Codestand wieder her.
Ctrl + z oder /undo: Macht die juengste Aenderung rueckgaengig.
/clear: Setzt Kontext zwischen unzusammenhaengenden Aufgaben zurueck. Lange Sitzungen mit irrelevanten Informationen verschlechtern die Leistung.

Wenn du Embedder in einer Sitzung mehr als zweimal beim selben Problem korrigieren musstest, ist der Kontext meist mit Fehlansaetzen verschmutzt. Fuehre /clear aus und starte neu mit einem praeziseren Prompt, der die Learnings enthaelt. Eine saubere Sitzung mit besserem Prompt ist fast immer besser als eine lange Sitzung voller Korrekturen.

Kontext aktiv begrenzen

Nutze /clear zwischen unzusammenhaengenden Aufgaben, um den Kontext zurueckzusetzen.

Embedder komprimiert bei langen Sitzungen den Verlauf automatisch und behaelt dabei wichtige Code- und Entscheidungsinformationen. In langen Sitzungen fuellt sich das Kontextfenster oft mit irrelevanten Details. Das reduziert Leistung und lenkt Embedder gelegentlich ab.

Nutze /clear regelmaessig zwischen Aufgaben, um das Kontextfenster komplett zurueckzusetzen
Wenn automatische Komprimierung greift, fasst Embedder wichtige Punkte wie Code-Muster, Dateizustaende und zentrale Entscheidungen zusammen
Fuer mehr Kontrolle kannst du /compress ausfuehren und den Zeitpunkt selbst bestimmen
Du kannst das Komprimierungsverhalten in EMBEDDER.md steuern, zum Beispiel mit: "When compressing, make sure to keep track of the full list of modified files"

Subagents fuer Untersuchungen nutzen

Delegiere Recherche mit "use subagents to investigate X". Sie arbeiten in einem separaten Kontext und halten deine Hauptkonversation fuer die Umsetzung sauber.

Subagents sind eines der effektivsten Mittel, um Sitzungen fokussiert zu halten. Bei Analyseaufgaben liest Embedder oft viele Dateien, was lange Sitzungen verlangsamen kann. Subagents erledigen das in einem separaten Kontextfenster und liefern dir eine Zusammenfassung zurueck.

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.

Der Subagent analysiert die Codebasis, liest relevante Dateien und liefert die Ergebnisse zurueck, ohne den Hauptkontext zu ueberladen.

Zu frueheren Checkpoints zurueckspringen

Jede Aktion von Embedder erzeugt einen Checkpoint. Du kannst Konversation und Code auf einen frueheren Stand zuruecksetzen.

Embedder erzeugt vor Aenderungen automatisch Checkpoints. Nutze /undo, um die letzte Aenderung rueckgaengig zu machen, oder /rewind, um das Checkpoint-Menue zu oeffnen. Statt jeden Schritt im Voraus auszuplanen, kannst du Embedder etwas ausprobieren lassen und bei Bedarf zurueckspulen, um einen anderen Ansatz zu testen.

Checkpoints verfolgen nur Aenderungen, die von Embedder gemacht wurden.

Konversationen fortsetzen

Nutze /history, um eine fruehere Konversation wieder aufzunehmen.

Embedder speichert Konversationen lokal. Wenn eine Aufgabe mehrere Sitzungen umfasst (Feature starten, unterbrechen, am naechsten Tag fortsetzen), musst du den Kontext nicht neu erklaeren.

Typische Fallstricke vermeiden

Diese Hinweise helfen, haeufige Fehler zu vermeiden:

Fuehre /clear zwischen unzusammenhaengenden Aufgaben aus. Sonst fuellt sich dein Kontextfenster mit irrelevanten Informationen.
Fuehre /clear nach Fehlschlaegen aus. Wenn Embedder etwas mehrfach falsch macht, nach zwei bis drei Korrekturen mit /clear neu starten und einen besseren Prompt formulieren.
Fuege zusaetzliche Dokumentation hinzu. Wenn Embedder deine Hardware missversteht, lade weitere oder aktualisierte Dokumente hoch.
Kuerze EMBEDDER.md regelmaessig. Ist die Datei zu lang, gehen wichtige Regeln im Rauschen unter.
Grenze Aufgaben ein und nutze Subagents. Unscharfe “explore”-Auftraege koennen den Kontext schnell fuellen. Grenze ein oder delegiere.

Kernkonzepte

Produktupdates

Hilf Embedder, die eigene Arbeit zu verifizieren

Erst analysieren und planen, dann coden

Gib in Prompts praezisen Kontext

Kontext bereitstellen

Umgebung einrichten

Eine `EMBEDDER.md` schreiben

Dokumentation bereitstellen

CLI-Tools nutzen

Fragen zur Codebasis stellen

Sitzungen steuern

Frueh und oft nachsteuern

Kontext aktiv begrenzen

Subagents fuer Untersuchungen nutzen

Zu frueheren Checkpoints zurueckspringen

Konversationen fortsetzen

Typische Fallstricke vermeiden

​Hilf Embedder, die eigene Arbeit zu verifizieren

​Erst analysieren und planen, dann coden

​Gib in Prompts praezisen Kontext

​Kontext bereitstellen

​Umgebung einrichten

​Eine EMBEDDER.md schreiben

​Dokumentation bereitstellen

​CLI-Tools nutzen

​Fragen zur Codebasis stellen

​Sitzungen steuern

​Frueh und oft nachsteuern

​Kontext aktiv begrenzen

​Subagents fuer Untersuchungen nutzen

​Zu frueheren Checkpoints zurueckspringen

​Konversationen fortsetzen

​Typische Fallstricke vermeiden

Hilf Embedder, die eigene Arbeit zu verifizieren

Erst analysieren und planen, dann coden

Gib in Prompts praezisen Kontext

Kontext bereitstellen

Umgebung einrichten

Eine `EMBEDDER.md` schreiben

Dokumentation bereitstellen

CLI-Tools nutzen

Fragen zur Codebasis stellen

Sitzungen steuern

Frueh und oft nachsteuern

Kontext aktiv begrenzen

Subagents fuer Untersuchungen nutzen

Zu frueheren Checkpoints zurueckspringen

Konversationen fortsetzen

Typische Fallstricke vermeiden