AGENT SKILL

no-comments

Code comments judged against a keep list. Use when adding or changing code comments, or when asked to remove comments.

License 许可
MIT
所属仓库
syanga/astack
最近更新
2026-11-14
Stars
★ 0
Forks
0

01 前言 Front Matter

name
no-comments
description
Code comments judged against a keep list. Use when adding or changing code comments, or when asked to remove comments.

02 资源文件 1

03 SKILL.md 正文

Delete the comments

During other work, check only the comment text you write against the keep list. Leave every existing comment the request does not name as it is, even one this skill would delete or your new comment makes redundant. Mention such a comment in your reply instead. When the user asks to remove comments, or a workflow tells you to apply this skill, run the whole procedure below.

Delete every comment in scope that is not on the keep list. Flag the code that needed a comment to be understood, then fix what the flags name. A flag is one line in the report naming a symbol that needed a comment. Every flag names code inside the scope and tells the truth.

Scope

Use the files or diff the caller names. With no caller scope, use the current diff against the base branch, main by default, including the working tree.

Keep list

Only these comments survive. Each of the first four survives only with proof that it concerns something outside this repository or a contract this repository publishes. The last two need the lookups they describe:

  • A legal or license header.
  • Behaviour forced by an external dependency, platform, vendor, or protocol we cannot change. Behaviour a reader would not expect from the names and types in our own code does not qualify. Delete that comment and flag the symbol.
  • A doc comment that defines a public API contract.
  • An issue or RFC link that explains a constraint the code cannot express.
  • // prettier-ignore, and a lint or type suppression whose rule is faulty, pedantic, or style-only. Look up the rule for every eslint-disable, @ts-ignore, @ts-expect-error, and similar suppression in scope, including the ones you did not write. If the rule catches real bugs or protects correctness or safety and the next entry does not keep the suppression, delete it and flag the symbol.
  • A suppression that the repository's agent rule table, in AGENTS.md or else CLAUDE.md, records as an approved exception for that file and rule, with an approver and an expiry date that has not passed.

When unsure whether a keep-list entry applies, delete the comment.

Delete these

Delete the whole comment rather than shortening it.

  • Narration, banners, commented-out code, and workaround justifications. In a test or verify script the assertion message documents the step.
  • A claim comment, such as IMPORTANT, too risky, or fine for now, and any long justification. A claim is not proof. Read the nearby code, run git log -L <start>,<end>:<file> on the lines, and read the PR that introduced the comment. The history decides whether the claim is still true on a live path. A claim that is still true and matches a keep-list entry stays. Anything else goes.
  • A constraint comment, such as do not remove, do not change wording, or talk to X before changing. First apply the keep-list test above. When the constraint concerns something we can change, offer the cheapest in-scope type, runtime check, test, or lint, local or CI, that encodes it, and wait for the user's approval. Unattended, treat it as not approved. If approved, encode the constraint, then delete the comment. Otherwise delete the comment, report the constraint open, and sketch the encoding.

Fix what the flags name

Delete the dead path, drop the unused parameter, or call the real API. When two or more flags need the same fix, sketch the new structure once, over the flagged code and its surroundings, before writing code. Make the smallest root-cause fix in scope and remove every named workaround. fix-root-causes.md and redesign-from-first-principles.md guide the intent. Both stay inside the scope. Neither allows fixes in other files. An out-of-scope root cause gets the smallest in-scope fix and a note.

Report

Report these:

  • the files touched
  • the number of comments deleted
  • each comment kept, with its keep-list entry
  • each flag, in one line
  • each fix made, and each flag left open with its note
  • the sketch, if there was one
  • the encodings offered and made
  • the constraints left open
  • other open work

Done when every comment in scope is deleted or matched to a keep-list entry, every flag is fixed or reported open, and the report carries each item above.

04 同仓库更多 Skills