ValentinNikolaev Clean Code Comments
Reduce comment noise while preserving intent, constraints, public contracts, tool directives, and non-obvious behavior.
Require an explicit scope
Accept one or more files or directories. If none are supplied, ask for them before editing.
Resolve relative paths from the repository root unless the user specifies another base. Resolve real paths and confirm every target remains inside the authorized scope and repository. Do not follow a symlink to edit content outside that boundary.
When the user requests --dry-audit, classify and report opportunities without editing files.
Capture the baseline
Before classification or editing:
- verify every target exists and identify file versus directory scopes;
- read repository and path-scoped instructions;
- record the starting commit,
git status --short, and the existing diff for target paths; - identify source languages, documentation rules, linters, formatters, generated markers, and tool-interpreted comments;
- inventory skipped binary, generated, vendored, third-party, minified, compiled, cached, and inaccessible files.
Treat pre-existing changes as user work. Never stash, reset, clean, overwrite, or “revert unrelated changes.” Undo only edits introduced by this task, using the recorded baseline to distinguish them.
Protect externally managed content
- Generated files: skip direct edits. Identify the authoritative source and generator. Edit or regenerate only when both are within the authorized task scope; ask before regeneration would write outside it.
- Vendored or third-party files: skip by default. Edit only when the user names the exact paths and explicitly confirms direct maintenance despite upstream overwrite risk.
- Minified, compiled, cached, or binary files: never rewrite for comment cleanup. Report them as skipped.
A broad parent-directory target is not explicit authorization to edit these categories.
Load the classification policy
Read references/comment-policy.md before classifying comments in both edit and dry-audit modes.
Consult references/examples.md only when a classification remains unclear after reading surrounding code and repository conventions.
Classify each candidate as preserve, remove, shorten, rewrite, skip, or question. Preserve when tooling, domain meaning, or operational importance remains uncertain.
Discover and inspect
Find source files within the resolved targets while respecting repository ignore rules. Do not rely only on directory names; inspect headers and repository configuration for generated or externally managed content.
Read enough surrounding code to determine whether a comment:
- merely narrates syntax or an obvious operation;
- explains intent, constraints, business behavior, or an invariant;
- documents a public contract required by the language or repository;
- is consumed by compilation, generation, linting, testing, documentation, or runtime tooling;
- belongs to a fixture, example, template, license, or migration artifact;
- remains accurate after nearby code changes.
Do not classify from comment text alone and do not infer authorship from writing style.
For large heterogeneous scopes, partition independent languages or modules without overlapping files. Keep baseline ownership, policy consistency, combined-diff review, and final validation with the main agent.
Apply focused edits
Allowed edits are limited to:
- removing comments that add no useful information;
- shortening useful but verbose comments;
- clarifying useful comments without changing meaning;
- removing clearly obsolete commented-out code outside fixtures and examples;
- adjusting whitespace directly caused by those edits.
Do not change behavior, symbols, public APIs, dependencies, tests, or architecture; invent rationale; add cleanup narration; or apply broad formatting.
Prefer removal over replacement when code is already clear. Preserve original language and project terminology in retained comments.
Review the task delta
Compare the final state with the recorded baseline and inspect only the delta introduced by this task. Confirm:
- every edited file is within the exact authorized scope;
- only comments and directly affected whitespace changed;
- directives, annotations, licenses, generated markers, and public documentation requirements remain intact;
- business, security, compatibility, concurrency, and operational context remains intact;
- no pre-existing user change was modified or attributed to this task;
- no formatter caused unrelated churn.
If an edit is unsafe, undo only that task-introduced hunk.
Validate narrowly
Run the narrowest documented checks available for edited files, such as a formatter check, parser or compilation check, static analysis, targeted tests, or documentation generation. Prefer check-only formatter modes; if formatting writes, restrict it to edited files and review its exact delta.
Request any command permission required by the host. Do not make unrelated code changes to repair pre-existing or environment failures.
Report
Return:
- resolved file and directory scopes;
- files inspected, changed, and skipped, with counts;
- categories removed, shortened, rewritten, or preserved;
- materially ambiguous comments intentionally preserved;
- baseline conflicts or pre-existing changes encountered;
- validation commands and results;
- confirmation that only task-introduced comment changes remain.
For --dry-audit, use stable IDs such as CCC-001 and include Disposition, location, current comment excerpt, rationale, and suggested classification. Do not enumerate every edit in normal cleanup mode unless requested.