PowerToys AI 贡献指南.claude/CLAUDE.md 规则体系与 AI 协作栈全解【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToys本文以.claude/CLAUDE.md这份「PowerToys AI 贡献者指引」为主线逐条解读其核心规则、风格强制机制、组件级指令的自动加载原理以及 Shortcut Guide 键盘快捷键清单KBSC的命名规范。读完之后你将了解 PowerToys 如何为 AI 编码助手Copilot / Claude Code 等设计一套分层的上下文体系从顶层 CLAUDE.md 入口到按文件位置自动应用的instructions文件再到.claude/目录下的代理agents、命令commands与技能skills栈。1. CLAUDE.md 的定位AI 协作的总入口.claude/CLAUDE.md的 YAML frontmatter 将其定义为PowerToys AI contributor guidancePowerToys AI 贡献者指引正文第一句即点明自身定位——简洁版指引完整细节跳转到顶层 AGENTS.mdConcise guidance for AI contributions. For complete details, see AGENTS.md.也就是说PowerToys 采用双入口设计AGENTS.md仓库根目录面向所有 AI 代理的顶层贡献指南applyTo: **对所有文件生效覆盖构建、测试、边界与验证清单.claude/CLAUDE.mdClaude 系工具进入仓库时的精简入口只保留最关键的规则把细节委托给其他文档。围绕这两个入口仓库还配套了完整的.claude/协作栈目录作用示例.claude/rules/按 glob 自动应用的指令文件镜像自.github/instructions/.claude/rules/common-libraries.instructions.md.claude/agents/专职子代理.claude/agents/PlanIssue.agent.md、.claude/agents/FixIssue.agent.md.claude/commands/可触发的提示词命令.claude/commands/create-pr-summary.prompt.md.claude/skills/可复用的验证/发布技能.claude/skills/powertoys-verification/SKILL.md这种分层保证了 AI 助手在任何会话中都能先拿到精简规则再按文件位置加载组件细则而不必每次通读全部文档。2. 三条核心规则Key RulesCLAUDE.md 第 11–13 行用三条铁律压缩了 PowerToys 对 AI 贡献的基本纪律.claude/CLAUDE.md#L9-L13原子 PRAtomic PRs一个 PR 只做一件逻辑变更禁止顺手重构drive-by refactors。这条规则在 AGENTS.md 的 Boundaries 一节被进一步展开——未完成的功能不要合入 main应使用 feature 分支。改变行为就要补测试Add tests when changing behaviorAGENTS.md 给出了配套纪律改了行为就更新测试如果跳过测试必须说明理由例如仅注释修改、字符串重命名处理文件 I/O 或用户输入的新模块必须实现模糊测试fuzzing。热路径保持安静Keep hot paths quiet钩子hooks与紧密循环中禁止打日志。这条规则在 .github/instructions/common-libraries.instructions.md 中落到具体实现C 日志统一使用 spdlog 的Logger::info / warn / error / debug要求no logging in tight loops or hooks性能敏感区hooks、timers、serialization要避免不必要的分配。3. 风格强制机制Style EnforcementCLAUDE.md 第 17–19 行声明了三语言/三格式的风格治理.claude/CLAUDE.md#L15-L19每一条都有对应的落盘配置可查3.1 C#.editorconfig StyleCop.AnalyzersC# 代码遵循 src/.editorconfig并以 StyleCop.Analyzers 做静态分析。仓库中 StyleCop 规则集中在 src/codeAnalysis/ 目录Rules.ruleset 定义启用的规则集StyleCop.json 提供 StyleCop 全局配置GlobalSuppressions.cs 记录带理由的规则豁免。3.2 C.clang-formatC 代码遵循 src/.clang-format。doc/devdocs/development/style.md 补充了实操细节在 Visual Studio 中CTRLK CTRLD可对当前文档应用 clang-format若使用其他编辑器可运行 src/codeAnalysis/format_sources.ps1它从 git 获取所有已修改文件清单并对它们批量执行 clang-format要求clang-format.exe在%PATH%中或从 VS Native Tools Command Prompt 启动以自动定位%VCINSTALLDIR%\Tools\Llvm\bin\下的版本风格哲学是插入式修改跟随既有风格全新代码/整类重构尽量贴近 Modern C 与 C Core Guidelines。3.3 XAMLXamlStylerXAML 使用 XamlStyler 格式化。仓库内置了 src/Settings.XamlStyler 配置文件并可通过.\.pipelines\applyXamlStyling.ps1 -Main批量应用格式组件指令文件 .github/instructions/runner-settings-ui.instructions.md 在 Code Style 一节同样引用了该脚本。值得注意的细节CLAUDE.md 只说XAML: XamlStyler一句而具体的执行命令写在组件级指令文件里——这正是顶层精简、组件级细化分层的典型体现。4. 何时必须请求澄清When to Ask for Clarification.claude/CLAUDE.md#L21-L25 列出了 AI 助手应当停下来自行推断、转而请求人工澄清的三种情形扫描相关文档后规格仍有歧义跨模块影响不明确例如改动共享的 enum/struct牵涉 ABI 或 IPC 契约涉及安全、提权elevation或安装器installer变更。AGENTS.md 的 Boundaries 一节把这三条扩展成一张高风险区域表src/common/关注 ABI 破坏src/runner/与src/settings-ui/关注 IPC 契约与设置 schemainstaller 文件关注发布影响提权/GPO 逻辑关注策略处理回归。这为 AI 代理划定了明确的谨慎区避免其对高风险改动自作主张。5. 组件级指令文件按文件位置自动应用CLAUDE.md 第 27–31 行指出两份组件指令会根据当前编辑文件的位置自动应用.claude/CLAUDE.md#L27-L31Runner Settings UICommon Libraries5.1 自动应用机制frontmatter 的 applyTo glob这两份指令文件以及 .github/instructions/ 目录下的其他指令都带有 YAML frontmatter关键字段是applyTo——一个 glob 模式决定指令注入哪些文件的上下文--- description: Guidelines for Runner and Settings UI components... applyTo: src/runner/**,src/settings-ui/** ------ description: Guidelines for shared libraries including logging, IPC, settings... applyTo: src/common/** ---从源码结构看.claude/rules/目录中保留了这些指令文件的镜像副本如 .claude/rules/runner-settings-ui.instructions.md供 Claude Code 按目录约定发现.github/instructions/中的同名文件则服务于 GitHub Copilot 的 custom instructions 机制。仓库中 .claude/rules/instructions.instructions.md 还专门规定了如何撰写高质量指令文件frontmatter 字段要求、glob 写法、示例结构即元规则。5.2 Runner Settings UI 组件指令要点.github/instructions/runner-settings-ui.instructions.md 覆盖src/runner/**与src/settings-ui/**两个区域核心约束包括Runnersrc/runner/模块自举、热键管理、设置桥接、更新/提权处理IPC/JSON 契约变更必须同步更新src/settings-ui/**保持启动路径轻量早期初始化避免阻塞/网络调用保留 GPO 与提权行为。Settings UIsrc/settings-ui/不得静默破坏持久化设置 schemaschema 形状变化必须加迁移逻辑UI 绑定操作要 marshal 到 UI 线程复用既有样式/资源避免重复主题键。共享关注点修改 Runner 与 Settings UI 之间的 JSON 消息格式时必须在同一个 PR 中同时更新两侧尽量保持向后兼容为 schema 变更添加迁移逻辑并测试双向通信。验证方式从src/runner/与src/settings-ui/分别执行构建脚本再同时启动两个组件验证 IPC 通信。5.3 Common Libraries 组件指令要点.github/instructions/common-libraries.instructions.md 覆盖src/common/**日志基础设施、IPC 原语、设置序列化、DPI 感知、遥测、通用工具核心约束包括API 稳定性避免破坏公开头文件/API修改公开接口前必须全仓库 grep 调用点并全部更新ABI 敏感的 struct/class 布局变更要保持二进制兼容。性能关注热路径hooks、timers、serialization性能避免高频调用代码中的不必要分配。依赖治理新增第三方依赖需事先确认且必须 MIT 许可或经 PM 团队批准任何新增外部包都要登记到 NOTICE.md。日志C 侧使用 spdlog启动早期调用init_logger()初始化热路径保持安静。6. Shortcut Guide 键盘快捷键清单KBSC 规范CLAUDE.md 第 33–37 行专门提醒创建或编辑 Shortcut Guide 的键盘快捷键清单文件时必须遵循 doc/specs/WinGet Manifest Keyboard Shortcuts schema.md 中定义的 schema 与命名约定尤其是为没有 WinGet 包的应用使用前缀.claude/CLAUDE.md#L33-L37。结合该 spec 文档关键约定如下6.1 文件命名与存放位置文件名 WinGet 包标识符 字符串语言区域 .KBSC.yaml扩展名。例如包test.bar的en-US清单保存为test.bar.en-US.KBSC.yaml。没有 WinGet 包的应用文件名以开头——这就是 CLAUDE.md 强调的前缀约定。所有以WindowsNT开头的命名空间保留给 Windows 操作系统及其组件如WindowsNT.Shell、WindowsNT.TaskManager。本地存放目录为%LocalAppData%\Microsoft\WinGet\KeyboardShortcuts同目录下还有一份仅本地存在的index.yaml索引文件记录DefaultShellName与按WindowFilter分组的清单文件列表。6.2 清单 schema 核心字段PackageName: # 包唯一标识符 WindowFilter: # 快捷键作用的目标进程精确进程名或 * BackgroundProcess: # 可选默认 False是否对后台进程也生效 Shortcuts: # 快捷键分组列表 - SectionName: # 分类名句首大写约定 Properties: - Name: # 快捷键名称 Description: # 可选描述 AdditionalInfo: # 可选附加信息如 MinWindowsVersion Recommended: # 可选是否显示在推荐区域 Shortcut: # 需依次按下的键序 - Win: # 是否含 Windows 键 Ctrl: # 是否含 Ctrl 键 Shift: # 是否含 Shift 键 Alt: # 是否含 Alt 键 Keys: # 其余按键数字按虚拟键码解释spec 文档给出了 PowerToys 自身的真实示例Microsoft.PowerToys的清单中WindowFilter: *、BackgroundProcess: True并在 General 分组下列出 Advanced Paste 的WinV虚拟键码 86等条目。两个容易踩坑的细节Keys中的裸数字被解释为虚拟键码因此字面数字键必须写作9如切换到最后一个标签页而非99会被解释为 Tab 键特殊键用...包裹如Enter、Space完整特殊键表见 spec 文档第 3.1 节。7. 详细文档入口与配套工程实践CLAUDE.md 末尾第 39–42 行给出两个深入入口.claude/CLAUDE.md#L39-L42架构总览——Runner、Settings UI、模块、公共库的整体设计编码风格——前文第 3 节所述的 clang-format / XamlStyler / format_sources.ps1 细节都出自这里。AGENTS.md 则补上了 AI 贡献的工程闭环构建纪律首次构建/缺少 NuGet 包时先执行tools\build\build-essentials.cmd日常用tools\build\build.cmd或build.ps1 -Platform x64 -Configuration Release退出码 0 即成功非 0 即失败视为绝对标准失败时优先读取build.config.platform.errors.log。测试纪律按产品代码前缀如FancyZones、AdvancedPaste在相邻或上一级目录寻找Product*UnitTests/Product*UITests项目先构建测试项目再运行用 VS Test Explorer 或vstest.console.exe仓库内避免dotnet test。收尾验证清单构建干净、测试更新并通过、无意外 ABI/schema 破坏、IPC 契约两侧一致、新依赖已登记 NOTICE.md、PR 原子且关联 issue。8. 进阶.claude/ 下的代理、命令与技能栈CLAUDE.md 本身是规则层而仓库真正驱动 AI 完成完整工作流的是.claude/下的三个子系统理解它们能帮读者看清算法式的协作全貌Agents子代理.claude/agents/PlanIssue.agent.md 是专职规划代理输入 GitHub issue 编号产出overview.mdissue 分析与评分与implementation-plan.md技术实现计划并明确STOP 规则——规划代理不得越界去改源码其 handoff 配置可在计划完成后一键移交给 FixIssue.agent.md 开始实现。Commands提示词命令.claude/commands/create-pr-summary.prompt.md 定义了从git diff target...HEAD生成符合 PowerToys 规范的 PR 标题与描述的完整工作流——以.github/pull_request_template.md为唯一事实来源、引用改动路径用行内代码、显式说明测试覆盖。Skills技能.claude/skills/powertoys-verification/SKILL.md 封装了用 winapp CLI 对已安装 PowerToys 构建做端到端验证的能力覆盖模块发布清单核对与PR 验证两类场景逐项驱动 UIA invoke / Named Events / settings.json 编辑 / 剪贴板 / GPO / SendInput并对每项输出带证据的 PASS / FAIL / BLOCKED 结论配套的.ps1辅助脚本状态探测、剪贴板 diff、前台窗口保护等随技能一起分发。9. 小结.claude/CLAUDE.md虽然只有 42 行但它是一份精心设计的AI 上下文索引用三条 Key Rules 锚定贡献纪律原子 PR、行为变更必带测试、热路径禁日志用 Style Enforcement 指向可执行的风格配置src/.editorconfig、src/.clang-format、XamlStyler使风格从口号变成可验证的产物用applyToglob 机制把组件级细则Runner Settings UI、Common Libraries按文件位置自动注入控制上下文成本用 KBSC 规范约束 Shortcut Guide 清单的命名与 schema前缀、保留命名空间、虚拟键码/...记法通过 frontmatter 跳转与.claude/下的 agents/commands/skills 栈把规则升级为可运行的贡献工作流。对贡献者无论是人还是 AI而言遵循这套体系的实际收益是明确的改动src/common/前会先想到 ABI 影响与全仓 grep改动 runner/settings-ui 前会先想到 IPC 契约双侧同步提交前会对照 AGENTS.md 的验证清单自检——这些护栏正是大型多模块 C/C# 混合仓库能安全接纳 AI 辅助开发的工程基础。【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToys创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PowerToys AI 贡献指南：.claude/CLAUDE.md 规则体系与 AI 协作栈全解
PowerToys AI 贡献指南.claude/CLAUDE.md 规则体系与 AI 协作栈全解【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToys本文以.claude/CLAUDE.md这份「PowerToys AI 贡献者指引」为主线逐条解读其核心规则、风格强制机制、组件级指令的自动加载原理以及 Shortcut Guide 键盘快捷键清单KBSC的命名规范。读完之后你将了解 PowerToys 如何为 AI 编码助手Copilot / Claude Code 等设计一套分层的上下文体系从顶层 CLAUDE.md 入口到按文件位置自动应用的instructions文件再到.claude/目录下的代理agents、命令commands与技能skills栈。1. CLAUDE.md 的定位AI 协作的总入口.claude/CLAUDE.md的 YAML frontmatter 将其定义为PowerToys AI contributor guidancePowerToys AI 贡献者指引正文第一句即点明自身定位——简洁版指引完整细节跳转到顶层 AGENTS.mdConcise guidance for AI contributions. For complete details, see AGENTS.md.也就是说PowerToys 采用双入口设计AGENTS.md仓库根目录面向所有 AI 代理的顶层贡献指南applyTo: **对所有文件生效覆盖构建、测试、边界与验证清单.claude/CLAUDE.mdClaude 系工具进入仓库时的精简入口只保留最关键的规则把细节委托给其他文档。围绕这两个入口仓库还配套了完整的.claude/协作栈目录作用示例.claude/rules/按 glob 自动应用的指令文件镜像自.github/instructions/.claude/rules/common-libraries.instructions.md.claude/agents/专职子代理.claude/agents/PlanIssue.agent.md、.claude/agents/FixIssue.agent.md.claude/commands/可触发的提示词命令.claude/commands/create-pr-summary.prompt.md.claude/skills/可复用的验证/发布技能.claude/skills/powertoys-verification/SKILL.md这种分层保证了 AI 助手在任何会话中都能先拿到精简规则再按文件位置加载组件细则而不必每次通读全部文档。2. 三条核心规则Key RulesCLAUDE.md 第 11–13 行用三条铁律压缩了 PowerToys 对 AI 贡献的基本纪律.claude/CLAUDE.md#L9-L13原子 PRAtomic PRs一个 PR 只做一件逻辑变更禁止顺手重构drive-by refactors。这条规则在 AGENTS.md 的 Boundaries 一节被进一步展开——未完成的功能不要合入 main应使用 feature 分支。改变行为就要补测试Add tests when changing behaviorAGENTS.md 给出了配套纪律改了行为就更新测试如果跳过测试必须说明理由例如仅注释修改、字符串重命名处理文件 I/O 或用户输入的新模块必须实现模糊测试fuzzing。热路径保持安静Keep hot paths quiet钩子hooks与紧密循环中禁止打日志。这条规则在 .github/instructions/common-libraries.instructions.md 中落到具体实现C 日志统一使用 spdlog 的Logger::info / warn / error / debug要求no logging in tight loops or hooks性能敏感区hooks、timers、serialization要避免不必要的分配。3. 风格强制机制Style EnforcementCLAUDE.md 第 17–19 行声明了三语言/三格式的风格治理.claude/CLAUDE.md#L15-L19每一条都有对应的落盘配置可查3.1 C#.editorconfig StyleCop.AnalyzersC# 代码遵循 src/.editorconfig并以 StyleCop.Analyzers 做静态分析。仓库中 StyleCop 规则集中在 src/codeAnalysis/ 目录Rules.ruleset 定义启用的规则集StyleCop.json 提供 StyleCop 全局配置GlobalSuppressions.cs 记录带理由的规则豁免。3.2 C.clang-formatC 代码遵循 src/.clang-format。doc/devdocs/development/style.md 补充了实操细节在 Visual Studio 中CTRLK CTRLD可对当前文档应用 clang-format若使用其他编辑器可运行 src/codeAnalysis/format_sources.ps1它从 git 获取所有已修改文件清单并对它们批量执行 clang-format要求clang-format.exe在%PATH%中或从 VS Native Tools Command Prompt 启动以自动定位%VCINSTALLDIR%\Tools\Llvm\bin\下的版本风格哲学是插入式修改跟随既有风格全新代码/整类重构尽量贴近 Modern C 与 C Core Guidelines。3.3 XAMLXamlStylerXAML 使用 XamlStyler 格式化。仓库内置了 src/Settings.XamlStyler 配置文件并可通过.\.pipelines\applyXamlStyling.ps1 -Main批量应用格式组件指令文件 .github/instructions/runner-settings-ui.instructions.md 在 Code Style 一节同样引用了该脚本。值得注意的细节CLAUDE.md 只说XAML: XamlStyler一句而具体的执行命令写在组件级指令文件里——这正是顶层精简、组件级细化分层的典型体现。4. 何时必须请求澄清When to Ask for Clarification.claude/CLAUDE.md#L21-L25 列出了 AI 助手应当停下来自行推断、转而请求人工澄清的三种情形扫描相关文档后规格仍有歧义跨模块影响不明确例如改动共享的 enum/struct牵涉 ABI 或 IPC 契约涉及安全、提权elevation或安装器installer变更。AGENTS.md 的 Boundaries 一节把这三条扩展成一张高风险区域表src/common/关注 ABI 破坏src/runner/与src/settings-ui/关注 IPC 契约与设置 schemainstaller 文件关注发布影响提权/GPO 逻辑关注策略处理回归。这为 AI 代理划定了明确的谨慎区避免其对高风险改动自作主张。5. 组件级指令文件按文件位置自动应用CLAUDE.md 第 27–31 行指出两份组件指令会根据当前编辑文件的位置自动应用.claude/CLAUDE.md#L27-L31Runner Settings UICommon Libraries5.1 自动应用机制frontmatter 的 applyTo glob这两份指令文件以及 .github/instructions/ 目录下的其他指令都带有 YAML frontmatter关键字段是applyTo——一个 glob 模式决定指令注入哪些文件的上下文--- description: Guidelines for Runner and Settings UI components... applyTo: src/runner/**,src/settings-ui/** ------ description: Guidelines for shared libraries including logging, IPC, settings... applyTo: src/common/** ---从源码结构看.claude/rules/目录中保留了这些指令文件的镜像副本如 .claude/rules/runner-settings-ui.instructions.md供 Claude Code 按目录约定发现.github/instructions/中的同名文件则服务于 GitHub Copilot 的 custom instructions 机制。仓库中 .claude/rules/instructions.instructions.md 还专门规定了如何撰写高质量指令文件frontmatter 字段要求、glob 写法、示例结构即元规则。5.2 Runner Settings UI 组件指令要点.github/instructions/runner-settings-ui.instructions.md 覆盖src/runner/**与src/settings-ui/**两个区域核心约束包括Runnersrc/runner/模块自举、热键管理、设置桥接、更新/提权处理IPC/JSON 契约变更必须同步更新src/settings-ui/**保持启动路径轻量早期初始化避免阻塞/网络调用保留 GPO 与提权行为。Settings UIsrc/settings-ui/不得静默破坏持久化设置 schemaschema 形状变化必须加迁移逻辑UI 绑定操作要 marshal 到 UI 线程复用既有样式/资源避免重复主题键。共享关注点修改 Runner 与 Settings UI 之间的 JSON 消息格式时必须在同一个 PR 中同时更新两侧尽量保持向后兼容为 schema 变更添加迁移逻辑并测试双向通信。验证方式从src/runner/与src/settings-ui/分别执行构建脚本再同时启动两个组件验证 IPC 通信。5.3 Common Libraries 组件指令要点.github/instructions/common-libraries.instructions.md 覆盖src/common/**日志基础设施、IPC 原语、设置序列化、DPI 感知、遥测、通用工具核心约束包括API 稳定性避免破坏公开头文件/API修改公开接口前必须全仓库 grep 调用点并全部更新ABI 敏感的 struct/class 布局变更要保持二进制兼容。性能关注热路径hooks、timers、serialization性能避免高频调用代码中的不必要分配。依赖治理新增第三方依赖需事先确认且必须 MIT 许可或经 PM 团队批准任何新增外部包都要登记到 NOTICE.md。日志C 侧使用 spdlog启动早期调用init_logger()初始化热路径保持安静。6. Shortcut Guide 键盘快捷键清单KBSC 规范CLAUDE.md 第 33–37 行专门提醒创建或编辑 Shortcut Guide 的键盘快捷键清单文件时必须遵循 doc/specs/WinGet Manifest Keyboard Shortcuts schema.md 中定义的 schema 与命名约定尤其是为没有 WinGet 包的应用使用前缀.claude/CLAUDE.md#L33-L37。结合该 spec 文档关键约定如下6.1 文件命名与存放位置文件名 WinGet 包标识符 字符串语言区域 .KBSC.yaml扩展名。例如包test.bar的en-US清单保存为test.bar.en-US.KBSC.yaml。没有 WinGet 包的应用文件名以开头——这就是 CLAUDE.md 强调的前缀约定。所有以WindowsNT开头的命名空间保留给 Windows 操作系统及其组件如WindowsNT.Shell、WindowsNT.TaskManager。本地存放目录为%LocalAppData%\Microsoft\WinGet\KeyboardShortcuts同目录下还有一份仅本地存在的index.yaml索引文件记录DefaultShellName与按WindowFilter分组的清单文件列表。6.2 清单 schema 核心字段PackageName: # 包唯一标识符 WindowFilter: # 快捷键作用的目标进程精确进程名或 * BackgroundProcess: # 可选默认 False是否对后台进程也生效 Shortcuts: # 快捷键分组列表 - SectionName: # 分类名句首大写约定 Properties: - Name: # 快捷键名称 Description: # 可选描述 AdditionalInfo: # 可选附加信息如 MinWindowsVersion Recommended: # 可选是否显示在推荐区域 Shortcut: # 需依次按下的键序 - Win: # 是否含 Windows 键 Ctrl: # 是否含 Ctrl 键 Shift: # 是否含 Shift 键 Alt: # 是否含 Alt 键 Keys: # 其余按键数字按虚拟键码解释spec 文档给出了 PowerToys 自身的真实示例Microsoft.PowerToys的清单中WindowFilter: *、BackgroundProcess: True并在 General 分组下列出 Advanced Paste 的WinV虚拟键码 86等条目。两个容易踩坑的细节Keys中的裸数字被解释为虚拟键码因此字面数字键必须写作9如切换到最后一个标签页而非99会被解释为 Tab 键特殊键用...包裹如Enter、Space完整特殊键表见 spec 文档第 3.1 节。7. 详细文档入口与配套工程实践CLAUDE.md 末尾第 39–42 行给出两个深入入口.claude/CLAUDE.md#L39-L42架构总览——Runner、Settings UI、模块、公共库的整体设计编码风格——前文第 3 节所述的 clang-format / XamlStyler / format_sources.ps1 细节都出自这里。AGENTS.md 则补上了 AI 贡献的工程闭环构建纪律首次构建/缺少 NuGet 包时先执行tools\build\build-essentials.cmd日常用tools\build\build.cmd或build.ps1 -Platform x64 -Configuration Release退出码 0 即成功非 0 即失败视为绝对标准失败时优先读取build.config.platform.errors.log。测试纪律按产品代码前缀如FancyZones、AdvancedPaste在相邻或上一级目录寻找Product*UnitTests/Product*UITests项目先构建测试项目再运行用 VS Test Explorer 或vstest.console.exe仓库内避免dotnet test。收尾验证清单构建干净、测试更新并通过、无意外 ABI/schema 破坏、IPC 契约两侧一致、新依赖已登记 NOTICE.md、PR 原子且关联 issue。8. 进阶.claude/ 下的代理、命令与技能栈CLAUDE.md 本身是规则层而仓库真正驱动 AI 完成完整工作流的是.claude/下的三个子系统理解它们能帮读者看清算法式的协作全貌Agents子代理.claude/agents/PlanIssue.agent.md 是专职规划代理输入 GitHub issue 编号产出overview.mdissue 分析与评分与implementation-plan.md技术实现计划并明确STOP 规则——规划代理不得越界去改源码其 handoff 配置可在计划完成后一键移交给 FixIssue.agent.md 开始实现。Commands提示词命令.claude/commands/create-pr-summary.prompt.md 定义了从git diff target...HEAD生成符合 PowerToys 规范的 PR 标题与描述的完整工作流——以.github/pull_request_template.md为唯一事实来源、引用改动路径用行内代码、显式说明测试覆盖。Skills技能.claude/skills/powertoys-verification/SKILL.md 封装了用 winapp CLI 对已安装 PowerToys 构建做端到端验证的能力覆盖模块发布清单核对与PR 验证两类场景逐项驱动 UIA invoke / Named Events / settings.json 编辑 / 剪贴板 / GPO / SendInput并对每项输出带证据的 PASS / FAIL / BLOCKED 结论配套的.ps1辅助脚本状态探测、剪贴板 diff、前台窗口保护等随技能一起分发。9. 小结.claude/CLAUDE.md虽然只有 42 行但它是一份精心设计的AI 上下文索引用三条 Key Rules 锚定贡献纪律原子 PR、行为变更必带测试、热路径禁日志用 Style Enforcement 指向可执行的风格配置src/.editorconfig、src/.clang-format、XamlStyler使风格从口号变成可验证的产物用applyToglob 机制把组件级细则Runner Settings UI、Common Libraries按文件位置自动注入控制上下文成本用 KBSC 规范约束 Shortcut Guide 清单的命名与 schema前缀、保留命名空间、虚拟键码/...记法通过 frontmatter 跳转与.claude/下的 agents/commands/skills 栈把规则升级为可运行的贡献工作流。对贡献者无论是人还是 AI而言遵循这套体系的实际收益是明确的改动src/common/前会先想到 ABI 影响与全仓 grep改动 runner/settings-ui 前会先想到 IPC 契约双侧同步提交前会对照 AGENTS.md 的验证清单自检——这些护栏正是大型多模块 C/C# 混合仓库能安全接纳 AI 辅助开发的工程基础。【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToys创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考