AltTab 代码注释重构实战用 rework-comments 技能审计并精简AI 可执行的注释【免费下载链接】alt-tab-macosWindows alt-tab on macOS项目地址: https://gitcode.com/gh_mirrors/al/alt-tab-macos导读注释是代码里唯一会骗人的文档它不参与编译却能同时误导人类与 AI Agent。本指南基于 AltTab 开源仓库Windows alt-tab on macOS内置的/rework-comments技能文档系统讲解一套可落地的注释分诊triage方法论——先判断每条注释是否可验证、删掉会破坏什么再按 P1–P5 优先级处理漂移、重复、过程叙述、复述与结构性损坏的注释最后用 git diff 与构建命令确保只改了注释没动代码。读完你将掌握一套可以直接应用到任意代码库的注释审计工作流以及 AltTab 仓库中大量实测证据型注释的真实范例。这套方法为什么存在注释审计的证据基础/rework-comments技能.claude/skills/rework-comments/SKILL.md的出发点不是注释太多所以要删而是注释漂移的成本远高于缺失。技能文档引用了一组可复现的测量结论研究出处见原技能文档此处不展开外部链接错误注释的代价远超缺失注释误导性注释在代码推理基准测试上造成约 13.5 个百分点的性能损失而删除注释的损失只有 2.4–8.2 个百分点一条过时注释的成本是无注释的 2–6 倍还会使推理 token 膨胀 2–3 倍。注释数量不是关键杠杆660 次 Claude Code 最小对照仓库试验显示整洁度对通过率没有影响专门的注释量消融实验也表明注释行数并不驱动 token 成本或文件重读。短小、单一意图优于冗长、混合意图跨 8 万条翻译的统计中约 5 个词的描述性注释优于混入多种意图的 19 词作者式注释。重复与冲突消耗注意力Anthropic 在不损失评测指标的情况下削减了 Claude Code 系统提示词 80% 以上并点名跨来源命名冗余与冲突表述是具体成本来源。因此技能的核心原则非常明确不要按行数裁剪要按漂移面drift surface裁剪。目标是减少可能过时的断言而不是减少字符数。一条正确且非显然的注释无论多长都应当保留。这一原则与仓库根目录 AGENTS.md 中Comments一节第 18–25 行完全一致A wrong comment costs several times more than a missing one一条错误注释的代价是缺失注释的数倍并明确要求开发者直接运行/rework-comments来审计某个文件、某个目录或整个src/。分诊规则两条顺序固定的提问技能为每条注释定义了两条必须按顺序回答的问题问题一读者能否从眼前的代码验证这条断言不能且它是关于外部世界的事实macOS / CGS / SkyLight / AppKit 的行为、操作系统时序怪癖、实测的捕获数据、API 契约→保留KEEP。这是不可替代的类别——不重新复现那个 bug 就无法重新推导出来。不能且它是关于项目自身历史或过程的事实以前是 X、我们试过 Y 又回退了、这条注释以前说的是……、这个教训在本文件里写了三遍→删除CUT。Agent 无法基于它行动而且它会像一条关于当前代码的活断言一样被读取。能但它只是复述代码→删除CUT除非它点出了代码没有展示出的后果。问题二删掉它会破坏什么有人会再次把它简化从而重新引入 bug→保留但压缩成护栏guardrail用一句话说明约束并给出强制该约束的测试名。真正守住防线的是测试注释散文只需要指向它。什么都不会破坏→删除CUT。其余情况属于判断留白而判断留白的默认动作是保留——误删一条真实注释的成本高于保留一条平庸注释。优先级分类按收益从高到低逐个处理技能要求按顺序处理以下五个类别第一个就是最值得做的P1 — 漂移注释唯一会损害正确性的类别注释的断言与旁边代码矛盾、点名了已不存在的符号、描述了已移动的分支、或声称了代码不再具备的顺序。处理方式修正注释若事实已不存在则删除。但有一条铁律——绝不允许为了迎合注释而修改代码若发现注释是对的、代码反而可疑应将其作为疑似 bug 上报两者都保持原样。仓库中有典型的描述历史注释反例可对照。例如 GestureTriggerKernel.swift 第 132–137 行记录了手势触发器的取舍Widening this to any non-matching count was tried and reverted放宽到任何不匹配的数量曾试过并回退随后用一句话解释了原因会把逐一到来的手指和暂停的手指都算进来。该历史在 GestureTriggerKernelSpecs.md 中也有对应记录2026-08-17 曾实现并回退。按技能规则这类试过并回退的过程叙述应当压缩成一条子句如// tried pairing with newlyDiscovered; breaks testX除非它承载着有人明显会重试的载荷。另一个更彻底的例子在 CGSCallScheduler.swift 第 43–49 行SLSWindowQueryWindowswas tried here and REVERTED——该 API 曾被尝试用于窗口存在性检查注释详细说明它看起来更像更强的存在性测试但实测macOS 26 上创建窗口、关闭并释放后轮询两个 API260 秒后答案一致证明窗口关闭但进程存活的尸体窗口两个 API 都不会回收于是回退并保留显式失败信号。这类注释恰恰处于 P1/P3 的边界若它防止有人重试一个被证伪的方案就值得压缩保留否则属于应删除的过程叙述。P2 — 重复的教训同一条规则在同一个文件或同级兄弟文件中被多处陈述。处理方式保留最高作用域声明处enum/struct/ 文件头最清晰的那份删除其余复述如果某处复述携带了权威版本缺少的细节就把细节上移合并而不是同时保留两份。P3 — 过程叙述与元评论被放弃的方案、试过又回退、对旧版注释本身的评论、道歉、关于注释的自我意识旁白。处理方式见 P1 段落中的// tried …; breaks testX压缩法。若被回退的方案确实承载载荷显然有人会重试压缩成一个子句即可。P4 — 对代码的复述// increment the counter写在count 1上面——直接删除。根据 AGENTS.md 的约定如果一个代码块需要注释才能被读懂优先把它拆成有名字的子方法而不是加注释。P5 — 结构性损坏的注释段落打断了项目符号列表导致尾部项目符号看起来属于另一个列表、缩进使注释与它所解释的语句脱节、doc 注释漂移到错误的声明上方。这些注释的部分读取会给出错误答案因此行为上等同 P1。永远保留的注释清单即使某个文件注释与代码比例达到 2:1以下类别也一律不动类型顶部只陈述一次的约束与前置条件invariants and preconditions。仓库中的教科书级范例是 TabGroupResolver.swift 第 105–122 行的fullscreen Space invariant一个全屏 Space 恰好容纳一个窗口及其标签页。它被陈述在类型顶部的 doc 注释里并展开说明两条推论跨度 ≤1 个 Space ⇒ 是一个窗口跨度 ≥2 个 Space ⇒ 是多个独立全屏窗口以及前置条件窗口的 Space 归属只有恰好命名一个 Space 时才算证据无 Space 或跨多个 Space 都处于未安定状态。注释还点名了四个曾各自重新发现这一教训的 bug切换器显示上一个标签、fold 匹配不到任何东西、组把自身标签页拆成每标签一格、第二个全屏窗口被折进第一个并隐藏。这正是在最高作用域陈述一次、下面每条规则只说明自己需要哪一侧的示范。不可推导的 OS/API 行为尤其带实测证据如the OS creates a new tab at 0×0 and sizes it ~640ms later。仓库中大量注释以 measured 标注实测数据例如 App.swift 第 32 行注释记录了一次窗口清单inventory在被请求后约 280ms 落地measured第 380、491 行也交叉引用同一 ~280ms 实测值ModifierReleaseLog.swift 记录了 Carbon 在按住按键重复期间保持沉默的实测3 秒 ⌥⇥ 无重复事件。私有 API 注释、#issue 引用、未文档化行为的警告。与对应*Specs.md相互引用的内核入口点 doc 注释如 TabGroupResolver.swift 这类与TabGroupResolverSpecs.md成三件套的文件。某个 guard 存在的原因——当该 guard 看起来删掉也无妨时。许可证头、// MARK:结构、swiftlint 指令。完整工作流从基线测量到构建验证技能定义了 7 步工作流默认作用于整个src/也可传入单个路径参数。第 1 步确定范围与基线先统计 Swift 文件数量排除测试支持代码再测量每个文件的注释对代码比例comment-to-code ratiofind src -name *.swift -not -path *_test-support* | wc -l for f in $(find src -name *.swift -not -path *_test-support*); do awk -v F$f { if ($0 ~ /^[[:space:]]*(\/\/|\/\*|\*)/) c; else if ($0 !~ /^[[:space:]]*$/) k } END { if (k 0) printf %.2f %d %d %s\n, c/k, c, k, F } $f done | sort -rn | head -40汇报仓库基线比例与异常值。注意比例只决定阅读顺序不是目标——一个 3:1 的实测 OS 事实文件完全没问题而一个 0.4:1 却充满过时复述的文件才有问题。第 2 步整文件阅读绝不孤立地 grep 注释每一条分诊问题都是关于注释相对其代码的。单独抽取的注释片段无法被判断因此必须按文件通读。第 3 步逐文件分诊自上而下走查注释给每条打上 P1–P5 或 KEEP 标签。对 P1必须阅读注释所描述的代码来验证漂移——若无法确认它漂移了就保留。第 4 步应用修改只编辑注释一次一个文件。整库运行时每处理完一个文件就把进度检查点checkpoint写入 .claude/scratch/rework-comments-progress.md文件 · 状态 · 发现这样被中断的运行可以在不重读文件的情况下续跑。第 5 步验证只有注释被改动整个技能的安全属性git diff -U0 -- *.swift | grep -E ^[-] | grep -vE ^(\\\|---) \ | grep -vE ^[-][[:space:]]*(//|/\*|\*|\*/) | grep -vE ^[-][[:space:]]*$此命令必须什么都不打印。如果打印了一行说明你改了代码必须回退该 hunk。唯一误报编辑行尾注释let x 2 // note会重写整行代码从而出现在结果里——肉眼确认//之前的代码逐字节相同后即可继续。第 6 步构建验证从 ai/build.sh 复制命令并执行。只改注释也可能破坏构建未闭合的块注释、与声明脱离的 doc 注释。仓库中该脚本实际内容为xcodebuild \ -project alt-tab-macos.xcodeproj \ -scheme Debug \ -configuration Debug \ -derivedDataPath DerivedData日常迭代可用 ai/test.sh 跑单元测试它用 Debug 配置任何共享源码的编辑只触发约 1.3 秒重编译而 CI 入口 scripts/run_tests.sh 用 Release 配置会重编译全部 131 个测试文件、耗时约 34 秒。第 7 步交叉核对 specs如果改动过某个内核kernel的 doc 注释对受影响的三件套运行/audit-specs-tests——对应的*Specs.md可能引用了你修改的散文。仓库的 AGENTS.md 同样强调了三件套模式规格写进*Specs.md、单元测试写进*Tests.swift、实现写进*.swift且规格文档经常逐字引用实现里的 doc 注释改动后必须保持同步。报告要求工作完成后汇报需包含仓库基线比例以及你重写过的文件表格路径 · 处理前后注释行数 · 应用的类别。P1 漂移注释单独列出并排在最前每条给出 file:line、注释的断言、代码实际行为。这些是用户最需要看到的也是最可能指向真实 bug而非文档错误的条目。任何你刻意保留但看起来注释过量的地方附一行理由通常是实测 OS 行为。任何注释与代码冲突且注释看起来是对的的地方——疑似 bug保持原样留给用户决策。如果某个文件本就状况良好直说并继续不要为了展示工作量而制造编辑。结合仓库源码的理解要点要真正用好这套技能需要理解 AltTab 仓库自身对注释的定位。从源码结构看这个项目把注释当作对抗代码漂移的第一道防线三件套结构实现、规格*Specs.md、测试*Tests.swift同目录成组规格文档如 GestureTriggerKernelSpecs.md、TabGroupResolverSpecs.md会引用实现中的 doc 注释测试则以回归护栏regression guard的形式固定住那些注释声称的约束——这正是分诊规则中KEEP, but shrink to the guardrail的仓库落地形态。实测优先于回忆AGENTS.md 明确要求Prefer measured evidence over recollection优先实测证据而非记忆因此仓库内大量注释自带 measured 字样和具体数值它们是不可推导的外部世界事实属于分诊规则里必须保留的类别。规则只在最高作用域陈述一次TabGroupResolver把 fullscreen Space 不变量、spaceIsOurAnnotation等规则都写在类型级 doc 注释或私有方法上并显式说明两条 claim 路径共用同一规则集必须同时修复避免重复陈述导致两份拷贝漂移。综上/rework-comments不是一次性的删注释工具而是一套可重复的注释健康审计流程它的分诊问题、P1–P5 分类、永远保留清单和git diff 验证只改注释的安全闸门共同保证了注释在长期演进中既不会误导 AI Agent也不会丢失那些用 bug 换来的实测知识。【免费下载链接】alt-tab-macosWindows alt-tab on macOS项目地址: https://gitcode.com/gh_mirrors/al/alt-tab-macos创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考