Taking Over an Unfamiliar Embedded Project: Start Here with Codex¶
The first challenge in a long-lived embedded project is rarely writing code. It is learning how the system starts, where its responsibilities live, and how data moves across it. AI is useful for creating that map—before it changes anything.
0. Establish a safe boundary¶
Make sure the project is in Git and create an analysis branch:
The first task should be read-only: inspect directories, source, build files, and history; do not edit, delete, flash, or reboot. That protects a mature project and makes later git diff reviews meaningful.
1. Ask for a map, not a file-by-file tour¶
Give the agent a bounded request:
Do not change code. Identify the major directories, business modules, drivers, third-party dependencies, and build entry points. Focus on the main flow rather than every file.
The useful output is a map: responsibilities, build targets, configuration files, and open questions that guide the next reading pass.
2. Follow the real main flow¶
main() often only initializes hardware and starts tasks. The actual work may sit in RTOS tasks, Linux threads, event loops, callbacks, or state machines. Ask for initialization order, task or thread creation, callback registration, and the hand-off to the primary workflow.
For FreeRTOS, list task entry points, roles, and queue/semaphore/event-group relationships. For Linux, include services, threads, and IPC boundaries.
3. Trace one concrete entry point¶
For a UART packet or unknown callback, use a precise question:
Starting from
uart_rx_callback(), trace the real call order. Show the modules involved and where protocol parsing and business handling finally occur.
Apply the same idea to messages: who sends them, who receives them, and what happens between. Treat the result as a guide and verify it against source.
4. Analyse first; change the smallest possible surface¶
Code is not the whole device: timing, power, and hardware can be the root cause. Ask first for affected modules, hypotheses, evidence to collect, and useful logging points. Once the scope is confirmed, request only the relevant change and preserve the existing style.
Afterward, inspect git diff, build the relevant target, and test on real hardware. AI speeds up understanding; it does not replace field evidence.