PaddlePaddle 代码评审规则体系解析ai-review Skill 与 base-rules 基础评审规则【免费下载链接】PaddlePArallel Distributed Deep LEarning: Machine Learning Framework from Industrial Practice 『飞桨』核心框架深度学习机器学习高性能单机、分布式训练和跨平台部署项目地址: https://gitcode.com/GitHub_Trending/pa/Paddle本文围绕 PaddlePaddle 仓库中.agents/skills/ai-review/目录下的 AI 评审技能展开讲解该 Skill 的规则加载机制、五步评审流程、跨模块评审基础规则base-rules以及扩展规则的编写与验证方法。读完本文后你将理解 Paddle 仓库如何用一套可复用、可自动发现的评审规则约束 AI 对 Pull Request 和全仓库代码变更的审查行为并掌握新增自定义评审规则文件的规范做法。ai-review Skill 的定位与目录结构ai-review是一个面向 PaddlePaddle 仓库的代码评审技能Skill其定位在 SKILL.md 开头被明确界定评审 Paddle 代码的实际行为和跨模块影响。优先级、评论格式和发布策略由调用方决定本 skill 只提供仓库级评审规则。也就是说这个 Skill 刻意把自己限制在仓库级评审规则这一层它负责回答评审 Paddle 代码时要检查什么、依据什么检查而评审结论的优先级排序、评论的呈现格式和发布节奏则交由调用方比如 CI 机器人或评审流程的发起者管理。这种职责切分让规则文件可以独立演进不被评论格式之类的表层策略绑架。整个 Skill 由三个文件构成各自承担不同角色文件职责SKILL.md技能入口声明规则加载方式、五步评审流程、可关联的领域 Skill 和基本原则README.md面向规则维护者的说明目录组织约定、新增扩展规则的五步流程、文件模板与验证命令references/base-rules.md每次评审都必须加载的基础规则覆盖正确性、算子、分布式、数值、安全、测试与 PR 信息七个维度references/目录是规则的真正承载地base-rules.md是适用于所有评审的基础规则其余references/*.md文件则是面向特定模块、技术或风险场景的扩展规则。规则加载机制全量加载 按适用条件应用SKILL.md 的规则加载一节给出了两条关键约定开始评审前读取.agents/skills/ai-review/references/下的全部Markdown 文件且必须包含基础规则 base-rules.md。随后根据每个文件自身声明的适用路径和触发条件决定是否实际应用其他规则——注意原文强调不要仅因变更路径不同而跳过加载。新增扩展规则时在references/下使用 kebab-case 文件名并在文件开头写明适用路径、触发条件和可验证的规则来源不要重复基础规则、评论格式或发布策略。README.md 进一步解释了这套机制的设计意图扩展规则按目录自动发现不需要修改SKILL.md也不维护额外注册表。加载 Skill 时会读取该目录下全部 Markdown 文件再根据文件声明的适用路径和触发条件决定是否应用。这意味着新增一个规则文件本身就是完整的一次注册规则与入口解耦避免了中心配置文件随规则增长而膨胀、频繁产生合并冲突的问题。关于更具体的扩展规则优先于基础规则的优先级原则SKILL.md 和 README.md 都给出了冲突处理约定规则冲突且无法由代码或仓库约定判定时向维护者确认发现冲突时先修正规则不能让评审者自行猜测。五步评审流程SKILL.md 将评审工作固化为五个步骤每一步都带有明确的产出要求理解变更目标阅读 PR 描述和完整 diff确认变更目标、影响范围、兼容承诺和用户可见行为。这一步对应 base-rules 中核对 PR 描述与实现是否一致的要求。追踪定义与契约使用rg追踪定义、调用方、注册入口、配置入口、实现和测试跨模块变更必须检查两端契约。在 Paddle 仓库中一条典型的追踪链是paddle/phi/ops/yaml/中的算子 YAML 声明 → paddle/phi/infermeta/ 中的 shape/dtype 推导 → paddle/phi/kernels/ 中的设备 kernel 实现 → python/paddle/ 中的 Python API 封装 →test/下对应模块的测试。验证候选问题对照完整函数、相邻实现和现有测试验证候选问题确认可复现或有明确代码证据后再报告。给出可执行评论评论指出具体位置、影响、触发条件和修改方向不报告无依据的猜测、纯风格偏好或泛化建议。分层记录验证状态按风险选择最接近变更的测试并分别记录静态检查、CPU 验证和依赖 GPU/多卡/特定硬件的未完成验证——即不允许把环境跑不了包装成已通过。这五步与 base-rules.md 末尾将git diff --check、相关静态检查和可执行测试分开记录Paddle、CUDA、分布式或特定硬件不可用时不把未运行包装成通过的要求相互呼应构成了一条从读 diff到分层验证的完整证据链。base-rules 基础规则逐章解读references/base-rules.md 是每次评审都必须加载的核心规则集开篇即要求根据变更范围应用相关条目并在评论中给出路径、行号和可观察影响。以下按原文六章逐章梳理并对照仓库中的实际目录说明每条规则的落点。1. 功能正确性与兼容性核对 PR 描述与实现是否一致包括输入输出、默认值、支持的 shape/dtype、设备范围和测试范围检查空输入、零值、负值、上下限、重复输入、非法格式、异常路径和资源失败避免只覆盖正常流程公共 Python/C API、配置项、默认值、state dict、序列化格式或算子 schema 变化必须保持向后兼容或提供明确迁移方案跨模块变更必须检查接口两端确认参数顺序、返回值、dtype、shape、设备、place、stream 和生命周期约定一致PIR、动态图和静态图同时支持时检查三条路径的行为、自动生成代码和回退逻辑是否一致。其中PIR、动态图、静态图三条路径的表述对应 Paddle 当前的架构现状仓库中 paddle/pir/ 承载 PIR 实现paddle/fluid/framework/ 承载动态图Eager与静态图框架paddle/fluid/pir/ 则承担两者之间的衔接。规则要求同一变更在三条执行路径上行为一致正是针对这种多路径共存的现实。2. 算子、Kernel 与设备这一章直接映射到 PHI 层的目录结构也是规则中最具 Paddle 特色的一章修改paddle/phi/ops/yaml/时同步检查 InferMeta、kernel 声明和实现、注册名、Python 封装、代码生成依赖及前向/反向配置。算子 YAML 是 Paddle 算子开发的声明式入口一处 schema 变更会沿代码生成链路扩散到多个环节因此规则要求做端到端核对检查 paddle/phi/infermeta/ 的 shape/dtype 推导、输入校验、空 Tensor 和边界行为InferMeta 不应假定 kernel 一定可用——即元信息推导必须在 kernel 缺失时也能正确工作检查 paddle/phi/kernels/ 的设备与 stream、整数宽度、索引边界、内存分配、kernel launch 错误和异步生命周期CPU、CUDA、ROCm、XPU、Custom Device 或其他后端新增路径必须有明确能力保护并与已有实现保持语义一致或提供可验证回退修改python/paddle/API 时检查动态图、PIR、静态图、类型转换、梯度和文档示例不能只验证 Python 表面调用成功关注隐式同步和多余拷贝如.cpu()、.numpy()、不必要的to_tensor()、contiguous()或 device/place 往返。值得注意的是base-rules.md 中关于算子路径的表述是paddle/phi/ops/yaml/当前仓库中该目录实际位于 paddle/phi/ops/ 之下且包含若干.yaml算子声明文件这与规则描述保持一致。3. 分布式训练与并行修改python/paddle/distributed/、python/paddle/incubate/distributed/、paddle/phi/infermeta/spmd_rules/或通信逻辑时检查进程组创建/销毁、rank 成员、重新初始化和错误路径。其中 paddle/phi/infermeta/spmd_rules/ 存放 SPMD 切分规则是自动并行推导算子并行策略的依据集合通信必须使用正确的通信组并保证各 rank 的调用次数、顺序、tensor shape、dtype 和参与条件对称不能用单进程 mock 代替多进程证据检查 DP、TP、PP、SP、EP、CP、ZeRO 和自动并行组合下的局部 shape、切分、reshard、位置编码、随机数同步、共享权重和流水线边界MoE 路径重点检查 top-k、归一化、token dispatch/combine 顺序、expert index、容量/丢弃策略、共享专家及梯度对称性重计算和 CUDA Graph 变更必须保持前向/反向一致、随机状态正确、地址稳定并为动态 shape 或不支持设备保留安全回退路径。对应到测试侧分布式行为的验证目录是 test/auto_parallel/ 与 test/collective/规则要求分布式行为需要代表性的多进程覆盖。4. 数值、性能与资源前向、反向和高阶梯度的 dtype、累加精度、NaN/Inf、溢出、归一化和容差必须与 API 契约一致不能只比较单个正常样例FP16、BF16、FP8、量化、融合算子、CINN、TensorRT 或 Triton 路径必须有明确的硬件/shape/dtype 保护并与非融合实现比较结果或说明回退检查低效循环、重复计算、显存峰值、内存泄漏、句柄/事件/通信组未释放及异常路径中的资源清理性能意见必须说明热点或复杂度影响修改cmake/、paddle/**/CMakeLists.txt、代码生成脚本、依赖或 lockfile 时确认所有目标、平台和构建配置仍能解析且没有无关依赖升级。最后一条针对 cmake/ 与各级 CMakeLists 的约束说明构建系统变更是隐形影响面最大的变更类型之一规则要求显式确认全平台可解析防止一次依赖升级悄悄改变多个后端的构建行为。5. 安全与错误处理禁止硬编码密钥、令牌和凭据外部输入必须经过校验不能直接拼接到 shell、路径、SQL 或不安全反序列化操作检查权限、认证、临时文件和敏感数据处理是否符合最小权限原则避免把调试信息或环境变量写入日志不使用 Pythonassert承担运行时输入校验应抛出明确异常并保留有效错误信息避免无处理的宽泛except Exception确认文件、线程、显存、stream、通信组和临时资源在失败路径中正确释放。6. 测试质量与验证这一章把测试应放在哪、写成什么样具体化了行为变化应放入最接近变更模块的现有目录规则逐一点名了 test/legacy_test/、test/cpp/、test/auto_parallel/、test/collective/、test/custom_kernel/、test/custom_runtime/、test/custom_op/ 或对应python/测试目录分布式行为需要代表性的多进程覆盖算子测试应覆盖前向、反向、PIR/动态图适用时、shape/dtype/设备边界和异常路径测试应验证核心结果而不是只断言不报错测试之间不得相互依赖外部网络、文件系统、随机状态或服务应隔离断言不能吞掉异常、使用assert True或 mock 掉被测函数来制造成功浮点结果使用合理容差重复场景优先参数化修改ci/rules/时同步检查 ci/rule-tests/ 和快照新增 blacklist 或跳过条件不能替代回归测试。最后一条与仓库中 ci/rules/ 下的静态检查规则文件如no-int32-type-dims.yml、no-int64-type-cuda-index-without-cast.yml一一对应CI 静态规则本身也要有配套的 rule-tests 快照验证防止规则与快照漂移。7. PR 信息与评审评论检查 PR 标题是否清晰概括修改对象和目的类别前缀可参考 Paddle 仓库惯例不强制单一格式。描述至少说明动机、解决的问题、主要改动和验证方式检查 PR 描述中的精度变化、兼容性和设备范围声明是否与实现一致发现不一致时指出具体代码证据评论必须具体、可执行并解释影响原因优先报告会导致错误、回归、数据损坏、安全风险或无法构建的问题不报告纯风格偏好。领域 Skill 联动评审时的规则扩展面SKILL.md 在适用的已有 Skill一节约定涉及专门领域时同时读取对应 skill 的 references并以实际源码为准。这些领域 Skill 与.agents/skills/目录下的实际目录对应如下领域引用的 Skill对应目录算子开发paddle-op-devpaddle-op-dev分布式设计paddle-design-distributedpaddle-design-distributed编译构建paddle-buildpaddle-build调试paddle-debugpaddle-debug编译器设计paddle-design-compilerpaddle-design-compiler动态图Eager设计paddle-design-eager-graphpaddle-design-eager-graphPHI Kernel 设计paddle-design-phi-kernelpaddle-design-phi-kernel例如paddle-op-dev自带 yaml-config.md、infermeta.md、kernel-dev.md 等 references正好覆盖了 base-rules算子、Kernel 与设备一章所要求核对的各个环节。这种评审规则指向领域 Skill、领域 Skill 承载实现细节的分层方式使 ai-review 保持轻量而深度知识沉淀在各自领域的 references 中。新增扩展规则流程、模板与编写要求当评审中出现新的、基础规则未覆盖的模块或风险场景时README.md 给出了完整的操作规程。五步新增流程确认规则不是基础规则的重复表述。通用规则直接修改references/base-rules.md模块专用规则新增为独立文件在references/下新增 kebab-case 命名的 Markdown 文件例如auto-parallel.md或custom-operators.md在文件开头声明适用路径和触发条件正文只保留可验证、可执行的检查项检查规则不会要求错误的测试目录、平台能力或兼容性承诺并补充规则来源运行 skill 校验和仓库 pre-commit 检查。文件模板要求每个规则文件以元信息三行 检查主题组织# 规则名称 - 适用路径src/example/**、tests/example/** - 触发条件修改 接口、配置或行为 - 规则来源设计文档、缺陷、测试或维护者约定 ## 检查主题 - 检查 具体条件避免 可观察的影响。 - 修改 行为 时同步验证 调用方、回退路径或测试。模板背后是几条明确的编写要求适用路径应尽量具体无法用路径表达时用触发条件描述配置、数据流或跨模块行为规则来源应指向仓库文档、已确认缺陷或稳定约定不写未经验证的经验结论每条规则包含检查对象、触发条件和潜在影响避免注意性能等泛化描述不在扩展文件中重复评论格式、问题优先级或发布策略这些由评审调用方管理所有规则文件都会加载因此一个文件应聚焦一个模块或主题并删除重复或无关内容测试要求应指向最接近变更模块的现有测试目录并区分单卡、多卡和硬件相关场景。验证如何确认新规则真正生效README.md 提供了两条可执行的验证命令。第一条调用 skill-creator 的快速校验脚本对.agents/skills/ai-review做结构化校验python ${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-creator/scripts/quick_validate.py \ .agents/skills/ai-review第二条把规则文件纳入仓库 pre-commit 检查pre-commit run --files \ .agents/skills/ai-review/SKILL.md \ .agents/skills/ai-review/README.md \ .agents/skills/ai-review/references/rule-name.md自动化校验之外README 还要求做一次人工双向试评审提交前用一个匹配适用范围的真实 diff 试评审确认扩展规则会被应用再用一个无关 diff 验证它不会被误用。这种正反两次的验证方式正好对应规则加载机制中按适用路径和触发条件决定是否应用的语义——规则的价值不仅在于该触发时触发也在于不该触发时保持沉默。小结.agents/skills/ai-review/为 PaddlePaddle 仓库构建了一套分层清晰的 AI 代码评审规则体系SKILL.md 定义规则加载方式与五步评审流程references/base-rules.md 沉淀覆盖正确性、算子 kernel、分布式、数值性能、安全和测试质量的七章基础规则且每条规则都能对应到仓库中真实存在的目录如paddle/phi/ops/、paddle/phi/infermeta/spmd_rules/、test/collective/README.md 则给出扩展规则的模板、编写约束与双向验证方法。目录自动发现、入口与规则解耦、更具体规则优先的冲突处理共同保证了这套规则可以随仓库模块的演化持续扩展而不产生维护负担。【免费下载链接】PaddlePArallel Distributed Deep LEarning: Machine Learning Framework from Industrial Practice 『飞桨』核心框架深度学习机器学习高性能单机、分布式训练和跨平台部署项目地址: https://gitcode.com/GitHub_Trending/pa/Paddle创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考