Buenas practicas

Esta página cubre patrones probados para obtener los mejores resultados de Embedder, recopilados de ingenieros que lo utilizan en una amplia gama de entornos. El factor más importante es la duración de la sesión. A medida que una sesión se alarga, Embedder acumula el historial de conversaciones, el contenido de los archivos y las salidas de los comandos. Cuando hay demasiado contexto acumulado, Embedder puede perder la pista de instrucciones anteriores, cometer más errores o comportarse de manera inconsistente. Mantener las sesiones enfocadas es la forma más efectiva de mantener la precisión. Utilice esta guía como punto de partida. Presta atención a lo que funciona y a lo que no.

Ayude a Embedder a verificar su trabajo

Incluya pruebas o resultados esperados para que Embedder pueda comprobarlo por sí mismo.

Embedder funciona mejor cuando puede verificar su propio trabajo. Sin criterios claros de éxito, se pueden generar soluciones que parecen correctas pero que fracasan en la práctica. En esos casos, usted se convierte en la única fuente de retroalimentación y cada error requiere revisión e intervención manual.

Estrategia	Antes	Después
Proporcione criterios de verificación	”implementar una función que lea un sensor de temperatura"	"implementar read_temperature(). Cuando el sensor devuelve el valor bruto 0x0190, la función debe devolver 25,0°C. Incluya pruebas unitarias con lecturas de I²C simuladas y verifique las salidas para [0x0000 -> 0,0°C, 0x0190 -> 25,0°C, 0x0320 -> 50,0°C]. Las pruebas deben pasar.”
Abordar las causas fundamentales, no los síntomas	”la compilación está fallando"	"la compilación falla con este error: [pegar error]. corríjalo y verifique que la compilación sea exitosa. Aborde la causa raíz, no suprima el error”

Su verificación puede adoptar muchas formas, como un conjunto de pruebas, un linter o un comando Bash que valida la salida. Invierta tiempo para que estas comprobaciones sean confiables y exhaustivas, ya que una verificación sólida permite resultados consistentes y confiables.

Explora y planifica, luego codifica

Separar la investigación y la planificación de la implementación para mejorar los resultados.

Permitir que Embedder salte directamente a la codificación puede producir código que resuelva el problema equivocado. Utilice el Modo Planificación para separar la investigación y la planificación de la ejecución. El flujo de trabajo recomendado tiene cuatro fases:

Explore

Ingrese al modo de planificación. Embedder lee archivos y responde preguntas sin realizar cambios.

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.

Plan

Pídale a Embedder que cree un plan de implementación detallado.

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.

Cuando Embedder termina de crear un plan, puede aprobarlo y continuar con la ejecución o darle comentarios sobre qué cambiar. Puede editar manualmente el plan yendo a .embedder/plans en su directorio de proyectos.

Implement

Vuelva al modo Act y deje que Embedder codifique, verificando su 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.

Commit

Pídale a Embedder que se comprometa con un mensaje descriptivo y cree un PR.

Embedder (Act Mode)

Commit with a descriptive message and open a PR.

El modo Planificar puede mejorar los resultados, pero no siempre es necesario y puede ralentizar un trabajo sencillo. Cuando la tarea es sencilla y de alcance limitado, como corregir un pequeño error, agregar una declaración de depuración o realizar un cambio de nombre menor, suele ser más rápido ejecutar el cambio inmediatamente. Un paso de planificación dedicado es más efectivo para situaciones más complejas, especialmente cuando la solución no está clara, la actualización afecta varias partes del código base o está trabajando con código desconocido.

Proporcionar contexto específico en las indicaciones

Cuanto más precisas sean tus instrucciones, menos correcciones necesitarás.

Embedder a menudo puede inferir su intención, pero no tiene conocimiento implícito de sus objetivos o suposiciones. Sea explícito y preciso en sus instrucciones. Haga referencia a los archivos exactos que desea modificar, indique las restricciones o requisitos y enlace a ejemplos o patrones relevantes a seguir.

