| name | python-jupyter-comment-guard |
| description | 当当前任务创建、修改、调试、修复、重构或扩展 Python 模块、脚本、测试、数据处理代码或 Jupyter notebook 时使用，包括用户只说“fix this Python bug”“refactor this script”“update this notebook”但没提注释的情况。默认只检查本轮任务触及的 `.py`、`.ipynb` 与 notebook 风格 `.py` 文件，并对这些受影响文件做整文件注释补齐：所有命名函数和方法都要有说明，重要函数和关键逻辑写得更详细，同时仍优先遵守项目既有风格，不扫描无关文件。 |
| metadata | {"short-description":"Python/Jupyter 隐式注释守门"} |
Python / Jupyter 隐式注释守门
目标
让 Codex 在编写或修改 Python 与 Jupyter 内容时，默认把“检查并补齐必要注释”当成交付的一部分，而不是等用户额外提醒。
这个 skill 的职责是做隐式守门：当本轮任务真正触及某个 Python 或 notebook 相关文件时，自动判断该文件的注释是否足够，不足就补齐。它不会扫描整个仓库，也不会把所有代码写成教科书；默认只解释目的、关键约束和难点，如果用户明确要求更详细说明，则按要求提升说明力度。
默认执行规则：
- 只要本轮任务触及
.py、.ipynb 或 notebook 风格 .py 文件，就把“整文件检查并补齐注释”视为代码任务的一部分。
- 对这些受影响文件中的所有命名函数和方法都要补说明，而不是只覆盖少数复杂函数。
- 重要函数和函数内部关键细节默认写得更详细，但仍不逐行翻译代码。
何时使用
当本轮任务满足以下任一条件时默认使用：
- 创建或修改 Python 模块、脚本、测试文件
- 创建或修改数据处理、分析、ETL、科研计算类 Python 代码
- 创建、整理或扩展 Jupyter notebook
- 修改 Jupytext 百分号风格 notebook
.py 文件
- 用户虽然没提注释，但任务本身已经在动 Python / Jupyter 代码
即使用户主要在修 bug、补功能、做重构或整理 notebook，只要本轮任务触及上述文件，本 skill 仍应介入。
何时不使用
以下情况不应触发：
- 纯讨论、纯方案设计、纯 brainstorm
- 纯 review 且没有实际代码修改
- 只改非 Python / Notebook 文件
- 当前任务没有创建、编辑、重写任何 Python / Notebook 相关代码文件
- 用户明确要求不要补注释，或项目规范明确不希望在该处增加注释
当前任务触及文件
“当前任务触及文件”只指本轮任务中明确创建、编辑、重写的 Python / notebook 相关文件。
默认包含：
.py.ipynb- 以 notebook 方式维护的 Jupytext 百分号风格
.py
默认不包含：
- 本轮没有修改的历史文件
- 工作区里与当前任务无关的未提交文件
- 其他语言文件
优先级
始终按以下优先级决策：
- 用户明确要求
- 仓库既有风格、邻近代码模式、项目文档规范
- 本 skill 的默认值
本 skill 是保底，不是压过真实项目规范的硬编码模板。
默认工作流
- 先看邻近文件和项目规范，判断已有注释语言、docstring 风格、notebook 组织方式。
- 识别本轮任务实际触及了哪些 Python / Notebook 相关文件，只关注这些文件。
- 对每个受影响文件做整文件注释审视，而不是只盯改动片段。
- 判断当前内容属于
Python 路由 还是 Notebook 路由。
- 判断应使用哪一层注释力度：
保底层、重点层、用户加严层。
- 先补真正缺失或明显不足的说明，再处理其他代码修改；不要先堆行内注释。
- 完成后自检：是否只处理了受影响文件，是否解释了真正难懂的地方，是否留下了明显废话，是否满足用户对详细程度的要求。
整文件补齐规则
对每个受影响文件，默认检查整文件是否缺少以下内容：
- 文件级说明是否缺失或明显不足
- 所有命名函数和方法前的说明是否缺失或明显不足
- 主脚本入口、编排逻辑、关键变量说明是否缺失
- 函数内部关键逻辑、关键变量和边界处理说明是否缺失
- notebook 的 Markdown 叙述、关键单元说明、结果解释是否缺失
如果缺失，就补齐；如果已经足够，就保持不动。不要因为只改了一小处代码，就顺手大扫除整个仓库；但可以在当前受影响文件内做完整的注释补齐。
三层注释策略
保底层
默认使用。
- 所有命名函数和方法都要在定义前添加中文块注释。
- 这段注释至少说明：
- 这个函数要解决什么问题
- 主要输入输出是什么
- 关键假设、边界、副作用或失败条件是什么
- 关键变量可加简短中文注释，但只标注难以从命名直接看出的意义。
- 函数内部的关键逻辑块、关键变量和边界处理也要补简短说明。
- 复杂逻辑块只解释“为什么这样做”，不要把代码字面意义再说一遍。
重点层
以下对象默认允许写得更详细：
- 主脚本入口
- 编排函数
- I/O 边界
- 数据清洗与转换
- 状态变化明显的逻辑
- 长函数
- 核心变量、配置对象、阶段性结果
- 数值敏感、业务敏感、实验敏感逻辑
重点层的目标是让用户快速读懂整体流程与关键决策，而不是让每一行都带注释。
用户加严层
当用户明确说“写详细注释”“解释清楚”“多写一点说明”“帮助我理解这段代码”时，必须提升注释力度。
此时优先加厚以下位置：
- 重要函数
- 主脚本和执行入口
- 核心变量
- 关键流程节点
- 容易误解的条件分支
- 数据结构转换和中间结果
加严时仍要避免废话型注释。详细不等于重复代码表面含义。
Python 路由
读取 references/python-guidance.md。
默认规则：
- 非平凡
.py 文件应有文件级说明。优先使用模块 docstring；若项目明显不用 docstring，也可用文件顶部中文块注释。
- 只要本轮任务触及某个
.py 文件，就要对该文件做整文件注释审视，而不是只看改动附近。
- 每个命名函数和方法都要在定义前写中文块注释，默认 2 到 4 行；重要函数可以更长。
- 极短、纯转发的简单包装函数可以写得更短，但不能完全不说明。
- 关键变量、阶段结果、状态对象、缓存对象、布尔开关可以写短注释；普通局部变量通常不需要。
- 函数内部的关键细节也要注释：非直观分支、边界处理、状态切换、缓存/中间结果、数据结构转换、数值假设、workaround 和关键变量含义。
- 新建脚本文件时，若项目没有其他明确约定，默认在文件头部写“使用方法”说明，告诉用户如何运行、需要什么输入、输出到哪里。
- 测试代码中的命名函数同样应有说明，并重点解释夹具、构造数据、边界用例和断言意图，不要把每个断言都解释一遍。
- 默认不强制 Google/NumPy docstring。只有用户明确要求、项目既有规范明确要求、或上下文强烈暗示时，才切换为 docstring。
Notebook 路由
读取 references/notebook-guidance.md。
默认规则：
- 每个主要分析阶段前都应有中文 Markdown 叙述，说明本段目的、输入来源、输出结果和观察重点。
- 只要本轮任务触及某个 notebook 或 notebook 风格文件，就要审视整份 notebook 的主要阶段说明是否足够。
- 代码单元要解释关键逻辑、关键变量、绘图/处理意图、边界处理和 notebook 特有的注意点。
- Notebook 中出现的所有命名函数和方法，同样遵守“函数定义前写中文块注释”的规则。
- 输出结果前最好有一句解释，告诉读者应该关注什么，而不是只堆表格和图。
- 尽量保持从上到下可重跑，不依赖分散的隐藏状态。
详细度升级规则
读取 references/escalation-rules.md。
在以下情况必须主动增加说明：
- 用户明确要求更详细
- 代码本身是教学、交接、审阅、科研复现或一次性 handoff 场景
- 主流程跨度大，函数之间依赖关系复杂
- 变量名受历史包袱影响，不够自解释
- 存在性能、数值稳定性、数据假设、边界行为等容易误解的地方
禁止事项
读取 references/core-policy.md。
尤其避免：
- 注释只是逐字复述代码
- 用注释掩盖糟糕命名或糟糕结构
- 在已经有明确英文 docstring 规范的项目里硬塞中文块注释
- 用户要求简洁时仍无节制地扩写
- 为了“看起来很认真”而给无关紧要的局部变量全加注释
输出自检
完成前至少检查以下几点：
- 所有命名函数和方法前是否都有清晰的中文目的说明
- 是否只检查并补齐了当前任务触及的文件，没有扩散到无关文件
- 重要函数、脚本、核心变量和函数内部关键细节是否在需要时得到了更详细解释
- 注释是否解释了目的、假设、边界和原因，而不是重复语法
- 如果用户要求更详细，最终结果是否确实比默认更详细
- 如果项目已有规范，最终写法是否服从项目规范而不是反客为主
引用导航
只读取需要的文件：
references/core-policy.md：默认目标、优先级、禁止事项、自检规则references/trigger-boundaries.md：隐式触发边界、受影响文件定义、范围控制规则references/python-guidance.md：Python 模块、脚本、函数、变量、测试的注释规则references/notebook-guidance.md：Jupyter notebook 的叙述、代码注释和输出说明references/escalation-rules.md：用户要求更详细时的升级规则examples/prompts.md：触发语和典型请求示例
