企业官网建设流程全解析

1. 嵌入式C代码风格为什么值得单独折腾

做嵌入式开发的人大多有过这种体验：接手一个前人留下的工程，打开某个.c文件，缩进一会儿是Tab一会儿是空格，大括号有的换行有的不换行，变量命名从ucRecvBuf到recv_buf再到a都有，宏定义散落在文件各处。你想改，又怕改出问题；不改，每次读代码都像在破译密码。更麻烦的是团队协作——三个人写出来的代码风格能凑出五种花样，代码评审的时候一半时间在争论“这个括号该不该换行”，而不是在讨论逻辑对不对。

这就是嵌入式C代码风格检查存在的意义。它不是学术洁癖，而是实打实的工程效率问题。嵌入式项目和普通应用软件有个很大的区别：代码往往要活很久。一个工业控制板子的固件可能跑十年以上，中间经历好几拨人维护。如果一开始没有统一的风格约束，后面每换一次人，代码的可读性就下降一截，最终变成谁都不敢动的“祖传代码”。

传统做法是靠人肉评审加一份Word版的编码规范，但人总有疏忽的时候，评审也容易流于形式。更靠谱的方式是把风格检查自动化，让工具在写代码的时候就提醒你，而不是等到评审会上才被发现。过去这类工作一般交给clang-format、uncrustify、cppcheck这类工具，配置起来不算复杂，但和编辑器的联动总有点割裂感——你得单独跑命令，或者配一堆插件。

现在有了Cursor这类AI编辑器，事情变得不太一样了。Cursor本身是基于VS Code深度定制的，它最大的特点是内置了AI能力，同时保留了VS Code的插件生态。更关键的是它有一套Rules（规则）机制，你可以把项目的编码规范写成规则文件，Cursor会在你写代码的时候自动参考这些规则，相当于给AI助手和编辑器同时装上了一本“项目规范手册”。

这篇内容就是围绕“用Cursor规则搞定嵌入式C代码风格检查”这件事展开的。我会结合一个叫Pikachu的嵌入式项目实战，把规则怎么写、怎么配、怎么和现有工具链配合、踩过哪些坑，都掰开揉碎讲清楚。不管你是刚接触嵌入式C的新手，还是带团队的老手，这套方法都能直接抄作业。

2. 整体思路：为什么选Cursor Rules而不是传统方案

2.1 传统代码风格检查方案的局限

在讲Cursor方案之前，先说说传统方案为什么不够用。常见的做法有这么几种：

第一种是纯人工评审。团队定一份编码规范文档，评审的时候对照着看。问题是人眼容易疲劳，而且规范文档往往写得很抽象，比如“变量命名要有意义”，什么叫有意义？每个人理解不一样。

第二种是独立跑格式化工具。比如用clang-format配一个.clang-format文件，提交代码前手动跑一遍或者挂个git hook。这个方案本身没问题，但它和写代码的过程是分离的。你写的时候不知道格式对不对，跑完工具才发现被改了一堆，有时候工具还会把某些精心排版的宏定义搞乱。

第三种是编辑器插件。比如VS Code里装C/C++插件加各种linter，能实时提示。但配置分散，每个插件管一摊，而且很多linter对嵌入式特有的写法支持一般，比如寄存器操作、位域、volatile指针这些。

这些方案共同的短板是：规范和写代码的人是割裂的。规范在文档里、在配置文件里、在插件设置里，就是不在你写代码的那个光标旁边。

2.2 Cursor Rules的核心机制

Cursor的Rules机制本质上是一个放在项目里的规则文件，通常叫.cursorrules或者放在.cursor/rules目录下。这个文件用自然语言写，描述项目的技术栈、编码规范、目录结构、常用命令等等。Cursor在生成代码、补全、回答问题的时候，会把这个文件的内容作为上下文参考。

这意味着什么？意味着你可以用中文写一段“本项目的C代码缩进用4个空格，函数名用下划线分隔的小写字母，宏定义全大写，禁止使用制表符”，然后Cursor在帮你写代码或者补全的时候，就会尽量遵守这些规则。它不只是格式化，而是在生成阶段就按规范来。

