A set of rules for writing comments and other code documentation. It says to explain non-obvious reasons and constraints, rather than repeating what the code already shows.

Use it when adding or reviewing code comments, documenting workarounds, recording hidden constraints, or marking technical debt and edge cases.

It keeps code readable by preventing unnecessary comments, outdated history notes, and commented-out code. It also provides standard tags for bugs, planned work, and risks.

comments — Cursor rule for Cursor by afaraha8403/balakit

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

Clone the repo

git clone --depth 1 https://github.com/afaraha8403/balakit

Made for: Cursor.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

README.md

[![agentmods](https://agentmods.dev/badge/rules/afaraha8403/balakit/comments/github.svg)](https://agentmods.dev/rules/afaraha8403/balakit/comments)

Your own site

<a href="https://agentmods.dev/rules/afaraha8403/balakit/comments"><img src="https://agentmods.dev/badge/rules/afaraha8403/balakit/comments/github.svg" alt="Measured on agentmods" height="20"></a>

Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.

Your own site · 80×15

<a href="https://agentmods.dev/rules/afaraha8403/balakit/comments"><img src="https://agentmods.dev/badge/rules/afaraha8403/balakit/comments.svg" alt="Reviewed on agentmods" width="80" height="20"></a>

Per session 564 This file is loaded in full into every session.

When invoked 564 The same file — it is already loaded in full.

Security scan A 0 findings. A grade says what 26 rules found in the file — not that it is safe.

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5.1	$0.00564	$0.00564
Opus 5.5	$0.00226	$0.00226
Sonnet 5.5	$0.00113	$0.00113
Haiku 4.5	$0.00056	$0.00056

Measured 1mo ago against content hash b0e7a330a110, method: parsed. Prices are Anthropic first-party input rates as of 2026-10-07, from the pricing page.

Security

Grade A, and why

comments scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 1mo ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

.cursor/rules/comments.mdc · 55 lines

How it starts

The opening of the file, as written. The whole thing — 55 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Comments & Documentation

Default to zero comments

Names document code. Add an inline comment only when the WHY is non-obvious:

A hidden constraint not visible in the code.
A subtle invariant a reader might violate.
A workaround for a specific bug (link the upstream issue).
Behavior a competent reader would find surprising.

If removing the comment wouldn't confuse a future reader, delete it.

Never write

Restatements of the code — increment counter above counter++.
Task / ticket references — added for CAN-123, fixes billing bug.
Caller references — used by the contacts module.
Change history — was async before, removed old logic.
Commented-out code.
Banner comments — === SECTION ===.

Authorized Tracking Tags (Exception)

You MUST use the following authorized tags to track technical debt and risks (as required by the Global Rules), using your language's comment syntax. These should cleanly describe the issue for IDE tracking:

BUG: — For critical, immediate issues.
FIXME: — For broken code or technical debt needing refactor.
TODO: — For general planned work.
CONCERN: — For edge cases or architectural risks.
OPTIMIZE: — For performance improvements or clean-up tasks.

Document every exported symbol

Every part of a module's public surface — exported functions, types, classes, constants — gets a documentation comment in your language's convention (doc comment, docstring, etc.). Internal/private helpers only get one when the WHY is non-obvious.

The first line is a one-sentence summary ending with a period.
Document a parameter only when its name isn't self-explanatory. Never restate information the signature already carries (e.g. the type, in a typed language).
Document the return only when it isn't obvious from the function name.
Document every error/exception the function can raise as part of its contract.
Add an example for non-trivial public APIs and shared utilities.
Don't duplicate what the language already expresses — let the type system, signatures, and tooling do their job.

Read the full file on GitHub · 55 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

1mo ago First seen · 55 lines · 564 tokens per session scan A b0e7a330a110

Subscribe to this mod's changes

comments is a cursor rule published in the GitHub repository afaraha8403/balakit (1 stars, last pushed 1mo ago), licensed MIT. It adds 564 tokens to every session, about $0.0023 per session on Opus 5.5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.

Claude Code Writing and docs agent-rules agent-skills agents-md ai-agents claude

skill-creator

Create, edit, evaluate, and debug the skills in this repo, including running their evals and fixing a description that fails to trigger. Use when user says 'help me build a new skill', 'add a skill for X', 'run the evals for the tf skill', 'run the behavioral evals', 'my skill is not triggering', 'fix this skill's…

anmolnagpal/devops-skills · 7,458 tokens

file-organization

Project file and folder organization patterns.

coco-research/coco · 6 tokens

skill-router

Use before starting any task in Cursor to check whether a skill file must be read first. Routes PRD, test-writing and code-verification tasks to the skill path to read before writing code.

coco-research/coco · 303 tokens

tf-plan

Review a Terraform plan before applying it: destroys and replacements of data-bearing resources, secrets readable in plan output, out-of-band drift, blast radius, and whether the apply is bound to the plan you actually reviewed. Use when user says 'review my plan', 'is this plan safe to apply', 'check tfplan', 'what…

anmolnagpal/devops-skills · 4,196 tokens

clarify-first

Infer-and-act by default — ask only on high confusion weight, after inspecting, with a decision-linked question.

madebyaris/cursor-composer-rules · 21 tokens

composer-senior-practices

Version-pinned framework guidance from primary docs when building on unfamiliar stacks, upgrading, or reviewing architecture — load when evidence beats training data; not required for routine feature work.

madebyaris/cursor-composer-rules · 33 tokens