菜单
Adds high-signal code comments and docstrings that explain WHY (intent, invariants, gotchas) rather than restating WHAT, in the language's idiomatic doc format (JSDoc/TSDoc, Google/NumPy Python docstrings, rustdoc, godoc) — without over-commenting.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/Sir-chawakorn/sanook-cli --skill code-comments命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
Gets machine-parseable JSON out of an LLM reliably — prefer provider-enforced grammar (OpenAI `response_format:{type:"json_schema",strict:true}`, Anthropic tool-calling / `tool_choice:{type:"tool"}`, Gemini `responseSchema`) over a "respond in JSON" prompt, define the contract once as a Pydantic/Zod model and validate every response (never trust the string), use constrained decoding / grammars for open weights (Outlines, llguidance, llama.cpp GBNF, vLLM `guided_json`), keep schemas SHALLOW with required fields + enums + `additionalProperties:false`, and build a repair-and-retry loop that handles refusals, `length`/`max_tokens` truncation, and streaming partial JSON (`partial-json-parser`). Schema-guided generation eliminates parse-error retries; validate-and-repair is the backstop, not the primary mechanism.
Builds production data grids that stay fast and accessible at 10k–1M+ rows — decide server-side vs client-side sort/filter/paginate by the dataset-fits-in-memory test (client only under ~10k rows, otherwise push to the API and treat the table as a controlled view of server state), ROW-VIRTUALIZE with TanStack Virtual or react-window so only the visible window mounts (fixed estimateSize, overscan 5–10, measureElement for dynamic rows, contain:strict, and a real scroll container — never table-layout:auto over thousands of rows), build the headless logic with TanStack Table v8 (or AG Grid when you need pinning/grouping/enterprise out of the box), add column resize/reorder/pin, inline edit with optimistic update + rollback on error, row selection with a stable rowId, full keyboard nav with roving tabindex over an ARIA grid (role=grid/row/gridcell, aria-sort, aria-rowcount/aria-rowindex so virtualization stays announced), position:sticky headers, streaming CSV export that doesn't block the main thread, and explici
Builds semantic/vector search — pick an embedding model + dimensionality (and whether to truncate Matryoshka dims) and the matching distance metric (cosine/dot/L2, normalize to unit length so cosine == dot and IP is correct), an ANN index with the recall/latency/memory tradeoff understood (HNSW M/efConstruction/efSearch for low-latency RAM-resident; IVF-PQ nlist/nprobe/PQ for billion-scale compressed; flat/exact for <100k) in pgvector/Qdrant/Milvus/FAISS/Pinecone, chunking + overlap + per-chunk metadata for filtering, HYBRID retrieval fusing BM25 + dense by Reciprocal Rank Fusion (RRF, k≈60) not score addition, a cross-encoder/Cohere reranker over the top-50→k, correct pre-filter-vs-ANN interaction (filterable HNSW, not post-filter that starves k), and offline eval with recall@k / nDCG@10 / MRR against a labeled qrels set. Quantize (scalar/PQ) only after measuring recall loss; tune efSearch/nprobe to a recall target, not a guess.
基于 SOC 职业分类
正在显示 SKILL.md
| name | code-comments |
| description | Adds high-signal code comments and docstrings that explain WHY (intent, invariants, gotchas) rather than restating WHAT, in the language's idiomatic doc format (JSDoc/TSDoc, Google/NumPy Python docstrings, rustdoc, godoc) — without over-commenting. |
| when_to_use | User asks to comment/document a function, add docstrings, explain a tricky block, or prep code for handoff/review; legacy code with no comments. Not for prose docs (that's write-docs). |
write-docs.Read the full unit first. Read the whole function/module before writing a single comment. Trace data flow, error paths, and callers (grep for usages) so you comment real intent, not a guess. If intent is genuinely unrecoverable, write // FIXME: intent unclear — <specific question> instead of inventing a rationale.
Mark only the non-obvious. Tag lines/blocks where WHY ≠ WHAT: magic numbers, off-by-one guards, ret/ timeout / backoff constants, workarounds for upstream bugs, ordering that looks swappable but isn't, perf hacks, locking/concurrency assumptions, security checks. Skip anything a competent reader infers from the code itself.
Write the docstring in the language's idiomatic format. Use the existing convention in the file/repo if one is present (match it). Otherwise default to:
@param, @returns, @throws. Omit @param types in TS (the type is in the signature) — describe meaning/constraints/units instead.Args:/Parameters, Returns:, Raises:. Add Examples: (doctest-style) only for non-trivial contracts.///: summary, # Arguments (when non-obvious), # Errors, # Panics, # Safety for unsafe. # Examples should be compilable.// Foo does ...), full sentences, period-terminated.Put the signal in the docstring, not the body. Document: units (ms vs s, bytes vs KB), valid ranges, nullability, ownership/lifetime, side effects, thread-safety, idempotency, and what each error/exception actually means for the caller. These are the things callers can't see from the signature.
Inline comments only for surprising WHY. One line, above the code (not trailing, unless very short). Good: // Retry 3x — upstream returns 503 on cold start. Bad: // loop over items. Prefer # TODO(context) / # HACK: / # SAFETY: tags so they're greppable.
Delete redundant and stale comments you encounter. While editing, remove comments that restate code, are commented-out dead code, or contradict current behavior (stale comments are worse than none). Don't expand scope hunting the whole repo — just clean what's in your editing path.
Keep the diff comment-only. Zero logic, formatting, or whitespace changes beyond the comments themselves. The diff must be reviewable as "comments added/removed" and nothing else.
i++ // increment i, return user // return the user. If the comment is the code in English, delete it.FIXME: intent unclear) — a wrong comment is a future bug./** */ in Go. Match the file's existing style; if none, use the language default above.@param {string} name when the signature already says name: string — drift risk when the type changes. Describe meaning, not type.git diff shows only added/removed comment lines and docstrings; no logic, no reordering, no reformatting. If logic changed, revert it.tsc --noEmit, ruff/pydocstyle, cargo doc, go vet). Malformed docstrings (bad @param, broken rustdoc # Examples) must pass.pytest --doctest-modules, cargo test --doc).FIXME, not a guess.