对于嵌入式C项目，这个机制特别合适，因为嵌入式C有很多约定俗成但工具不好检查的规范。比如：

• 中断服务函数名要以_IRQHandler结尾
• 寄存器操作要用特定的宏封装
• 全局变量要加g_前缀，静态变量加s_前缀
• 禁止在中断里调用阻塞函数

这些规则用传统linter写起来很费劲，但用自然语言描述就很直接。

2.3 Pikachu项目的背景设定

为了把这件事讲具体，我拿一个虚构但很典型的嵌入式项目来举例，就叫Pikachu。这个项目是一个基于ARM Cortex-M单片机的数据采集设备，功能包括串口通信、ADC采样、Flash存储、定时器中断等。代码量大概两万行左右，团队三个人维护，用的是Keil MDK加GCC双工具链。

Pikachu项目之前没有统一的风格约束，三个人各写各的。后来决定引入Cursor Rules来做风格统一，同时保留原有的clang-format作为最后一道格式化防线。下面我就按这个项目的实际改造过程来讲。

3. Cursor Rules文件怎么写才管用

3.1 规则文件的位置和基本结构

Cursor支持几种规则文件位置，最常用的是项目根目录下的.cursorrules文件。另外也可以在.cursor/rules/目录下放多个.mdc文件，按主题拆分。对于Pikachu项目，我建议用单文件.cursorrules，因为嵌入式项目的规范相对集中，拆太散反而不好维护。

文件的基本结构没有强制要求，但按经验，分成几个区块写会比较清晰：

• 项目概述：说明这是什么项目，用什么芯片，什么工具链
• 代码风格：缩进、命名、括号、注释等
• 文件组织：头文件包含顺序、文件命名规则
• 嵌入式特定规范：中断、寄存器、内存操作等
• 禁止事项：明确列出不能做的事

每个区块用Markdown标题分隔，Cursor解析起来更准确。

3.2 代码风格规则的具体写法

写规则最忌讳的是太抽象。比如“命名要规范”这种话，Cursor看了等于没看。要写成可执行的具体描述。下面是我在Pikachu项目里实际用的规则片段：

## 代码风格 - 缩进统一使用4个空格，禁止使用Tab字符 - 左大括号不换行，跟在语句同一行，例如： if (condition) { do_something(); } - 函数名使用小写字母加下划线，例如 adc_start_conversion - 全局变量以 g_ 开头，静态变量以 s_ 开头，例如 g_system_tick - 宏定义和常量全部大写，单词间用下划线，例如 MAX_BUFFER_SIZE - 指针类型星号靠近变量名，例如 uint8_t *p_data - 每行代码不超过100个字符 - 注释使用 /* */ 风格，禁止使用 // 单行注释

这里有几个点值得说明。为什么禁止//注释？因为有些老旧的嵌入式编译器对C99的//支持不完整，虽然现在主流编译器都支持了，但为了兼容性统一用/* */更稳妥。为什么指针星号靠近变量名？这是Linux内核风格的约定，好处是uint8_t *p_data, data;这种声明里能一眼看出哪个是指针。

规则里最好带上正例和反例，Cursor对例子的理解比纯描述更准。比如：

- 函数参数超过3个时，每个参数单独一行，例如： void uart_send(uint8_t *p_buf, uint16_t len, uint32_t timeout); 不要写成： void uart_send(uint8_t *p_buf, uint16_t len, uint32_t timeout);

3.3 嵌入式特定规范的补充

这部分是通用格式化工具搞不定的，也是Cursor Rules价值最大的地方。Pikachu项目里我写了这些：

