comment-quality

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Comment Quality Skill

注释质量Skill

Operator Context

操作上下文

This skill operates as an operator for documentation quality assurance, configuring Claude's behavior for timeless, meaningful code comments and documentation. It implements a Scan, Analyze, Rewrite, Verify workflow with deterministic pattern matching against known temporal and activity language.

本Skill作为文档质量保证的操作器，配置Claude的行为，以生成具备时效性、有意义的代码注释和文档。它实现了一套扫描、分析、重写、验证的工作流，通过确定性模式匹配识别已知的时间性和开发活动表述。

Hardcoded Behaviors (Always Apply)

硬编码行为（始终生效）

CLAUDE.md Compliance: Read and follow repository CLAUDE.md before scanning
Over-Engineering Prevention: Scan only files explicitly requested or in the current working scope. Do NOT scan entire codebases unless user asks for full audit
Remove ALL Temporal Language: Words like "new", "old", "now", "recently", "updated", "fixed" are NEVER acceptable in comments
Focus on WHAT and WHY: Comments MUST explain current functionality and purpose, never history or development activity
No Exceptions for Temporal Language: Every instance is flagged regardless of perceived harmlessness
Preserve Legal and Generated Markers: Copyright headers, license text, @generated tags, and @deprecated annotations are left unchanged

CLAUDE.md 合规性：扫描前阅读并遵循仓库中的CLAUDE.md
避免过度工程：仅扫描用户明确请求的文件或当前工作范围内的文件。除非用户要求全面审计，否则请勿扫描整个代码库
移除所有时间性语言："new"、"old"、"now"、"recently"、"updated"、"fixed"等词汇在注释中绝对不允许出现
聚焦内容与目的：注释必须解释当前功能和用途，而非历史或开发活动
时间性语言零例外：无论看似是否无害，所有时间性语言实例都需标记
保留法律与生成标记：版权头、许可证文本、@generated标签和@deprecated注释保持不变

Default Behaviors (ON unless disabled)

默认行为（默认开启，可关闭）

Concise Reporting: Report facts with file paths and line numbers. No excessive commentary
Suggest Rewrites: Provide corrected versions of every problematic comment
Explain Reasoning: Clarify why temporal language fails for long-term maintainability
Check Surrounding Context: Inspect nearby comments for temporal patterns when one is found
Report All Findings: List every instance, not just the first few
Temporary File Cleanup: Remove scan results, intermediate reports, or helper files at task completion

简洁报告：仅报告包含文件路径和行号的事实，无需过多额外说明
提供重写建议：为每个有问题的注释提供修正版本
解释理由：说明时间性语言为何不利于长期可维护性
检查上下文：发现时间性模式时，检查附近的注释
报告所有问题：列出所有实例，而非仅前几个
临时文件清理：任务完成后移除扫描结果、中间报告或辅助文件

Optional Behaviors (OFF unless enabled)

可选行为（默认关闭，需开启）

Auto-Fix Mode: Automatically apply corrections without user review (enable with explicit request)
Aggressive Scanning: Check git commit messages and PR descriptions (enable with explicit request)
Batch Processing: Process files by directory with grouped reports (enable for large codebases)

自动修复模式：无需用户审核自动应用修正（需明确请求开启）
深度扫描：检查Git提交消息和PR描述（需明确请求开启）
批量处理：按目录处理文件并生成分组报告（针对大型代码库开启）

What This Skill CAN Do

本Skill可实现的功能

Identify temporal language, development-activity words, and relative comparisons in comments
Provide specific, actionable rewrites that explain WHAT and WHY
Scan multiple file types:
```
.go
```
,
```
.py
```
,
```
.js
```
,
```
.ts
```
,
```
.md
```
,
```
.txt
```
Distinguish between developer comments and legal/generated markers
Generate structured reports with file path, line number, current text, and suggested fix

