القائمة
Use when writing new code or reviewing existing code to decide which comments to add, keep, or remove. Defines what makes a comment valuable vs. noise.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Invoke immediately if the Navigator mentions: inspecting changes (status, diff, log, show), staging/adding files (add, stage), creating commits (commit, amend, reset), branch management (branch, checkout, merge, rebase), remote operations (push, pull, fetch), or repository state (stash, worktree). Trigger words: git, commit, status, diff, add, stage, branch, merge, push, pull, log, revert, stash, worktree, 'what changed', 'save changes', 'commit this', 'show me the diff'.
Use when creating, updating, troubleshooting, or organizing Ubuntu GNOME dock buttons, .desktop launchers, Zenity control menus, script shortcuts, launcher icons, or taskbar actions for commands stored across multiple projects.
Use when investigating opencode sessions, subsessions, agent drift, missed handoffs, tool misuse, or feedback grounded in opencode session exports.
Guide a user with basic CSS knowledge who is learning Tailwind CSS and frontend styling. Use when the user asks for help styling a page, layout, component, tag, or UI state and wants coaching through style categories, good frontend practices, CSS mental models, or Tailwind decision-making without being given the finished code solution.
Use when investigating swap, memory pressure, compressor usage, llama.cpp memory, Metal/unified memory, or model-server RAM issues on the Mac Studio ai-server.
Run any question, idea, or decision through a council of 5 AI advisors who independently analyze it, peer-review each other anonymously, and synthesize a final verdict. Based on Karpathy's LLM Council methodology. MANDATORY TRIGGERS: 'council this', 'run the council', 'war room this', 'pressure-test this', 'stress-test this', 'debate this'. STRONG TRIGGERS (use when combined with a real decision or tradeoff): 'should I X or Y', 'which option', 'what would you do', 'is this the right move', 'validate this', 'get multiple perspectives', 'I can't decide', 'I'm torn between'. Do NOT trigger on simple yes/no questions, factual lookups, or casual 'should I' without a meaningful tradeoff (e.g. 'should I use markdown' is not a council question). DO trigger when the user presents a genuine decision with stakes, multiple options, and context that suggests they want it pressure-tested from multiple angles.
| name | code-comments |
| description | Use when writing new code or reviewing existing code to decide which comments to add, keep, or remove. Defines what makes a comment valuable vs. noise. |
| license | MIT |
| metadata | {"author":"Airton Ponce @ton-anywhere"} |
Comments exist to transfer knowledge that cannot be read from the code itself. A comment that restates what the code does is noise. A comment that explains why it does it — or warns of a non-obvious consequence — is essential.
A restart or deployment action is required. Initializers and certain config files require a server restart to take effect. Always include the restart warning at the top of those files:
# Be sure to restart your server when you modify this file.
The "why" is not derivable from the code. If a future developer would ask "why is this here?", the comment belongs. Examples:
An inline operation is opaque. Short inline comments on non-obvious expressions are acceptable:
trace_id = context.trace_id.unpack1('H*') # binary → hex string
A commented-out block is a deliberate template. If a block is commented out because it is optional or environment-specific (e.g. CSP policy, SSL enforcement, DNS rebinding protection), keep it so the path to activation is clear without requiring external research.
A security concern is present. Any configuration that filters sensitive data, enforces access control, or affects security posture should explain what it protects and why. Example: parameter filtering comments explaining partial-match behavior and the goal of limiting log dissemination.
A health or observability endpoint serves an infrastructure role. If a route or config is consumed by load balancers, uptime monitors, or tracing systems, say so explicitly.
The comment restates the code.
# Set version to 1.0 above config.assets.version = '1.0' adds nothing.
The information is authoritative elsewhere. Standard Rails environment config options, Puma DSL parameters, and RSpec setup prose are all documented in their official guides. Duplicating them in-file creates maintenance burden without adding value.
The comment is auto-generated boilerplate. Schema file headers, seeds file examples, and generator-output comments can be removed without loss.
The "why" is already obvious from context. Method names, variable names, and surrounding code often make intent clear. Don't add prose that a reader would reach without the comment.
require or configuration call.# === SCOPES ===): avoid in production code; acceptable in long test files only.Before writing or keeping a comment, ask: "Would a competent developer, reading only this repository, understand why this line exists without the comment?"