English | 简体中文

rtl-guardrails

让你的 AI 真正写出可交付的 Verilog。

---

AI 写的 Verilog，综合能过，上板不对。

代码混乱，无法维护。

便宜模型不敢用，贵模型用不起。

不换模型，只改写法。

实测四个模型，加上这套规则后：

- 通义 3.8 Max       功能错：丢数、重复交付
+ 通义 3.8 Max       通过

- DeepSeek V4 Pro    不合格：仿真编译都过不了
+ DeepSeek V4 Pro    通过

- Claude Opus 5      21 处规范问题，同步器缺 ASYNC_REG
+ Claude Opus 5      全部归零

! 豆包 2.1 Turbo     规范 12 处 → 0，CDC 从 Critical 升到最高档
! 豆包 2.1 Turbo     功能仍未通过（豆政委依旧幽默）

前三者产出完全一致：功能、综合资源、跨时钟域评级、代码规范，四个维度一个不差。

这不只是"代码变好了"——是不同的模型被压到了同一个解上。 产出可预期，不再是每次开盲盒。

「我已经在用 Opus 5 / GPT 了，还需要这个吗？」

需要。 同一个 Claude Opus 5，用规则前后：

	不用规则	用规则
功能	PASS	PASS（本来就写对了）
代码规范	21 处问题	0
跨时钟域评级	CDC-2（缺 ASYNC_REG）	CDC-3
资源	8 LUT / 83 FF	6 LUT / 158 FF

CDC-2 = 同步器缺 ASYNC_REG。 两级触发器可能被摆得很远，亚稳态裕量实打实下降——不是纸面扣分。 多出的 75 个 FF 占这块器件的 0.018%，不用管。

写得对的模型，规则把"碰巧对了"变成"结构上可审计地对"；写不对的模型，规则直接把功能救回来。

两样东西，纯文本，不装任何软件：

1. 一份规则 —— 发给 AI，它照着写
2. 一个脚本 —— 扫一遍，告诉你哪里会炸

每一条规则都来自 Xilinx FPGA 上踩过的坑。作者已有项目用它生成代码并交付。

---

规则管住 AI 什么

不是排版偏好，是每一条都堵死一类事故：

规则	堵的是什么
跨时钟域只准用 XPM，不准手写同步器	手写的十次有九次漏 ASYNC_REG、漏握手保护
一个 always 只驱动一个信号	以后改一个信号，不会连累另外四个
声明全部集中在模块头	断掉前向引用，堵死隐式 wire
时序寄存器在声明处给初值	仿真开局不是 x，仿真和上板对得上
输出一律先寄存再出端口	组合逻辑不出模块，毛刺不外传
禁 for / function / task	代码的形状就是电路的形状，一眼看得出有几个加法器

这是最能体现取舍的六条。 完整条文在 SKILL.md（529 行）， 还管复位范围、状态机三段式、握手与反压、位宽推导、寄存器命名、 调试信号的挂载与摘除等等；每条背后的论证与裁决记录在 references/rationale.md。

脚本告诉你什么

不说"你违反了第几条"，只说"这么写会出什么事"：

它抓到什么	不改会怎样
寄存器没给初值	仿真开局一片 xxxx，你找不到源头
一个 always 驱动五个信号	以后改一个，另外四个跟着变
声明写在逻辑后面	信号名打错，综合器造根悬空线，0 warning 通过，上板才发现
除数是变量	推断出一个完整除法器，时序收敛杀手

每条都指到行号。以上是 39 条里挑出来的 4 条，其余的还查：

• 语言语义与综合行为（15 条）—— 时序块用了阻塞赋值、组合块用了非阻塞、组合块漏默认值导致 latch、 initial / casex / # 延时、缺 timescale、裸立即数位宽、尾随逗号、文件编码
• FPGA 平台（3 条）—— 模块内部三态、inout 非顶层、时序寄存器初值
• 可维护性（8 条）—— 位置连接、$clog2、reg 数组、for / function / task
• 格式与命名（13 条，默认关闭）—— 缩进、方向后缀、实例名前缀、嵌套三元、一文件一模块……

---

有用吗——实测数据

同一道跨时钟域的题，四个模型各写一遍，Vivado 2018.3 综合 + xsim 功能仿真判定：

模型	直接写	用了这套规则
Claude Opus 5	功能通过，21 处问题	功能通过，0 处
DeepSeek V4 Pro	不合格（仿真编译失败），27 处	功能通过，0 处
通义 3.8 Max	功能错（丢数、重复交付），14 处	功能通过，0 处
豆包 2.1 Turbo	死锁，12 处	仍有功能问题，0 处

用了规则之后，DeepSeek、通义、Claude Opus 5 三者的产出在每一个实测维度上完全相同：

	功能	代码规范	跨时钟域评级	综合资源