Estrategia	Antes	Después
Alcance de la tarea. Especifique qué archivo, qué escenario y preferencias de prueba.	”Agregar pruebas para uart.c"	"Escriba una prueba a nivel de hardware para drivers/uart.c que verifique el manejo del desbordamiento del búfer RX. Simule más de 256 bytes que llegan uno tras otro y afirme que no hay daños en la memoria. Evite las simulaciones; use el arnés de prueba HAL existente.”
Señale las fuentes. Dirija a Embedder a la fuente que puede responder una pregunta.	”¿Por qué el controlador SPI es tan complicado?"	"Lea drivers/spi.c y su historial de git y resuma cómo ha evolucionado el controlador SPI. Explique las limitaciones de hardware que influyeron en el diseño.”
Haga referencia a patrones existentes. Apunte Embedder a patrones en su base de código.	”Agregar un controlador de sensor I2C"	"Observe cómo drivers/adc.c y drivers/uart.c estructuran las funciones init/config/read. Siga el mismo patrón para implementar drivers/i2c_temp_sensor.c. Haga coincidir los nombres, el manejo de errores y el estilo ISR. No introduzca nuevos marcos.”
Describa el síntoma. Proporcione el síntoma, la ubicación probable y cómo se ve “arreglado”.	”Solucionar el error del LED"	"El LED de estado deja de parpadear aleatoriamente después de ~10 minutos. Probablemente esté relacionado con el temporizador ISR en src/timer.c. Reproduzca con un bucle de larga duración, agregue el registro para confirmar las interrupciones perdidas y luego arregle para que el LED mantenga un parpadeo estable de 1 Hz durante más de 30 minutos.”

Las indicaciones vagas pueden resultar muy útiles cuando estás explorando o estás abierto a sugerencias. Preguntar “¿Qué errores hay en este archivo?” puede sacar a la luz cosas que de otro modo no habrías encontrado.

Proporcionar contexto

Puede proporcionar datos enriquecidos a Embedder de varias maneras:

Archivos de referencia con @ en lugar de describir dónde reside el código.
Documentación de referencia en el espacio de trabajo de tu proyecto.
Proporcione URL para documentación y referencias en línea.

Configure su entorno

Una pequeña cantidad de configuración inicial puede hacer que Embedder sea mucho más efectivo en cada sesión. Tomarse el tiempo para configurar su entorno y proporcionar el contexto adecuado ayuda al agente a trabajar de manera más precisa, consistente y eficiente desde el principio.

Escribir un archivo `EMBEDDER.md`

Ejecute /init para generar un archivo EMBEDDER.md inicial basado en la estructura de su proyecto actual.

Embedder lee automáticamente un archivo EMBEDDER.md al comienzo de cada sesión. Utilice este archivo para definir detalles importantes, como comandos bash comunes, convenciones de codificación y pautas de flujo de trabajo. Esto proporciona un contexto persistente que no se puede inferir de manera confiable únicamente a partir del código base. El comando /init escanea su proyecto para identificar sistemas de compilación, marcos de prueba y patrones recurrentes. Esto crea un sólido punto de partida que luego puedes personalizar y perfeccionar. No se requiere una estructura estricta para EMBEDDER.md, pero debe ser concisa y fácil de entender. Trate de obtener instrucciones claras y legibles por humanos en lugar de documentación extensa.

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 se carga al inicio de cada sesión, por lo que solo incluye información que se aplique ampliamente a todo el proyecto. Mantenga el archivo breve y enfocado. Para cada línea, pregúntese: “Si esto faltara, ¿Embedder cometería errores?” Si la respuesta es no, elimínelo. Un EMBEDDER.md demasiado grande o desordenado diluye la guía importante y hace más probable que Embedder pase por alto sus instrucciones reales.

Incluir	Excluir
Comandos Embedder no puede adivinar	Todo lo que Embedder pueda ver en código o documentos
Reglas de estilo de código únicas	Convenciones de lenguaje estándar
Instrucciones de prueba y corredores de prueba preferidos	Documentación API detallada (en su lugar, enlace a documentos)
Etiqueta del repositorio	Información que cambia con frecuencia
Peculiaridades del entorno de desarrollador (variaciones de entorno requeridas)	Descripciones archivo por archivo del código base
Errores comunes o comportamientos no obvios	Prácticas evidentes como “escribir código limpio”

Si Embedder sigue haciendo algo que usted ha prohibido explícitamente, su EMBEDDER.md probablemente sea demasiado largo y la regla se esté enterrando. Si hace preguntas que ya están respondidas en el expediente, es probable que la redacción sea ambigua o poco clara. Trate EMBEDDER.md como código: revíselo cuando el comportamiento salga mal, elimine periódicamente las líneas innecesarias o redundantes y pruebe los cambios para confirmar que el comportamiento de Embedder realmente cambia. También puede mejorar la adherencia agregando un énfasis claro como “IMPORTANTE” o “DEBE”. Verifique el archivo en git para que su equipo pueda contribuir, ya que las pequeñas mejoras se acumulan con el tiempo y hacen que el documento sea cada vez más valioso.

