Skip to content

Best practices

The single biggest performance lever in AI-assisted firmware development is session focus. Accuracy degrades as a conversation accumulates file reads, tool outputs, and aborted attempts.

1. Attach your datasheets

Datasheets are the single biggest accuracy multiplier. Attach the datasheet for every chip your project drives. Ask Hydron to cross-reference a driver against its datasheet and it can produce a complete register coverage table in one pass.

  • Attach errata sheets separately. They often contradict the main datasheet on edge cases.
  • Re-attach when the vendor publishes a new revision. Datasources do not auto-update.
  • Confirm your project is selected before prompting. Datasources are scoped to the active project.
  • Use trigger keywords. Hydron routes to datasource lookup when it sees query, refer to, look up, or the project name. Without them it may answer from training data instead of your attached documents.

2. Use mentions to anchor context

Explicit @-mentions give you tight control over what the agent sees.

Trust the discovery tools for sweeping architectural tasks. "Find everywhere we use blocking delays in ISRs" works better as a plain question than as a list of manually tagged headers.

See Context and mentions.

3. Help Hydron verify its work

Pair every implementation prompt with a concrete check it can run. When success criteria are vague, Hydron produces code that compiles and looks plausible but silently misses behaviour. Given a command, it iterates against the compiler instead of waiting for your review.

Before

Add SPI register read support to the DRV8316 driver

After

In src/drivers/drv8316/drv8316.cpp, add a readRegister(addr) that returns
the 16-bit SPI frame. Verify against the DRV8316 datasource: writing 0x03
(Control_1) with REG_LOCK=0x3 then reading back should yield REG_LOCK=0x3.
Add a sketch under examples/drivers/drv8316/ that prints all status
registers and exits. Build with
arduino-cli compile --fqbn arduino:samd:nano_33_iot.

Always name the target board. Without it, Hydron may pick a default architecture and you will miss platform-specific breakage such as ARM against AVR differences.

4. Prompt like a code review comment

The more your prompt resembles a strict code review comment, the better. Hydron infers intent well, but inference compounds error.

  • Scope by file. "In src/drivers/drv8316/drv8316.cpp..."
  • Trigger datasource lookup. Use "query documents" or name the project explicitly.
  • Reference existing patterns. "Look at src/drivers/tmc6200/ for layout. Scaffold src/drivers/tmc6300/ matching that file split. No new abstractions."
  • Describe the symptom. "On STM32G4, drv8316.readStatus() returns 0xFFFF after ~30s of operation. Likely SPI clock or CS timing. Reproduce with the standalone example, instrument the CS pin, fix root cause."

5. Manage your session

Course-correct early. Esc interrupts generation but preserves context. The cost of letting Hydron finish a wrong path is that its flawed reasoning stays in the context window and influences the next attempt.

Start fresh when stuck. More than two corrections on the same point means /new beats continuing.

One session, one scope. Do not continue a session across unrelated tasks.

Use Ask mode for exploration. It returns a summary and keeps your main session clean.

6. Explore, plan, then code

For anything spanning more than one file, ask Hydron to plan before it writes. Letting it jump straight to code on a multi-file change often produces a partial implementation in one file and a stub in the next.

See Agent modes for the three-step sequence.

Skip the plan step for trivial work. Planning short tasks adds latency without changing the outcome.

7. Review everything

Generated outputs are produced by AI and may contain errors, omissions, or inaccuracies. They are assistive, not a substitute for engineering judgment. All outputs must be independently reviewed, tested, and validated by qualified engineers before deployment.

This matters more when hardware is in the loop.