识别注释中的时间性语言、开发活动词汇和相对比较表述
提供具体、可执行的重写建议，聚焦内容与目的
扫描多种文件类型：
```
.go
```
,
```
.py
```
,
```
.js
```
,
```
.ts
```
,
```
.md
```
,
```
.txt
```
区分开发者注释与法律/生成标记
生成包含文件路径、行号、当前文本和建议修正的结构化报告

What This Skill CANNOT Do

本Skill无法实现的功能

Write new documentation from scratch (use documentation skills instead)
Enforce code style rules beyond comment content (use code-linting instead)
Fix comments without reading surrounding code context
Auto-fix without explicit user authorization
Modify copyright headers, license text, or generated code markers

从零开始编写新文档（请使用文档类Skill）
执行注释内容以外的代码风格规则检查（请使用代码检查工具）
不阅读周边代码上下文就修复注释
无明确用户授权的情况下自动修复
修改版权头、许可证文本或生成代码标记

Instructions

操作步骤

Phase 1: SCAN

阶段1：扫描

Goal: Identify all comments containing temporal, activity, or relative language.

Step 1: Determine scope

Scan only what was requested. If user specifies files, scan those files. If user specifies a directory, scan that directory. NEVER default to full codebase.

Step 2: Search for temporal patterns

Target these categories:

Temporal words: "new", "old", "previous", "current", "now", "recently", "latest", "modern"
Development activity: "added", "removed", "deleted", "updated", "changed", "modified", "fixed", "improved", "enhanced", "refactored", "optimized"
State transitions: "replaced", "migrated", "upgraded", "deprecated", "became", "turned into", "evolved"
Date references: "as of", "since", "from", "after", "before"
Relative comparisons: "better than", "faster than", "instead of", "unlike the previous"

Step 3: Filter false positives

Exclude from findings:

Copyright and license headers
```
@generated
```
markers
```
@deprecated
```
annotations (keep the tag, flag only temporal explanation text)
Variable names or string literals that happen to contain temporal words
TODO/FIXME items that describe future work without temporal references

Gate: All files in scope scanned. Findings list populated with file path, line number, and matched text. Proceed only when gate passes.

目标：识别所有包含时间性、活动或相对比较语言的注释。

步骤1：确定范围

仅扫描用户请求的内容。如果用户指定文件，扫描这些文件。如果用户指定目录，扫描该目录。切勿默认扫描整个代码库。

步骤2：搜索时间性模式

针对以下类别：

时间性词汇："new", "old", "previous", "current", "now", "recently", "latest", "modern"
开发活动："added", "removed", "deleted", "updated", "changed", "modified", "fixed", "improved", "enhanced", "refactored", "optimized"
状态转换："replaced", "migrated", "upgraded", "deprecated", "became", "turned into", "evolved"
日期引用："as of", "since", "from", "after", "before"
相对比较："better than", "faster than", "instead of", "unlike the previous"

步骤3：过滤误报

以下内容排除在结果之外：

版权和许可证头
```
@generated
```
标记
```
@deprecated
```
注释（保留标签，仅标记时间性解释文本）
恰好包含时间性词汇的变量名或字符串字面量
描述未来工作且无时间引用的TODO/FIXME项

检查点：已扫描范围内所有文件。结果列表已填充文件路径、行号和匹配文本。仅当通过检查点后进入下一阶段。

Phase 2: ANALYZE

阶段2：分析

Goal: Understand context for each finding to produce meaningful rewrites.

Step 1: Read surrounding code

For each finding, read the function, block, or section the comment describes. Understand what the code actually does.

Step 2: Classify the comment

markdown

| Finding | Type | Severity |
|---------|------|----------|
| "now uses JWT" | Temporal + Activity | High |
| "improved perf" | Activity | Medium |
| "Copyright 2024" | Legal (skip) | N/A |

Step 3: Determine replacement content

For each comment, identify:

What does the code do right now?
Why does it do it this way?
What value does the comment add for a future reader?