Proporcionar documentación

Ejecute /peripheral para cambiar qué documentación periférica está asociada con su proyecto

Muchas plataformas y periféricos tienen documentación preindexada. Si descubre que Embedder está haciendo cosas mal con respecto a su placa o periféricos, considere cargar documentación complementaria a través de la consola web. Si ha agregado su propia plataforma o periférico, asegúrese de cargar documentación suficiente y actualizada. Puede agregar más documentación para su plataforma o periféricos usando el comando /console y cargando más documentación en la sección de proyectos de la aplicación web.

Utilice herramientas CLI

Dígale a Embedder que utilice herramientas como gh, west o openocd cuando interactúe con servicios externos.

La forma más eficaz de interactuar con servicios externos es mediante herramientas CLI. Si usa GitHub, instale la CLI gh. Embedder sabe cómo usarlo para crear problemas, abrir solicitudes de extracción y leer comentarios. Sin gh, Embedder aún puede usar la API de GitHub, pero las solicitudes no autenticadas a menudo alcanzan límites de velocidad. Embedder también es excelente para aprender herramientas CLI que aún no conoce. Pruebe indicaciones como Use 'cli-tool --help' to learn about more about the cli tool, then use it to solve A, B, C.

Haga preguntas sobre su código base

Haga a Embedder preguntas que le haría a un empleado o a un ingeniero senior.

Al incorporarse a una nueva base de código, utilice Embedder para aprender y explorar. Puede hacerle a Embedder preguntas que le haría a otro ingeniero:

¿Cómo funciona el registro de errores?
¿Cómo leo los datos del sensor utilizado en este proyecto?
¿Qué hace el handle_sample() en la línea 134 del foo.c?
¿Qué casos extremos aborda el artículo TIMER_CTRL?
¿Por qué este código llama foo1() en lugar de foo2() en la línea 173?

Esto puede acelerar significativamente la incorporación y reducir la carga de otros ingenieros.

Gestiona tu sesión

Las conversaciones son persistentes y los cambios realizados durante ellas pueden revertirse.

Corrija el rumbo temprano y con frecuencia

Corrija Embedder temprano y con frecuencia.

Embedder funciona mejor con un circuito de retroalimentación estrecho. La corrección de Embedder produce rápidamente mejores soluciones a un ritmo más rápido.

Esc: Detenga el Embedder en mitad de la acción con la tecla Esc. El contexto se conserva, por lo que puedes redirigir.
Ctrl + z (2x) o /rewind: presione Ctrl + z (2x) o ejecute /rewind para abrir el menú de rebobinado y restaurar la conversación anterior y el estado del código.
Ctrl + z or /undo: Presione Ctrl + z o ejecute /undo para que Embedder revierta su cambio más reciente.
/clear: Restablecer contexto entre tareas no relacionadas. Sesiones largas con contexto irrelevante pueden reducir el rendimiento.

Si ha corregido a Embedder más de dos veces sobre el mismo problema en una sesión, el contexto estará lleno de enfoques fallidos. Ejecute /clear y comience de nuevo con un mensaje más específico que incorpore lo que aprendió. Una sesión limpia con mejores indicaciones casi siempre supera a una sesión larga con correcciones acumuladas.

Gestionar el contexto de forma agresiva

Ejecute /clear entre tareas no relacionadas para restablecer el contexto.

Embedder comprime automáticamente el historial de conversaciones durante sesiones largas, preservando el código y las decisiones importantes y liberando espacio. Durante sesiones más largas, la ventana contextual de Embedder puede llenarse de información irrelevante. Esto reduce el rendimiento y, en ocasiones, distrae a Embedder.

Utilice /clear con frecuencia entre tareas para restablecer la ventana de contexto por completo
Cuando se activa la compresión automática, Embedder resume lo más importante, incluidos patrones de código, estados de archivos y decisiones clave.
Para tener más control, puede ejecutar /compress para elegir cuándo se produce la compresión.
Personalice el comportamiento de compresión en EMBEDDER.md con instrucciones como "When compressing, make sure to keep track of the full list of modified files" para asegurarse de que cualquier contexto importante sobreviva al resumen.