Claude Opus 5	PASS	0	CDC-3	6 LUT / 158 FF
DeepSeek V4 Pro	PASS	0	CDC-3	6 LUT / 158 FF
通义 3.8 Max	PASS	0	CDC-3	6 LUT / 158 FF

用我们收集的任何一个指标，都区分不出这三份代码出自哪个模型。 而不用规则时，它们的资源是 8/83、4/82、8/82，各写各的。

原始代码、Vivado 报告、复现脚本、以及失败案例，全在 eval/round1/。

---

怎么用

让 AI 按这套规则写代码

用 Claude Code 之类支持 skill 的助手——把整个文件夹放进 skills 目录，改个名对齐即可：

~/.claude/skills/rtl-guardrails/     ← 个人全局，所有项目都生效
<你的项目>/.claude/skills/rtl-guardrails/    ← 只在这个项目生效

放好之后正常提需求就行，说到"写一个模块""按我的风格改"它会自己加载。

用网页版 AI（GPT / DeepSeek / 通义 / 豆包）——把 SKILL.md 和 references/patterns.md 的内容一起粘给它，再说你的需求。这几个都试过。

不确定怎么弄——把整个文件夹丢给你的 AI 助手，让它自己读， 然后跟它说"按这套规则给我写 Verilog"。

检查已有的代码

python scripts/check_style.py  你的模块.v          # 只检查
python scripts/check_style.py  --fix  你的模块.v   # 顺便把排版也规整了

只要有 Python 3 就行——零第三方依赖，不用 pip install，不用虚拟环境。

Windows 上敲 python 弹出应用商店？那是系统的占位程序不是真 Python。 改用 py scripts/check_style.py 你的模块.v 就行。

实在拿不准，把报错原样贴给你的 AI 问一句，比自己猜快得多。

---

检查脚本的严格度：--profile

脚本查得多严，你自己定。 前面「脚本告诉你什么」列的那四类， 正好对应四个档位，一档比一档严：

python scripts/check_style.py --profile core  你的模块.v

档位	查到哪一层	什么时候用
core	只查语言语义与综合行为	只想知道"哪里一定会炸"
fpga	再加 FPGA 平台	上板前的底线检查
maintain	再加可维护性 —— 默认就是这档	交给别人、或者要长期维护
all	再加格式与命名	完整约束，作者自己日常用这档

默认档位不含格式与命名那 13 条——那些是作者的个人偏好， 你完全可以不认同，所以不会一上来就拿它们烦你。

---

适用范围

Warning

仅 AMD/Xilinx FPGA（Vivado 流程）。Intel / Lattice / ASIC 不适用。 "声明处给初值 + 前馈不复位"这套做法依赖 Xilinx 的 GSR，在 ASIC 上照搬是错的。

• 默认输出 Verilog-2001
• 只管可综合 RTL，testbench 不在范围内

已知局限

• SKILL.md 正文没做同档位拆分：脚本已分四档，但 529 行条文仍是一份完整的个人规范。只用脚本的人不受影响，想直接抄条文的人需自行取舍
• 部分条文是工程政策不是物理约束（如 assign 出端口必落一拍）——references/rationale.md 里逐条标了依据，别当硬性约束照搬
• 上面那组对照数据只有一轮、一道题、四个模型，不可外推。"完全一致"指的是该实验测到的四个维度（功能、资源、CDC 评级、代码规范）无差异，不等于两份代码逐字相同
• 规则本身已在真实项目中用于生成代码并交付，但那是生产使用——没有对照组、没有量化记录，只能说明它在实践中站得住，不能当实验证据用
• 四个模型里收敛了三个，豆包用了规则仍然功能不通过——规则不保证一定救得回来

Important

它管不了功能对错。 check_style 查写法，report_cdc 查跨域结构， 功能正确性只能靠仿真——三者不可互相替代。 实测中出现过"风格评分更好、但功能是错的"的情况。

与 Verilator 的关系

不重复，建议一起用。 Verilator 查的是仿真正确性与 IEEE 合规；这套查的是综合出来能不能用。 重叠的只有三条（时序块阻塞赋值、casex、无位宽字面量），其余互补。

许可

Apache-2.0。可以自由使用、修改、商用，两个要求：

• 再分发时保留 NOTICE 内容，并标注你改了什么
• 不得使用本项目名称或作者名义为你的产品背书

check_style.py 每次运行会打印一行出处，按许可第 4 条它属于必须保留的署名。

联系

作者 bawan（八萬） · 827490081@qq.com · Issues、邮件、QQ都行。

特别欢迎这类反馈：某条规则在你的项目里不成立、或者误报了。 规则的适用边界比规则本身更值钱，而我一个人测不出所有边界。