Gate: Every finding classified with context understood. Proceed only when gate passes.

目标：理解每个问题的上下文，生成有意义的重写建议。

步骤1：阅读周边代码

针对每个问题，阅读其描述的函数、代码块或部分，理解代码实际功能。

步骤2：分类注释

markdown

| 问题 | 类型 | 严重程度 |
|---------|------|----------|
| "now uses JWT" | 时间性+活动 | 高 |
| "improved perf" | 活动 | 中 |
| "Copyright 2024" | 法律文本（跳过） | 无 |

步骤3：确定替换内容

针对每个注释，明确：

代码当前的功能是什么？
为什么要这样实现？
该注释能为未来的读者带来什么价值？

检查点：所有问题已分类且上下文已理解。仅当通过检查点后进入下一阶段。

Phase 3: REWRITE

阶段3：重写

Goal: Generate specific, valuable replacement comments.

Step 1: Draft rewrites

For each finding, produce:

markdown

**File: `path/to/file.ext`**

Line X - [Comment type]:
  Current:   // Authentication now uses JWT tokens
  Suggested: // Authenticates requests using signed JWT tokens
  Reason:    "now uses" is temporal - describe current behavior only

Step 2: Validate rewrite quality

Each rewrite MUST pass these checks:

Would this comment make sense in 10 years?
Does it explain WHAT or WHY, not WHEN?
Is it more specific than what it replaces (not just temporal word removed)?
Does it add value for a future maintainer?

If a rewrite just removes the temporal word without adding substance, it fails validation. Rewrite again with specific, descriptive content.

Gate: All rewrites pass quality checks. No vague or empty replacements. Proceed only when gate passes.

目标：生成具体、有价值的替换注释。

步骤1：起草重写内容

针对每个问题，生成：

markdown

**文件: `path/to/file.ext`**

第X行 - [注释类型]:
  当前内容:   // Authentication now uses JWT tokens
  建议内容: // Authenticates requests using signed JWT tokens
  原因:    "now uses"是时间性表述 - 仅描述当前行为

步骤2：验证重写质量

每个重写内容必须通过以下检查：

该注释在10年后仍有意义吗？
它是否解释了内容或目的，而非时间？
它比原注释更具体（不只是移除时间性词汇）？
它能为未来的维护者带来价值吗？

如果重写仅移除时间性词汇而未添加实质内容，则验证失败。需重新编写具体、描述性的内容。

检查点：所有重写内容通过质量检查。无模糊或空泛的替换内容。仅当通过检查点后进入下一阶段。

Phase 4: REPORT

阶段4：报告

Goal: Deliver structured, actionable report.

Step 1: Generate report

markdown

undefined

目标：交付结构化、可执行的报告。

步骤1：生成报告

markdown

undefined

Comment Quality Review

注释质量审查报告

Summary

摘要

Files scanned: N
Issues found: M
Most common pattern: [temporal word]

扫描文件数: N
发现问题数: M
最常见模式: [时间性词汇]

Findings

问题列表

[All findings with file, line, current text, suggested text, reason]

[所有问题，包含文件、行号、当前文本、建议文本、原因]

Recommendations

建议

Apply suggested changes
Consider adding linter rules for temporal language prevention


**Step 2: Apply fixes (if auto-fix enabled)**

If user requested auto-fix, apply all rewrites using Edit tool. Verify each edit succeeded.

**Gate**: Report delivered. All findings accounted for. Task complete.

---

应用建议的修改
考虑添加针对时间性语言的检查规则


**步骤2：应用修复（如果开启自动修复）**

如果用户请求自动修复，使用编辑工具应用所有重写内容。验证每个编辑是否成功。

**检查点**：报告已交付。所有问题已记录。任务完成。

---

Examples

示例

Example 1: Single File Review

示例1：单个文件审查

User says: "Check the comments in auth.go" Actions:

