Slang AGENTS.md 深度解读：面向 AI 代理的编译器仓库工程规范、构建测试流程与缺陷修复方法论

Slang AGENTS.md 深度解读面向 AI 代理的编译器仓库工程规范、构建测试流程与缺陷修复方法论【免费下载链接】slangMaking it easier to work with shaders项目地址: https://gitcode.com/GitHub_Trending/sl/slangAGENTS.md 是 Slangshader-slang/slang一个以 C20 与 CMake 实现的着色语言编译器仓库根目录下的仓库工程规范文档它既是人类贡献者的协作契约也是 AI 编程代理在该仓库中工作时的事实标准操作手册。本文完整梳理该文档覆盖的九大主题——项目结构、仓库本地 Skills、平台工具链选择、构建与测试命令、include 路径约定、编码风格与评审惯例、Shell 脚本可移植性、测试指南、以及独具特色的原则化缺陷修复方法论与五段式 PR 描述格式并结合仓库内 CMakePresets.json、.clang-format、source/core/CMakeLists.txt 等真实文件逐项印证。读完后你将掌握在 Slang 仓库中正确配置构建、运行并行测试套件、遵循命名与 include 规范以及如何按修根因、不打补丁的原则完成一次编译器变更评审。一、AGENTS.md 的定位仓库级协作契约AGENTS.md 采用 CC-BY-4.0 许可文件头部的 SPDX 声明表明版权归 Khronos Group 所有。与一般的 README 不同它不介绍项目是什么而是规定在这个仓库里应当如何工作目录如何组织、命令如何执行、代码如何书写、缺陷如何定位、PR 如何撰写。文档中多处内容明确面向自动化代理场景例如 WSL 环境下的工具选择规则这也是当前大型 C 开源项目中常见的Agent 友好型仓库治理实践。二、项目结构与模块组织AGENTS.md 开宗明义Slang 是一个以 C20 实现、使用 CMake 构建的着色语言编译器与运行时。文档列出的关键目录如下均与仓库实际布局一致目录职责source/核心实现包括source/slang/编译器主体、source/core/基础库、source/compiler-core/词法/IR/下游编译器等以及source/slangc/命令行工具include/公共 API 头文件如slang.h、slang-gfx.hprelude/ 与 source/standard-modules/标准/前导头文件即编译器生成的各目标语言前置代码与内建模块tests/按功能或目标分组组织的测试套件tests/diagnostics/、tests/hlsl-intrinsic/、tests/spirv/等tools/测试基础设施与开发者工具slang-test、slang-unit-test、gfx等docs/文档包括 docs/building.md 构建指南与 docs/design/coding-conventions.md 编码约定examples/可运行示例hello-world、ray-tracing、mlp-training等cmake/CMake 辅助脚本SlangTarget.cmake、AutoOption.cmake等external/以子模块形式 vendored 的第三方依赖glslang、spirv-tools、llvm 相关等理解这张目录地图是后续所有操作的前提include 路径约定、测试放置位置、格式化脚本作用范围全部以这些目录为锚点。三、仓库本地 Skills.claude/skills/文档规定本仓库在.claude/skills/下存放本地 agent skills且Codex 及其他非 Claude 的代理框架在用户请求相关工作流时也应查阅这些SKILL.md文件——即 skills 不绑定单一代理平台。经核实.claude/skills/ 目录下实际存在 11 个技能每个目录内均有SKILL.md。AGENTS.md 点名的是七个评审review相关技能构成一条生成候选 → 合并去重 → 范围过滤 → 解决存疑项 → 发布的流水线slang-review-clarity-workflow协调端到端的清晰度评审工作流slang-review-clarity生成高层清晰度与可解释性评审候选项slang-review-fine-grained-clarity逐行生成命名/注释/类型/函数一致性评审候选项slang-review-consolidate-candidates合并候选文件解决重复、重叠与被取代的评论slang-review-scope-filter保守地过滤候选评论只保留 PR 作者能够合理负责的条目后再发布slang-review-resolve-judgment-calls在发布前对不确定的候选项做聚焦的后续分析slang-review-post-github将过滤后的候选项作为一条规范的 GitHub PR 评审发布。目录中还存放着文档未列出的其他技能如slang-release-process、repro-remix、slangpy-debug说明该目录是持续扩展的仓库级工作流知识库。四、平台工具链选择WSL/Windows 与原生 Linux/macOSAGENTS.md 用两节专门约束跨平台工具选择这在 WSL 环境下维护 C 编译器项目时极具实战价值。WSL 上的规则当从 Windows 的 WSL 中工作时默认使用 Windows 原生开发工具除非用户明确要求 WSL/Linux 版本使用git.exe而非裸git。文档给出的理由是这些 worktree 使用 Windows 路径约定WSL 侧的 Git 可能损坏或误判 worktree 状态且 Windows Git 在此 checkout 上文件 I/O 性能更好当slang-build技能调用 CMake 时使用cmake.exe而非裸cmake——Windows 版 CMake 能找到vs2026preset 所需的 Visual Studio 2026 与 Windows 工具链该 preset 在 CMakePresets.json 中确实存在generator为Visual Studio 18 2026需要与 Windows 原生 Git 共享同一凭证上下文时使用gh.exe而非裸gh传参前转换路径WSL 路径传给 Windows 工具前先wslpath -w $pathWindows 工具输出的路径在 shell 中使用前先wslpath -u $win_path若所需.exe工具不可用应停下来报告而不是静默回退到 WSL/Linux 版本工具。这条禁止静默降级的规则对代理尤为关键。原生 Linux 与 macOS 的规则在原生 Linux 或 macOS 上则直接使用平台原生工具不带.exe后缀用git、gh、cmake、python3而不是git.exe等。两条规则互为镜像核心思想是让工具与文件系统的宿主保持一致。五、构建、测试与开发命令5.1 构建入口slang-build技能与回退文档文档明确Slang 的构建配置是平台相关的尤其在 WSL 下。构建编译器时应使用独立shader-slang/slang-skills仓库中skills/slang-build的slang-build技能而不是照搬本文件中的硬编码命令。技能提供的用法示例/slang-build build debug # 构建 Debug 配置 /slang-build rebuild debug # 丢弃已有 build 目录后重建 Debug /slang-build configure releasewithdebug # 配置带符号的优化构建 /slang-build clean # 重命名并删除已有 build 目录文档特别强调不要从通用 Linux 指令推断 WSL 构建命令必须遵循技能中定义的平台探测、宿主工具选择、CMake preset 选择与干净构建步骤。当技能因无法安装或网络受限而不可用时回退到 docs/building.md 作为构建参考——该文档给出了 TLDR 命令cmake --workflow --preset release以及 CMake 3.25 下cmake --preset defaultcmake --build --preset releaseWithDebugInfo的标准流程、vs2019/vs2022/vs2026等 Visual Studio preset、自定义编译标志覆盖-DCMAKE_CXX_FLAGS_DEBUG-O0 -g3等和CMakeUserPresets.json用法。5.2 CMake Presets 全景仓库证据CMakePresets.jsonversion 6要求 CMake 3.25.0是上述命令的落地。从配置 preset 看defaultNinja Multi-Config 生成器输出到${sourceDir}/build一次配置四种配置类型Debug;Release;RelWithDebInfo;MinSizeRelDebug 下开启SLANG_ENABLE_IR_BREAK_ALLOCvs2019/vs2022/vs2026及对应*-dev变体*-dev额外设置SLANG_ENABLE_IR_BREAK_ALLOC: TRUE一种 IR 内存破坏检测的调试辅助其中vs2022-dev输出到build/windows-vs2022-devemscriptenWasm 构建关闭 GFX/CUDA/OptiX/Replayer 等可选组件并禁用 LLVM 后端android-arm64/android-x86_64基于 NDK toolchainANDROID_PLATFORMandroid-31的移动端构建slang-llvmUSE_SYSTEM_LLVM、generators构建期代码生成器、coverageSLANG_ENABLE_COVERAGE。build presets 与 AGENTS.md 提到的构建配置一一对应debug、release、releaseWithDebugInfo、minSizeRel等workflow presets 则将 configure → build → package 串成一条cmake --workflow流水线。5.3 运行测试slang-test与并行测试服务器构建完成后从仓库根目录用所选配置目录中生成的slang-test二进制运行测试# 运行 Debug 测试套件 build/Debug/bin/slang-test # 使用测试服务器并行运行带符号的优化测试 build/RelWithDebInfo/bin/slang-test -use-test-server -server-count 8 # 并行运行 Release 测试 build/Release/bin/slang-test -use-test-server -server-count 8在 Windows 宿主构建中若生成的二进制带后缀则加上.exe。从源码看这两个参数在 tools/slang-test/options.cpp 中定义-use-test-server启用通过测试服务器运行测试-server-count n设置服务器数量默认 1与 tools/test-server/ 目录配套——这正是大测试套件能通过多进程并行显著缩短耗时的机制。六、Include 路径约定直连路径优先于相对跳转AGENTS.md 规定#include指令优先使用直连路径而非../相对跳转。原因在 source/core/CMakeLists.txt 中可以找到直接证据core静态库目标通过INCLUDE_DIRECTORIES_PUBLIC把${slang_SOURCE_DIR}/source与${slang_SOURCE_DIR}/include加入了公共 include 路径因此跨模块头文件无需../即可触达// 新代码中的首选形式 #include core/slang-string.h #include compiler-core/slang-source-loc.h // 存量代码仍是相对形式不要仅为风格而修改 #include ../core/slang-string.h #include ../compiler-core/slang-source-loc.h处理原则是典型的渐进式迁移新文件一律使用直连路径存量文件不因风格问题被强制改写但在因其他原因如安全修复、新功能大量触改实质性修改该文件时可以顺手更新。七、编码风格与命名约定7.1 格式化C/C/头文件与 Slang 文件统一使用4 空格缩进提交前运行 ./extras/formatting.sh 应用 .clang-format 与 .editorconfig 中的规则风格要点Allman 大括号、100 列限制、左对齐指针、文件末尾换行。仓库中的 .clang-format 完整给出了机器可读的规则BasedOnStyle: LLVM基础上IndentWidth: 4、ColumnLimit: 100、BreakBeforeBraces: Allman、PointerAlignment: Left以及BinPackArguments: false、AlignCaseBlocks: true等细节.editorconfig 则约束编辑器侧行为——c/cpp/h/slang文件使用 UTF-8、4 空格缩进、补末尾换行。两份配置与文档文字描述完全吻合。7.2 通用约定遵循 docs/design/coding-conventions.md普通错误处理中避免 STL 容器、iostreams、RTTI 与异常——这是编译器这类基础设施项目控制二进制尺寸与错误处理确定性的常见取舍类型用UpperCamelCase值用lowerCamelCase宏用SLANG_前缀的SCREAMING_SNAKE_CASE注释优先解释代码为什么存在。7.3 评审惯例用文档化的高频评审反馈避免返工文档专门列出反复出现的评审意见遵循它们即可减少评审轮次这是极具信息量的实战清单函数注释用完整句子先说做什么非显而易见时再说为什么非平凡逻辑要附具体示例解释性注释采用会话式conversational风格偏好 Consider this example: 后接相关用户代码避免 Full source shape、AST trace、IR trace 这类抽象标签示例之后用自然语言逐步说明——哪个 producer 构造了该 AST/IR/值形态、这段代码维护什么不变量、哪个下游 consumer 依赖它示例要包含足够的原始用户代码使读者无需凭记忆重建周边程序先复用再新写新增 helper 前先查共享头文件slang-ast-type.h、slang-ir-util.h、各*-util.h是否已有现成工具例如isDeclRefTypeOfT逻辑确实新时应提取为有命名、有文档的 helper而不是内联 lambda 或长代码块映射/分类保持单一事实来源并删除重构后不可达的分支与回退路径不要为已有表示的值再造第二套 AST/IR/Val表示会破坏equals/去重应在构造点用SLANG_ASSERT守护此类不变量对违约输入使用SLANG_RELEASE_ASSERT而不是静默返回默认值。八、Shell 脚本bash 3.2 可移植性硬约束文档要求extras/下及其他仓库 shell 脚本必须能在 bash 3.2 上运行——这是 Apple 在 macOS 上/bin/bash的实际版本。明令禁止的 bash 4 特性包括${var,,}/${var^^}大小写转换、关联数组declare -A、mapfile/readarray、namerefslocal -n替代方案示例用小写转换时用tr [:upper:] [:lower:]。验证方式为在系统 bash 下执行bash -n script.sh。extras/formatting.sh 本身就是这条约束的活样本脚本开头显式解析BASH_VERSINFO版本低于 3.2 时报错退出并在检测到Darwin时提示用 Homebrew 安装新版 bash。九、测试指南新测试放在 tests/ 中相关覆盖附近的目录按功能/目标分组如tests/diagnostics/、tests/hlsl-intrinsic/Slang 测试使用前导指令directive如//TEST(smoke):SIMPLE:仓库中的实际测试以该体系派生出//DIAGNOSTIC_TEST(smoke):SIMPLE(diagCHK):-target spirv ...等变体如 tests/diagnostics/call-argument-type.slang//DISABLE_TEST只允许伴随明确理由使用定向运行传前缀例如build/Debug/bin/slang-test tests/diagnostics/my-testC 单元测试位于 tools/slang-unit-test/惯例使用SLANG_UNIT_TEST(name)宏如 tools/slang-unit-test/unit-test-allocator.cpp 中的SLANG_UNIT_TEST(defaultAllocator)。十、问题解决方法论走原则化路径而非最小编辑距离路径这是 AGENTS.md 中最具思想性的一节明确反对最小改动距离式的补丁思维。10.1 核心原则修根因不修症状一个在 emit/codegen 阶段显现的 bug通常源自上游某个 IR pass、lowering、类型合法化、特化或 AST/IR 表示本身应追到那里质疑每一处改动如果你说不出哪个测试在没有该改动时会失败这个改动大概率不该存在同时反问问题是否在提示方向/表示本身有缺陷不要掩盖为畸形 AST/IR/witness-table 数据打掩护的守卫、空检查或特例是遮住表示层 bug 的创可贴——应把表示修对让消费者保持简单审问输入形态对处理特定输入形态AST 节点、IR inst、witness、类型……的代码永远先问该形态本身是否正确、原则化还是上游 producer 应该修形态错误就修 producer只有形态确实是合法输入时才在本地处理并把结论写进 PR 描述Process report对概念上无序的 key→value 数据witness-table / interface 需求条目按角色/键处理绝不按位置/索引全程维护工作日志问题与动机示例、问题如何级联一个修复暴露下一个、每个修复及其原则化理由附代码追踪、被否决的替代方案日志最终浓缩进 PR 描述但不提交。10.2 非原则化改动的自我评审清单对任何非平凡的编译器变更定稿前应把 diff 当作是否在补偿一套糟糕的 AST/IR/Val/witness 表示来审。文档列出七类高风险模式在证明其处于正确层级之前一律视为高危对DeclRef/Val/Type/Witness或 IR 形态新引入的自定义等价关系形如are...Equivalent、does...Match、try...Match的递归 helper——先问为什么既有的substitute、resolve、getCanonicalType、equals或既有规范化构造器不能让两个值天然一致只为让一个失败测试通过而存在的新 helper/回退/try... 函数——每个新 helper 都要审计如果它重复做了替换、解析、AST 拷贝、泛型求解、查找或 lowering多半是在掩盖真正的不变量破坏把已检查的语义数据重新变回语法的代码如从Val/Type/DeclRef/witness 重建Expr或TypeExp——已检查的语义字段通常应保留为事实来源重建语法是 producer 或 copier 存错表示的强烈信号遍历任意操作数图、替换链、witness 链或查找路径以重新发现上下文泛型实参、需求键、规范路径、父声明的代码——producer 通常应直接存储或构造规范形态在 lowering/emit/特化/typeflow 中修补前一阶段畸形 AST/IR 形态的逻辑——这些消费者应当是简单的若需要针对前端表示意外的目标特定知识应去追 producer硬编码特定DeclRef子类、内建魔法类型名、泛型实参索引、witness-table 条目顺序、嵌套/扁平特化形态的知识——此类代码需要强不变量支撑且通常应位于规范化构造边界对不可能形态静默返回默认值的守卫——形态确实违约就用断言否则说明该形态为何是合法输入并补充测试覆盖。评审执行方式先对 diff 中每个新增 helper/回退/特例做清单盘点逐项记录保留、回退、还是需要 producer 侧修复对每个被标记的改动在保留之前先完成六步输入形态审计到达这段代码的确切形态是什么给出具体示例与产生它的函数该形态是规范且被有意允许的还是意外的替代写法若是意外的能否修 producer 使下游直接走既有substitute/resolve/规范化路径已有的语义事实来源是什么这段代码是否在从它重建语法/结构形态而非保持它移除该改动后哪个测试失败该测试能否证明这一层就是责任方条件允许时做回退演练revert drill删掉 helper/特例跑最小的失败测试用失败定位真正的 producer-consumer 断裂该特例能否被断言 producer 侧修复或复用既有 helper 取代结论底线不能仅因让测试通过了就保留被标记的改动。若确有必要保留PR 描述的 Process report 必须论证该输入形态为何合法、为何这一层拥有这段逻辑并给出从 producer 到 consumer 的代码追踪。十一、提交与 PR 指南11.1 提交与合入要求commit 主题简短、祈使句例如Reject invalid descriptor heap accessPR 保持小粒度基于master合入要求工作流workflow通过、评审批准、打上pr: non-breaking或pr: breaking change标签人类贡献者在被提示时签署 CLA格式化失败时运行 ./extras/install-git-hooks.sh 安装的钩子或请求格式机器人/format。11.2 五段式 PR 描述格式PR 描述按固定五段撰写且写作对象是脑中不持有全部上下文的评审者采用与代码注释相同的会话式文风从具体用户代码示例出发贴出完整的相关片段而非仅类型或函数名按逻辑顺序解释每一步说明编译器构造了什么、该表示如何流经具名函数或 IR 指令、所选修复为何保持住了不变量避免 AST trace 这类干瘪标题。Motivation——问题本身附具体示例/动机测试用例Proposed solution——方案及其原则化理由Change summary——触及的文件/区域及各自作用Concepts and vocabulary——介于 change summary 与 process report 之间的短词汇表只复述报告所依赖的代码库特有或微妙术语如 witness、facet、fixpoint solver、修复所依赖的某个非显而易见的区分作为提醒基础且众所周知的概念interface、associated type不必解释——默认评审者已知Process report——为每处改动给出逻辑理由。对级联问题的修复描述问题附动机测试用例并用代码追踪涉及的确切函数/inst论证修复为何必要且原则化、而非权宜之计任何处理、守卫或特例化某个输入形态的改动必须回答第十节方法论中的输入形态检查——该形态是否正确原则化、还是应修 producer——以便评审者确认修复处于正确层级。十二、小结AGENTS.md 的价值在于把如何在这个仓库里高效且低摩擦地工作沉淀为可执行文本目录地图与 include 约定解决代码在哪、怎么引用skills 与构建命令解决怎么编译和测试格式化与命名规则解决代码长什么样而原则化修复方法论 输入形态审计 五段式 PR则解决编译器开发中最难的改动该落在哪一层问题。对贡献者而言逐条对照本文即可对齐仓库预期对 AI 代理而言这份文档本身就是其行为边界的权威定义。【免费下载链接】slangMaking it easier to work with shaders项目地址: https://gitcode.com/GitHub_Trending/sl/slang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考