# Source Maintenance Reader

> 理解、解释、排查、修改和移植已有 MCU/嵌入式源码。适用于接手老固件项目、回答启动流程、调用链、中断、条件编译、板卡变体、寄存器配置问题，或需要新增功能、修改参数、跨芯片移植功能时。

- Skill: `tsaiguohua/source-maintenance-reader` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tsaiguohua/source-maintenance-reader`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tsaiguohua/source-maintenance-reader/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tsaiguohua (https://skillmd.com/u/tsaiguohua)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tsaiguohua/source-maintenance-reader

---


# 源码理解与维护

老项目先理解，再修改。不要一上来重构。

## 工作流

1. 识别项目类型和构建系统  
   判断 Keil、IAR、Make、CMake、厂商 IDE、RTOS、裸机或嵌入式 Linux。找到工程文件、启动文件、链接脚本、配置、生成代码和板卡变体。

2. 梳理启动和运行路径  
   看 Reset Handler、系统时钟、HAL/厂商初始化、板级初始化、调度器或主循环、中断向量表、已启用中断、tick 和任务分发。

3. 梳理模块职责  
   识别 driver、bsp、component、app、workflow、协议、存储、UI。发现跨层问题可以记录，但不要无关重构。

4. 追踪目标行为  
   找入口函数、回调、ISR、flag、缓冲区、状态变量、宏和条件编译。注意板卡/芯片变体会改变行为。

5. 最小修改  
   保持现有风格和命名。能加日志、测试或保护就加。窄问题不要做大架构调整。

6. 验证  
   能编译就编译；需要板端验证时说明步骤；更新调试记录或决策记录。

## 回答源码问题的格式

回答“这段代码怎么工作”时，包含：

- 简短结论。
- 涉及文件和函数。
- 调用链或状态转移。
- 关键宏和配置。
- 哪些是源码事实，哪些是推断。
- 风险和未知项。

## 老项目风险

- 一个代码库可能通过宏兼容多个板子和芯片。
- 厂商生成文件可能被 IDE 覆盖。
- 直接寄存器操作可能依赖未写明的顺序或延时。
- 全局 flag 和 ISR 交互可能隐藏竞态。
- 奇怪的 `delay` 可能是硬件稳定时间，不一定是随手乱写。

## 排错规则

- 先读原始报错、日志和现象，再提修复。
- 崩溃/卡死重点看栈、ISR、看门狗、时钟、内存越界和阻塞调用。
- 通信问题重点看波特率/时钟、引脚复用、上下拉、缓冲处理、超时和协议帧。
- 显示/UI 问题要区分代码逻辑正确和产品/布局判断错误。

## 移植规则

- 先分离可移植逻辑和芯片相关 driver/BSP。
- 为目标板重新生成硬件接口表。
- 重新验证时序、内存、栈、Flash/RAM、外设可用性。
- 不要假设不同 MCU 家族的引脚复用、DMA 通道、中断向量和时钟树相同。