Scan only auth.go for temporal patterns (SCAN)
Read surrounding code for each finding, classify severity (ANALYZE)
Draft specific rewrites with WHAT/WHY focus (REWRITE)
Deliver report with file path, line, current, suggested, reason (REPORT) Result: Targeted report for one file with actionable rewrites

用户请求："检查auth.go中的注释" 操作：

仅扫描auth.go中的时间性模式（扫描阶段）
阅读每个问题的周边代码，分类严重程度（分析阶段）
起草聚焦内容与目的的具体重写建议（重写阶段）
交付包含文件路径、行号、当前内容、建议内容和原因的报告（报告阶段）结果：针对单个文件的定向报告，包含可执行的重写建议

Example 2: Pre-Release Documentation Audit

示例2：发布前文档审计

User says: "Audit all markdown files in docs/ before release" Actions:

Scan all .md files in docs/ directory (SCAN)
Classify findings, skip license headers and generated markers (ANALYZE)
Generate rewrites, validate each passes the 10-year test (REWRITE)
Deliver grouped report sorted by file, with summary statistics (REPORT) Result: Comprehensive audit with every finding addressed

用户请求："发布前审计docs/目录下所有markdown文件" 操作：

扫描docs/目录下所有.md文件（扫描阶段）
分类问题，跳过许可证头和生成标记（分析阶段）
生成重写内容，验证每个内容通过10年有效性测试（重写阶段）
交付按文件排序的分组报告，包含汇总统计（报告阶段）结果：全面审计，所有问题已处理

Example 3: Auto-Fix Mode

示例3：自动修复模式

User says: "Fix all temporal comments in pkg/api/ automatically" Actions:

Scan all code files in pkg/api/ (SCAN)
Analyze context for each finding (ANALYZE)
Generate and validate rewrites (REWRITE)
Apply fixes using Edit tool, verify each succeeded, deliver report (REPORT) Result: All temporal comments replaced in-place with verification

用户请求："自动修复pkg/api/目录下所有时间性注释" 操作：

扫描pkg/api/目录下所有代码文件（扫描阶段）
分析每个问题的上下文（分析阶段）
生成并验证重写内容（重写阶段）
使用编辑工具应用修复，验证每个编辑成功，交付报告（报告阶段）结果：所有时间性注释已被替换，并完成验证

Error Handling

错误处理

Error: "No Temporal Language Found"

错误："未发现时间性语言"

Cause: Files are clean or scope was too narrow Solution:

Verify common files were scanned (README, main source files)
Report clean results -- this is a valid positive outcome
Suggest expanding scope if user suspects issues exist elsewhere

原因：文件无问题或范围过窄解决方案：

验证是否扫描了常见文件（README、主源码文件）
报告无问题结果——这是有效的正面输出
如果用户怀疑其他位置存在问题，建议扩大范围

Error: "Too Many Results to Display"

错误："结果过多无法显示"

Cause: Large codebase with widespread temporal language Solution:

Prioritize by file importance (README first, then core modules)
Group findings by pattern type
Enable batch processing optional behavior

原因：大型代码库中广泛存在时间性语言解决方案：

按文件重要性排序（优先README，然后核心模块）
按模式类型分组问题
开启批量处理可选行为

Error: "Comment Meaning Unclear Without History"

错误："无历史上下文则注释含义不明确"

Cause: Comment only makes sense with development context that no longer exists Solution:

Read surrounding code to infer current purpose
If purpose is clear from code, suggest removing the comment entirely
If purpose is unclear, ask user for clarification before rewriting

原因：注释仅在有开发上下文时才有意义，而该上下文已不存在解决方案：

阅读周边代码推断当前用途
如果从代码中可明确用途，建议完全移除该注释
如果用途不明确，重写前询问用户以获取澄清

Anti-Patterns

反模式

Anti-Pattern 1: Scanning Entire Codebase Without Scope

反模式1：无范围限制扫描整个代码库

