企业官网建设流程全解析

pstack的注释哲学：no-comments技能与注释规则深度解析

【免费下载链接】pstack-claudeClaude Code, Codex, Copilot, Pi, OpenCode, Gemini, and Prime Agent versions of Poteto's pstack. Rigorous agent workflows with Cursor primitives translated for other harnesses.项目地址: https://gitcode.com/GitHub_Trending/ps/pstack-claude

pstack 是把 Poteto 的严格 Agent 工作流移植到 Claude Code、Codex、Pi 等平台上的技能栈。它最有争议也最有趣的设计，是no-comments 技能：一套默认"有罪推定"的注释规则——注释先被删，少数类型才配活下来。本文带你读懂 no-comments 技能、comment-sicko 子代理，以及 pstack 完整的注释清理规则。

🧹 no-comments：提交前的一轮"注释净化"评审

在 pstack 的命令目录中，这条技能只有一句话的官方定义：

/no-comments：strip comments before review, fix the accepted findings, encode claimed constraints. （评审前剥离注释，修复被接受的发现，并把声称的约束编码成可执行形式。）

见 docs/reference.md。它的完整定义在 plugins/pstack/skills/no-comments/SKILL.md，核心是一条六步流水线：

1. 派出子代理：用subagent_type: "pstack:comment-sicko"派出"找茬者"，把审查范围（当前文件、diff 或相对main的变更）交给它；
2. 审查报告：主代理逐条核对发现，拒绝误报——被保留的注释必须"有证据证明代码无法表达它"；
3. 处理小修复：删死代码路径、丢无用参数、改用真实 API；
4. 根因修复：删除每个被点名的 workaround，而不加"症状守卫"；
5. 约束注释：遇到do not remove之类的注释，给出最便宜的"编码"方案——类型、运行时检查、测试或 CI lint，批准后才编码并删除注释；
6. 输出报告：删除数量、恢复的注释、未强制的约束等。

它的设计意图在 CHANGES.md 中有记录：no-comments加上comment-sicko子代理，共同构成一道"comment-stripping review pass"（注释剥离评审通道）。

🤖 comment-sicko：一个"仇恨注释"的子代理

plugins/pstack/agents/comment-sicko.md 里的角色设定相当个性：

A deranged comment-hater that savors deletion and condemns workaround code. （一个变态的注释仇恨者，以删注释为乐，并以 workaround 代码为罪。）

它对"叙述性注释、横幅分隔线、被注释掉的尸体代码、workaround 说教"全部感兴趣。但它的纪律也很严格：

• 只报告，不动代码：它只点名触碰的文件、删除计数、MUST KILL标记（每个附一行说明）和跳过项，从不写应用代码；
• lint 抑制不放过：eslint-disable、@ts-ignore、@ts-expect-error等"发臭"的抑制必须查明规则——如果规则真能抓 bug 或保护正确性，就杀掉抑制并标记MUST KILL；
• IMPORTANT、do not remove只是"气味，不是证据"：它会读附近代码，必要时跑/how、/why技能去求证，证明不了的注释就删。

✅ 注释的"五宗豁免"：哪些注释能活下来

comment-sicko 的"唯一缰绳"是 comment-sicko.md 第 16-21 行 的例外清单，只有五类：

清单之外，"不确定的就死"（When I am not sure a keep clause applies, the comment dies）。

⚡ 如何触发一次注释清理

安装 pstack 插件后（各平台安装方式见 README.md），直接在 Agent 会话中运行/no-comments即可。作用范围规则很实用：

• 优先使用调用者指定的文件或 diff；
• 否则自动使用相对基础分支（默认main）的当前 diff，包含工作区未提交内容。

配合 poteto-mode 技能 使用效果最佳：它的触发器规则明确要求"评审前 →/no-comments"（见 poteto-mode/SKILL.md 第 30 行），让注释清理成为每次评审前的固定动作。

🔗 三层防线：no-comments 与 deslop、poteto-mode 的注释规则

pstack 的注释哲学不是单点技能，而是三层防线：

1. 写代码时——poteto-mode/SKILL.md 的 Comments 章节 规定：注释只保留"代码无法展示的非显然 why"；测试脚本禁止写// Phase 1: add cards这类阶段叙述，断言信息自己说话；
2. 提交时——deslop 技能 对照main的差异清理"多余的、与本地风格不一致的注释"等 AI 生成痕迹；
3. 评审前——no-comments + comment-sicko 做最终剥离，把活下来的约束注释编码成类型、测试或 lint 规则。

一句话总结这套注释规则：注释默认是债务，代码自己说话才是目标；注释要活，要么有证据，要么有豁免。

📁 相关文件速查

• 技能定义：plugins/pstack/skills/no-comments/SKILL.md
• 子代理定义：plugins/pstack/agents/comment-sicko.md
• 配套清理技能：plugins/pstack/skills/deslop/SKILL.md
• 工作流与触发器：plugins/pstack/skills/poteto-mode/SKILL.md
• 命令目录：docs/reference.md

【免费下载链接】pstack-claudeClaude Code, Codex, Copilot, Pi, OpenCode, Gemini, and Prime Agent versions of Poteto's pstack. Rigorous agent workflows with Cursor primitives translated for other harnesses.项目地址: https://gitcode.com/GitHub_Trending/ps/pstack-claude