emb-agent: An AI Workflow Layer for Embedded Development, Keeping Hardware Truths in the Codebase Permanently

emb-agent is an AI workflow framework designed specifically for embedded firmware projects, aiming to solve the inefficiency problem of AI programming assistants in embedded development caused by deep hardware coupling. Its core idea is keeping hardware truths in the codebase permanently—by using structured configuration files and约定 directories, key hardware information such as MCU models and pin assignments is explicitly stored in version control, helping AI assistants understand hardware constraints and enabling a hardware-first collaborative development model. This article will introduce it from aspects of background, design, workflow, value, etc.

With the breakthrough of large models in the field of code generation, AI programming assistants have become important tools for developers, but their performance is greatly reduced when applied to embedded firmware development. Embedded projects are deeply coupled with hardware: specific MCU models, pin assignments, peripheral configurations, timing constraints, register definitions, and other "hardware truths" determine the feasibility of code, but are difficult to pass to AI through regular code context, leading to AI generating code that seems reasonable but cannot run. Developers fall into an inefficient cycle of repeated corrections. emb-agent is born to solve this dilemma.

The design of emb-agent revolves around five principles:

1. Hardware truth versioning: Record hardware information in structured .hw.yaml files (including MCU model, package, signal mapping, etc.) to ensure traceability and team consistency;
2. Shortest default path: The core loop is concise (declare hardware → get suggestions → execute), and complex operations are triggered on demand;
3. Document-to-truth conversion: Extract information from PDF manuals or schematics through the ingest doc/schematic command, and incorporate it into project truth after manual review;
4. Chip support runtime: Chip logic is abstracted into independent support packages, which the community can contribute to, keeping the core lightweight;
5. Verification-aware closed loop: Tasks need review and verify to ensure code meets hardware constraints.

In terms of project structure, emb-agent creates an .emb-agent directory in the codebase, containing files such as hw.yaml (hardware definition), req.yaml (requirement constraints), project.json (default preferences), tasks/ (task lifecycle), etc., making hardware information part of version control and facilitating AI to quickly obtain context.

emb-agent defines multiple workflows:

• Quick start for known hardware: Use declare hardware to specify the chip model, automatically pull the support package, and use next to get steps;
• Unknown hardware exploration: req.yaml records target constraints, and next gets guidance (such as extracting manual information);
• Document import process: Use ingest doc/schematic to parse PDF/schematic → incorporate into truth after manual review;
• Task execution loop: Isolate task workspaces to manage parallel streams and support full lifecycle operations.

In terms of integration, emb-agent adapts to AI tools such as Codex, Claude Code, and Cursor. It achieves collaboration through AGENTS.md (behavior guidelines), Skills/Commands (custom skills), and Hooks (inject context at session startup) to maintain project configuration consistency.

emb-agent is particularly suitable for:

• Legacy MCU projects: Help AI understand hardware constraints to safely refactor or extend register-intensive code;
• Multi-platform firmware development: Structured hardware definitions provide a clear migration path;
• Hardware-software co-design: Track the impact of hardware iterations on software;
• Knowledge inheritance: Precipitate the hardware knowledge of senior engineers and lower the threshold for new members.

Its value lies not only in improving the accuracy of AI code but also in promoting the explicit, versioned, and shareable management of hardware knowledge, thereby improving team collaboration and knowledge management.

Current limitations:

• Chip support package coverage depends on community contributions, so support for niche/new MCUs may be insufficient;
• Document import depends on external tools, and the processing ability for complex PDFs or scanned versions is limited;
• The verification loop depends on the maturity of the project's test infrastructure.

Future directions:

• Enhance the chip support package ecosystem;
• More intelligent document parsing capabilities;
• Deep integration with hardware simulators;
• Adapt to more AI host environments.

emb-agent is an attempt to deepen AI-assisted development in vertical domains. It recognizes the limitations of general AI tools in embedded scenarios and bridges the gap through structured project infrastructure. It not only improves the accuracy of AI code generation but also promotes the explicit management of hardware knowledge. This idea is worth learning from by other professional fields: instead of waiting for general AI to become smarter, build domain adaptation layers to allow AI to better utilize domain knowledge.