## 嵌入式特定规范 - 所有中断服务函数必须以 _IRQHandler 结尾，例如 TIM2_IRQHandler - 中断服务函数内禁止调用 printf、malloc、delay 等阻塞或非重入函数 - 访问硬件寄存器必须通过 volatile 指针，禁止直接对地址赋值 - 所有外设初始化函数返回 int32_t 类型，0表示成功，负数表示错误码 - 共享变量在中断和主循环之间传递时必须加 volatile 修饰 - 禁止使用动态内存分配，所有缓冲区在编译期确定大小 - 位操作使用位带别名或标准宏，禁止魔法数字，例如用 GPIO_PIN_5 而不是 0x20

这些规则如果靠人记，新人很容易犯错。写进Cursor Rules之后，AI在补全代码时会自动避开这些坑。比如你写中断函数，它不会给你补printf进去。

3.4 规则文件的维护经验

规则文件不是写完就一劳永逸的。Pikachu项目刚开始写了大概80行规则，后来随着项目推进，陆续补充到150行左右。我的经验是：

• 每次代码评审发现新的风格问题，就补一条规则进去
• 规则要定期清理，过时的约定删掉，否则Cursor会被误导
• 规则文件本身也要进版本控制，团队共享
• 不要写太多规则，超过200行之后Cursor的注意力会被稀释，重点规则反而不突出了

提示：规则文件里的描述要具体到可以直接判断对错，避免“尽量”“建议”这类模糊词。Cursor对确定性描述的遵守度明显更高。

4. 把Cursor Rules和现有工具链串起来

4.1 与clang-format的分工

Cursor Rules管的是“生成时遵守规范”，但它不保证格式化。也就是说，AI帮你写的代码风格是对的，但你自己手敲的代码可能还是乱的。所以clang-format这类格式化工具不能丢，它负责最后一道防线。

Pikachu项目的做法是：Cursor Rules负责实时引导，clang-format负责提交前统一格式化。两者要配合好，关键是配置文件要一致。比如Cursor Rules里写“缩进4个空格”，那.clang-format里就要有IndentWidth: 4和UseTab: Never。

下面是一个和前面规则匹配的.clang-format配置片段：

BasedOnStyle: LLVM IndentWidth: 4 UseTab: Never BreakBeforeBraces: Attach ColumnLimit: 100 PointerAlignment: Right AllowShortFunctionsOnASingleLine: None

BreakBeforeBraces: Attach对应“左大括号不换行”，PointerAlignment: Right对应“星号靠近变量名”。这样两边就不会打架。

4.2 与git hook的集成

光有工具不够，得让它自动跑。Pikachu项目用了一个简单的pre-commithook，在提交前对所有改动的.c和.h文件跑一遍clang-format，如果格式化后有变化就拒绝提交，提示开发者先格式化。

#!/bin/bash files=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(c|h)$') if [ -n "$files" ]; then for f in $files; do clang-format -i "$f" git add "$f" done fi

这个脚本会直接把格式化结果加回暂存区，省得开发者手动操作。注意这里用的是-i原地修改，不是检查模式，因为检查模式还得让人再跑一遍，多一步就多一分偷懒的可能。

4.3 与CI流水线的配合

如果项目有CI，可以在流水线里加一个检查步骤，确保合并进来的代码都符合规范。Pikachu项目用的是GitLab CI，加了一个job：

style-check: script: - find . -name '*.c' -o -name '*.h' | xargs clang-format --dry-run --Werror

--dry-run --Werror的意思是只检查不修改，有不符合的就报错退出。这样能挡住那些绕过本地hook的提交。

4.4 Cursor Rules在团队协作中的实际效果

Pikachu项目引入这套机制大概两个月后，几个变化比较明显：

• 代码评审里关于风格的讨论基本消失了，评审时间缩短了大概三分之一
• 新人上手快了很多，因为规则文件本身就是一份可执行的编码规范
• 代码库的整体一致性明显提升，跨文件阅读不再有割裂感

当然也有代价。规则文件需要维护，偶尔会出现Cursor生成的代码和clang-format结果不一致的情况，需要回头调整规则描述。但总体来说，投入产出比是划算的。

5. Pikachu项目实战：从零配置到落地