Utilice subagentes para la investigación

Delegar la investigación con "use subagents to investigate X". Exploran en un contexto separado, manteniendo limpia la conversación principal para su implementación.

Los subagentes son una de las herramientas más efectivas para mantener enfocadas las sesiones. Cuando Embedder investiga una base de código, lee muchos archivos, lo que puede ralentizar el rendimiento en sesiones largas. Los subagentes completan la tarea en una ventana contextual separada e informan resúmenes:

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.

El subagente explora el código base, lee archivos relevantes e informa los hallazgos, todo sin saturar la conversación principal.

Rebobinar a puntos de control anteriores

Cada acción que realiza Embedder crea un punto de control. Puede restaurar la conversación y el código a un estado anterior.

Embedder controla automáticamente los puntos antes de los cambios. Ejecute /undo para deshacer el último cambio o /rewind para abrir el menú de puntos de control. En lugar de planificar cuidadosamente todos tus movimientos, puedes decirle a Embedder que pruebe algo y, si no funciona, retroceder e intentarlo de otra manera.

Los puntos de control sólo rastrearán los cambios realizados por Embedder.

Reanudar conversaciones

Ejecute /history para retomar una conversación donde la dejó.

Embedder guarda una copia de las conversaciones localmente. Cuando una tarea abarca varias sesiones (inicia una función, lo interrumpen, regresa al día siguiente), no es necesario volver a explicar el contexto.

Evitar trampas

Estos son algunos consejos útiles para evitar errores comunes.

Ejecutar /clear entre tareas no relacionadas. De lo contrario, puedes inflar tu ventana contextual con mucha información irrelevante.
Ejecutar /clear después de fallas. Si Embedder hace algo mal, después de dos o tres correcciones fallidas, ejecute /clear y escriba un mensaje inicial mejor incorporando lo que aprendió, ya que el contexto se verá contaminado con enfoques fallidos.
Agregue documentación adicional. Si Embedder parece no entender aspectos de su hardware. Considere cargar documentación adicional o reemplazar la actual.
Podar EMBEDDER.md a menudo. Si EMBEDDER.md es demasiado largo, Embedder ignorará gran parte ya que las reglas importantes se perderán en el ruido. Cuantas menos directrices haya en EMBEDDER.md, más centrado estará el Embedder en mantener esas directrices.
Amplia el alcance de las tareas y utiliza subagentes. Si le pides a Embedder que “explore” algo y no lo analizas, Embedder puede terminar llenando su contexto rápidamente. Alcance las tareas o utilice subagentes para preservar el contexto.

Conceptos clave

Novedades del producto

Ayude a Embedder a verificar su trabajo

Explora y planifica, luego codifica

Proporcionar contexto específico en las indicaciones

Proporcionar contexto

Configure su entorno

Escribir un archivo `EMBEDDER.md`

Proporcionar documentación

Utilice herramientas CLI

Haga preguntas sobre su código base

Gestiona tu sesión

Corrija el rumbo temprano y con frecuencia

Gestionar el contexto de forma agresiva

Utilice subagentes para la investigación

Rebobinar a puntos de control anteriores

Reanudar conversaciones

Evitar trampas

​Ayude a Embedder a verificar su trabajo

​Explora y planifica, luego codifica

​Proporcionar contexto específico en las indicaciones

​Proporcionar contexto

​Configure su entorno

​Escribir un archivo EMBEDDER.md

​Proporcionar documentación

​Utilice herramientas CLI

​Haga preguntas sobre su código base

​Gestiona tu sesión

​Corrija el rumbo temprano y con frecuencia

​Gestionar el contexto de forma agresiva

​Utilice subagentes para la investigación

​Rebobinar a puntos de control anteriores

​Reanudar conversaciones

​Evitar trampas

Ayude a Embedder a verificar su trabajo

Explora y planifica, luego codifica

Proporcionar contexto específico en las indicaciones

Proporcionar contexto

Configure su entorno

Escribir un archivo `EMBEDDER.md`

Proporcionar documentación

Utilice herramientas CLI

Haga preguntas sobre su código base

Gestiona tu sesión

Corrija el rumbo temprano y con frecuencia

Gestionar el contexto de forma agresiva

Utilice subagentes para la investigación

Rebobinar a puntos de control anteriores

Reanudar conversaciones

Evitar trampas