Python Comments 是一个针对 Python 代码注释与文档字符串的写作与审计技能，核心依据是 antirez 在《Writing system software: code comments》中提出的九类注释分类法，并将其映射到 PEP 257 规范。
用途
该技能提供两种操作模式：写入模式用于补充缺失注释、改进现有注释、修复负面类型注释；审计模式用于分类所有注释、识别缺口并生成结构化质量报告。其核心原则是：注释解释“为什么”，代码解释“什么”，类型提示解释类型。
何时调用
写入模式的触发条件包括：用户请求“添加注释”“为代码写文档”“改进注释”；代码审查指出缺少文档字符串或逻辑不清晰；新模块、类或函数缺少文档；复杂算法或业务规则需要解释。审计模式的触发条件包括：用户请求“审查注释”“注释质量”“文档审计”；发布前文档审查；新团队成员入职准备；遗留代码评估。
不适用场景
代码计划删除；用户需要生成 API 参考（应使用文档工具）；用户需要生成类型存根（应使用类型提示工具）；简单脚本或一次性脚本，注释无附加价值。
九类注释分类法
正面类型（应编写）：类型 1 功能（Function），以文档字符串形式说明函数、类或模块做什么；类型 2 设计（Design），以文档字符串或 # 说明架构理由与 API 设计选择；类型 3 原因（Why），以内联 # 说明代码背后非显而易见的推理；类型 4 教学（Teacher），以内联 # 提供领域知识或算法解释；类型 5 清单（Checklist），以内联 # 列出不可跳过或不可重排的步骤；类型 6 指南（Guide），以 # 分节标题作为长模块中的导航辅助。
负面类型（应检测并修复）：类型 7 琐碎（Trivial），复述代码，应删除；类型 8 债务（Debt），TODO、FIXME、HACK，应解决或创建 issue；类型 9 备份（Backup），被注释掉的代码，应删除（git 保留历史）。
Python 特定映射
文档字符串（"""..."""）对应类型 1-2，描述接口（做什么、参数、返回值、异常），遵循 PEP 257。内联注释（#）对应类型 3-6，描述实现（为什么、如何、上下文）。类型提示可减少注释负担：文档字符串应记录语义，而非类型。
PEP 257 要点
单行文档字符串使用祈使语气并以句号结尾，如 """Return the user's full name."""；多行文档字符串包含摘要行、空行和详细说明；所有公共模块、类、函数、方法都需要文档字符串；私有方法在逻辑不明显时添加文档字符串。
写入模式工作流
分四个阶段。阶段 1 扫描：读取整个文件或模块，识别所有现有注释和文档字符串，映射代码结构，记录已有类型提示。阶段 2 分类缺口：按模块级、类级、函数级、块级确定缺失内容，并按影响优先级排序（关键、高、中、低）。阶段 3 编写：选择正确类型、正确形式（类型 1-2 用文档字符串，类型 3-6 用内联 #）、正确风格（匹配项目现有风格，默认 Google 风格），简洁书写，修复负面类型。阶段 4 验证：不添加琐碎注释，不重复类型提示，风格一致，保留现有有效注释，代码逻辑不变。
审计模式工作流
分四个阶段。阶段 1 收集：提取所有注释和文档字符串，记录位置、形式、关联代码元素。阶段 2 分类：为每条注释分配类型（1-9）、质量（好/足够/差）、准确性（正确/过时/误导）。阶段 3 缺口分析：识别公共 API 覆盖率、原因注释覆盖率、设计文档、负面类型数量，并按严重程度分级。阶段 4 报告：生成结构化审计报告，包含摘要、关键缺口、发现的问题、覆盖率指标、建议和注释风格。
关键约束
绝不添加琐碎注释；绝不添加占位文档字符串；绝不重复类型提示；绝不改变代码逻辑；保留现有风格；保留有效注释，仅修改或删除负面类型（7-9）或明显错误的注释。
与同包技能的集成
python-refactor-method：重构后运行写入模式更新文档字符串。pytest-patterns：测试文档字符串受益于类型 1 注释，审计模式可评估测试文档。python-performance-optimization：性能关键代码受益于类型 4 注释解释算法选择。python-packaging：包级文档（init.py 文档字符串）遵循类型 1+2 模式。