5.1 环境准备和Cursor基础设置

先说环境。Pikachu项目用的是Windows加Keil MDK，但代码编辑和规则管理在Cursor里做。Cursor的安装没什么特别的，官网下载安装包一路下一步就行。装完之后有几个设置建议调整：

第一是语言。Cursor默认英文界面，如果你习惯中文，可以在扩展市场搜“Chinese (Simplified) Language Pack”装上，然后重启。不过说实话，用英文界面查文档和搜问题更方便，我建议保持英文。

第二是模型选择。Cursor内置了好几种AI模型，写代码补全和规则理解用默认的就行。如果遇到复杂逻辑分析，可以手动切到更强的模型。免费额度用完之后需要订阅，这个看个人需求。

第三是打开项目的方式。直接把Pikachu项目的根目录用Cursor打开，然后在根目录创建.cursorrules文件。Cursor会自动识别这个文件并应用到整个项目。

5.2 规则文件的完整示例

下面是Pikachu项目实际使用的.cursorrules文件完整内容，可以直接参考修改：

# Pikachu 嵌入式项目编码规范 ## 项目概述 本项目是基于 ARM Cortex-M4 的数据采集设备固件，使用 C99 标准。 工具链：Keil MDK 5 + ARM GCC。代码总量约 2 万行。 ## 代码风格 - 缩进使用 4 个空格，禁止 Tab - 左大括号不换行 - 函数名小写下划线，全局变量 g_ 前缀，静态变量 s_ 前缀 - 宏和常量全大写 - 指针星号靠近变量名 - 每行不超过 100 字符 - 注释用 /* */，禁止 // - 函数之间空一行 ## 文件组织 - 头文件包含顺序：标准库、CMSIS、项目公共头、本模块头 - 每个 .c 文件对应一个同名 .h 文件 - 头文件必须加 include guard，格式为 PIKACHU_模块名_H ## 嵌入式规范 - 中断函数以 _IRQHandler 结尾 - 中断内禁止阻塞调用 - 寄存器访问用 volatile 指针 - 外设初始化返回 int32_t，0 成功 - 中断与主循环共享变量加 volatile - 禁止动态内存分配 - 位操作禁止魔法数字 ## 禁止事项 - 禁止使用 goto - 禁止在头文件里定义变量 - 禁止使用未初始化的指针 - 禁止忽略函数返回值（除非明确标注可忽略）

这个文件大概60行，覆盖了Pikachu项目最核心的规范。实际使用中可以根据需要增减。

5.3 实际编码中的效果验证

配置好之后，我拿几个典型场景测了一下。比如写一个串口发送函数，我只敲了函数名和参数，Cursor补全出来的代码是这样的：

int32_t uart_send_data(uint8_t *p_data, uint16_t len, uint32_t timeout) { if (p_data == NULL || len == 0) { return -1; } for (uint16_t i = 0; i < len; i++) { while (!uart_tx_ready()) { if (timeout-- == 0) { return -2; } } uart_write_byte(p_data[i]); } return 0; }

缩进4空格、大括号不换行、指针星号靠变量名、返回int32_t、参数检查，全都符合规则。如果没配规则，补全出来的可能是另一种风格，比如大括号换行、用//注释、返回void。

再比如写中断函数，我敲了void TIM2_，Cursor补全出TIM2_IRQHandler，并且函数体里没有出现任何阻塞调用。这就是规则在起作用。

5.4 参数计算与配置细节

这里补充一个实际配置中的细节。Pikachu项目用的GCC工具链，clang-format的版本要和Cursor里C/C++插件的格式化引擎版本尽量一致，否则可能出现同一份代码两边格式化结果不同的情况。

检查版本的方法是在终端跑：

clang-format --version

然后在Cursor设置里搜“C_Cpp: Clang_format_fallback Style”，确认用的格式化配置和命令行一致。Pikachu项目统一用.clang-format文件，两边都指向这个文件，就不会有分歧。