What it looks like: User asks "check comments in auth.go" and agent scans all 500 files Why wrong: Wastes tokens, produces overwhelming reports, ignores user's explicit request Do instead: Scan only what was requested. Ask before expanding scope.

表现：用户请求"检查auth.go中的注释"，而agent扫描了全部500个文件 错误原因：浪费token，生成冗余报告，忽略用户明确请求 正确做法：仅扫描用户请求的内容。如需扩大范围，先询问用户。

Anti-Pattern 2: Vague Rewrites That Remove Without Adding

反模式2：仅移除词汇而无实质内容的模糊重写

What it looks like:

// Updated error handling

becomes

// Error handling

Why wrong: Removing temporal word without adding substance produces a useless comment Do instead:

// Handles database connection errors with exponential backoff retry

表现：

// Updated error handling

变为

// Error handling

错误原因：仅移除时间性词汇而未添加实质内容，生成无用注释 正确做法：改为

// Handles database connection errors with exponential backoff retry

Anti-Pattern 3: Flagging Legal Text and Generated Markers

反模式3：标记法律文本和生成标记

What it looks like: Flagging

Copyright 2023-2024

as temporal language Why wrong: Copyright years are legal requirements; generated markers serve tooling Do instead: Skip license headers, @generated markers, and @deprecated tags

表现：将

Copyright 2023-2024

标记为时间性语言 错误原因：版权年份是法律要求；生成标记用于工具识别 正确做法：跳过许可证头、@generated标记和@deprecated标签

Anti-Pattern 4: Reporting Without Actionable Fixes

反模式4：仅报告问题而无修复建议

What it looks like: "Found 47 instances of temporal language" with no suggested rewrites Why wrong: Diagnostic-only reports create work without providing solutions Do instead: Every finding includes file path, line number, current text, suggested fix, and reason

表现："发现47处时间性语言实例"但未提供建议重写内容 错误原因：仅诊断的报告增加了用户工作量，未提供解决方案 正确做法：每个问题都包含文件路径、行号、当前文本、建议修复和原因

References

参考

This skill uses these shared patterns:

Anti-Rationalization - Prevents shortcut rationalizations
Verification Checklist - Pre-completion checks

本Skill使用以下共享模式：

反合理化 - 避免捷径式合理化
验证清单 - 完成前检查

Domain-Specific Anti-Rationalization

领域特定反合理化

Rationalization	Why It's Wrong	Required Action
"That temporal word is harmless here"	All temporal language ages poorly	Flag and rewrite it
"Removing the word is enough"	Removing without adding produces empty comments	Write specific replacement
"Legal text has dates too"	Legal text is not a code comment	Skip legal headers, flag code comments
"User only asked about one file"	Nearby files may share patterns	Report scope, suggest expansion if warranted

合理化理由	错误原因	要求操作
"此处的时间性语言无害"	所有时间性语言都会随时间失效	标记并重写
"移除词汇即可"	仅移除词汇会生成空泛注释	编写具体的替换内容
"法律文本也包含日期"	法律文本不属于代码注释	跳过法律头，标记代码注释
"用户仅询问了一个文件"	周边文件可能存在相同模式	报告当前范围，如必要建议扩大范围

Reference Files

参考文件

${CLAUDE_SKILL_DIR}/references/temporal-keywords.txt

: Complete list of temporal words to flag

```
${CLAUDE_SKILL_DIR}/references/examples.md
```
: Before/after examples of comment rewrites

${CLAUDE_SKILL_DIR}/references/anti-patterns.md

: Common problematic patterns with explanations

${CLAUDE_SKILL_DIR}/references/temporal-keywords.txt

: 需标记的时间性词汇完整列表

${CLAUDE_SKILL_DIR}/references/examples.md

: 注释重写的前后示例

${CLAUDE_SKILL_DIR}/references/anti-patterns.md

: 常见问题模式及解释