另外，ColumnLimit设成100是因为嵌入式代码里寄存器操作和宏定义经常比较长，80太紧，120又太松。这个值可以根据团队习惯调整，但一旦定了就别频繁改，否则git diff里全是格式变动。

6. 常见问题与排查技巧实录

6.1 Cursor不遵守规则怎么办

这是最常见的问题。表现是明明规则里写了“禁止Tab”，Cursor补全出来的代码还是带Tab。排查思路如下：

首先确认.cursorrules文件在项目根目录，而且Cursor确实加载了。可以在Cursor的聊天窗口里问一句“本项目的缩进规则是什么”，如果它答不上来，说明规则没加载。

其次检查规则描述是否足够具体。像“代码要整洁”这种话Cursor没法执行，要改成“缩进4空格，禁止Tab”这种可判断的描述。

第三，规则文件太长也会导致遵守度下降。如果超过200行，建议拆分成多个.mdc文件放在.cursor/rules/目录下，按主题分。

最后，Cursor的AI补全和规则遵守不是100%可靠的，偶尔会漏。所以clang-format这道防线不能省。

6.2 规则和clang-format冲突的处理

有时候Cursor按规则生成的代码，跑clang-format之后被改了。比如规则里写“函数参数超过3个换行”，但clang-format的BinPackParameters设置可能导致它不换行。

解决办法是让两边配置对齐。在.clang-format里加：

BinPackParameters: false BinPackArguments: false

这样参数多了就会自动换行，和规则一致。每次发现冲突，就回头调整其中一边的配置，直到两边结果一致。

6.3 团队协作中的规则同步问题

三个人用Cursor，如果规则文件不一致，生成出来的代码风格就不同。Pikachu项目的做法是把.cursorrules和.clang-format都放进git仓库，任何人修改都要走评审。另外在README里写清楚这两个文件的作用，新人clone下来就能用。

还有一个坑是Cursor的版本差异。不同版本的Cursor对规则文件的解析可能略有不同，团队最好统一版本。Pikachu项目要求所有人用同一个大版本，避免出现“我这边规则生效你那边不生效”的情况。

6.4 常见问题速查表

6.5 几个踩过的坑

第一个坑是规则文件里用了太多“建议”“尽量”这类词。Cursor对这类模糊描述基本无视，后来全部改成“必须”“禁止”才生效。

第二个坑是刚开始把规则写得太细，连每个函数的注释格式都规定了，结果规则文件膨胀到300多行，Cursor反而经常漏掉核心规则。后来精简到60行，效果明显好转。

第三个坑是忘了把.cursorrules加进.gitignore的例外。有次新人clone项目发现规则没生效，查了半天发现是.gitignore里有个通配符把点文件都忽略了。

第四个坑是Cursor的AI补全偶尔会“自作聪明”，比如你写了个不符合规则的命名，它不提醒你，反而顺着你的错误命名继续补全。这种情况只能靠代码评审和clang-format兜底。

7. 一些延伸想法和实际体会

这套方案跑下来，我最大的体会是：工具的价值不在于多先进，而在于能不能嵌进日常工作流。Cursor Rules之所以好用，是因为它就在你写代码的那个窗口里，不用切来切去。规则文件用自然语言写，改起来也方便，不像传统linter配置那样一堆正则表达式。

Pikachu项目后来还把规则文件扩展了一下，加了一些业务相关的约定，比如“所有ADC采样值必须经过滑动平均滤波”“Flash写入前必须先擦除对应扇区”。这些规则AI在补全时会参考，相当于把领域知识也固化下来了。

当然，Cursor Rules不是万能的。它管不了逻辑错误，管不了内存泄漏，管不了时序问题。它解决的是风格一致性和部分约定俗成的规范问题。真正的代码质量还得靠测试、评审和静态分析工具。

如果你也在做嵌入式C项目，建议先从一个小模块试起，写十几条核心规则，跑一两周看看效果。觉得顺手再推广到整个项目。规则文件不用一次写完美，边用边补，慢慢就沉淀成团队自己的编码规范了。