К основному содержанию
правило CX Codex

typescript-doc-comments — правило для Claude Code

Правило typescript-doc-comments для написания документирующих комментариев в TypeScript по стандарту TSDoc. Помогает описать поведение и ограничения функций, типов и компонентов так, чтобы вызывающий код не ошибся.

MIT ★ 1 627 обновлён 2026-10-25

Установить в GitHub Copilot · Вручную: положить файлы Все способы и платформы ↓
.github/instructions/typescript-doc-comments.instructions.md
Открыть на GitHub

Что делает typescript-doc-comments

Правило задаёт, когда и как документировать экспортируемые функции, классы, интерфейсы, компоненты, хуки и тестовые помощники. Основной принцип: добавлять в комментарий только то, что нельзя вывести из имени и сигнатуры типа. TypeScript уже выражает типы параметров, возвращаемые значения и модификаторы — комментарий расказывает про поведение, единицы измерения, побочные эффекты, порядок вызовов, граничные случаи и обработку ошибок.

Правило охватывает реусуемые API: публичные функции, классы, типы, интерфейсы, перечисления, UI-компоненты, хуки, помощники для тестов. Не требует переписывать старые комментарии — применяется при добавлении или изменении кода. Описывает синтаксис: /** ... */ блок прямо над объявлением, краткая строка в начале, потом детали или @remarks, теги @param, @returns, @throws, @typeParam, @example, @deprecated только когда они добавляют информацию, не повторяют сигнатуру.

Правило работает с файлами *.ts, *.tsx, *.mts, *.cts и авторских деклараций (.d.ts, .d.mts, .d.cts). Не требует типизации в комментариях вроде @param {string} name — типы уже в коде.

Какие задачи решает

  • Документировать функции и типы так, чтобы вызывающий не ошибся
  • Выразить граничные случаи, единицы и побочные эффекты, которые не видны из сигнатуры
  • Описать порядок вызовов, закрытие ресурсов и обработку ошибок для асинхронных API
  • Избежать пустых или повторяющих сигнатуру комментариев
  • Привести документацию в соответствие со стандартом TSDoc

Примеры запросов агенту

  • Добавлю на функцию комментарий с граничными условиями для size параметра и поведением на пустом входе
  • Документирую React-хук с описанием побочных эффектов и того, когда колбэк срабатывает
  • Напишу @remarks с уточнением, что функция не мутирует входные данные и сохраняет порядок

Как установить typescript-doc-comments

Вручную: положить файлы

.github/instructions/typescript-doc-comments.instructions.md

Поле applyTo задаёт, к каким файлам применять

По шагам, с командами для каждой платформы: AGENTS.md и CLAUDE.md: что это, кто читает и какой выбрать

Вопросы о typescript-doc-comments

Как установить typescript-doc-comments в Claude Code?

Скопируй файл .claude/rules/typescript-doc-comments.md из репозитория в проект. Claude Code автоматически прочитает правило из директории .claude/rules и применит его при редактировании TypeScript-файлов.

Что документировать по этому правилу?

Экспортируемые функции, классы, интерфейсы, типы, компоненты, хуки, тестовые помощники. Пропусти рутинные колбэки, конфиг-экспорты, переэкспорты, константы с понятным названием и сгенерированный код. Документируй, если вызывающий может ошибиться без комментария.

Какие теги использовать, а какие пропустить?

Используй @param, @returns, @throws, @remarks, @typeParam, @example, @deprecated только если они добавляют новую информацию. Не пиши теги для модификаторов (@private, @readonly), типов (@param {string} name), пустые теги или теги, что повторяют имя параметра.

Исходный текст

typescript-doc-comments.instructions.md · MIT
---
description: 'Contract-focused TSDoc conventions for TypeScript. Use when adding or changing reusable functions, classes, types, components, hooks, props, callbacks, or test helpers'
applyTo: '**/*.ts, **/*.tsx, **/*.mts, **/*.cts'
---

# TypeScript Documentation Comments

Document what a caller needs to know that the name and the type signature cannot say. TypeScript already expresses parameter types, return types, optionality, and modifiers; documentation comments add behavior, constraints, and intent.

## Scope

* Applies to new or materially changed declarations in TypeScript source and authored declaration files (`.d.ts`, `.d.mts`, `.d.cts`).
* Does not require retrofitting comments onto unchanged declarations.
* Describes documentation content only. Types, tests, and review remain responsible for enforcing behavior.

## What to Document

Give every reusable API a concise summary, then add only the details callers cannot infer from its name and signature.

Reusable APIs include:

* Exported functions and helpers used beyond their own module
* Public classes, interfaces, type aliases, and enums, plus public members whose meaning or constraints are not self-evident
* Shared UI components and hooks
* Reusable test helpers, such as shared fixtures, page objects, and assertion or setup utilities used across test files
* Declarations in authored declaration files; a `.d.ts` suffix does not mean the file is generated

Document a private or module-local helper when its name and signature hide something a maintainer needs, such as an invariant, an ordering assumption, or a side effect.

The following need no documentation block unless they carry a non-obvious contract:

* Routine test callbacks, such as `describe`, `it`, and hook bodies, and mocks or stubs local to one test
* Tooling-only exports consumed by a framework or build tool, such as a configuration default export
* Re-export barrels; document the original declaration instead
* Constants whose name and value are self-describing, including any unit
* Generated or vendored code; change the generator or upstream source instead

When deciding, ask whether a caller could misuse the API without the comment. If not, skip it.

## Contract Content

Consider these facts and document each one that applies and is not already evident:

* Units and valid ranges, such as milliseconds versus seconds or positive integers only
* How relative paths, URLs, or identifiers are resolved
* Whether inputs, shared state, or the file system are mutated
* Ordering guarantees for returned collections or callback invocations
* What an empty or missing result looks like: an empty array, `undefined`, `null`, or an error
* Side effects such as network calls, file writes, logging, timers, or global state
* Timing: when a callback fires, whether work is deferred, debounced, or batched
* Resource ownership: who must close, dispose, or unsubscribe
* Failure conditions a caller is expected to handle or avoid

For asynchronous APIs, describe what the returned promise resolves to and when it rejects, rather than only stating that a promise is returned. Mention cancellation behavior when the API accepts an `AbortSignal`.

## Comment Syntax and Placement

* Place a `/** ... */` block directly above the declaration it documents. When the declaration has decorators, place the block above the first decorator. Leave only whitespace between the block and the decorators or declaration.
* Start with a one-sentence summary written from the caller's perspective. Do not restate the declaration name.
* Put longer explanation after the summary or under `@remarks`.
* Use `//` comments inside function bodies for implementation reasoning. Keep caller contracts in the documentation block, where editors surface them.
* Document props and callback options on the property declaration inside the interface or type, not as nested `@param props.name` entries on the component. When props are declared inline, describe the non-obvious ones in the component's comment; do not restructure types solely to host documentation.

## Tags

Tags are conditional. Use a tag when it adds information, and omit it when it would only repeat the name or type.

| Tag                          | Use when                                                                                      |
|------------------------------|-----------------------------------------------------------------------------------------------|
| `@param name - description`  | A parameter has a constraint, unit, default behavior, or meaning not evident from its name    |
| `@returns description`       | The result's meaning, ordering, ownership, empty case, or resolved promise value needs saying |
| `@throws description`        | A caller is expected to avoid or handle a specific error                                      |
| `@remarks`                   | Detail is too long for the summary paragraph                                                  |
| `@typeParam T - description` | A generic parameter has a role or constraint the signature does not convey                    |
| `@example`                   | Correct usage, call order, or setup is not obvious from the signature                         |
| `@deprecated description`    | The API is deprecated; name the replacement to use instead                                    |

Avoid these patterns:

* JavaScript-style type annotations such as `@param {string} name` or `@type`; TypeScript syntax already carries types
* Tags that duplicate modifiers, such as `@private`, `@readonly`, `@static`, `@abstract`, or `@async`
* Empty tags or descriptions that repeat the parameter name
* Treating `@throws` as an exhaustive or compiler-checked list; it documents the failures callers should know about

Release-stage tags such as `@public` or `@beta` follow the project's own documentation tooling policy; this guidance does not require them.

## Examples

A reusable helper documents the constraint, ordering, empty-input behavior, aliasing, and failure that its signature cannot express. The generic parameter needs no `@typeParam` because it has no special role, and `items` needs no `@param` because its description would only repeat the name.

<!-- <example-reusable-helper> -->
```typescript
/**
 * Splits items into consecutive batches of at most `size` elements.
 *
 * @remarks
 * Preserves input order and does not modify `items`. Each batch is a new array,
 * but its elements are the same references as in the input.
 *
 * @param size - Maximum batch length; must be a positive safe integer.
 * @returns Batches in input order, where only the last batch may be shorter.
 *   Returns an empty array when `items` is empty.
 * @throws A `RangeError` when `size` is not a positive safe integer.
 */
export function chunk<T>(items: readonly T[], size: number): T[][] {
  if (!Number.isSafeInteger(size) || size < 1) {
    throw new RangeError(`size must be a positive safe integer, received ${size}`);
  }

  const batches: T[][] = [];
  for (let start = 0; start < items.length; start += size) {
    batches.push(items.slice(start, start + size));
  }
  return batches;
}
```
<!-- </example-reusable-helper> -->

Props and callbacks carry their constraints on their own declarations, so every consumer of the type sees them.

<!-- <example-props-callbacks> -->
```typescript
/** Options for a list in which people can select rows. */
export interface SelectionProps {
  /** Maximum number of rows selected at once; further selections are ignored. Omit for no limit. */
  readonly maxSelected?: number;

  /**
   * Called after each user change to the selection, with row IDs in display order.
   * Receives an empty array when the last selected row is cleared. Not called for
   * the initial render.
   */
  readonly onSelectionChange: (selectedIds: readonly string[]) => void;
}
```
<!-- </example-props-callbacks> -->

A self-describing constant and a re-export barrel need no documentation block. The constant's name states its unit, and the re-exported declarations keep their documentation at their source. A constant whose unit or purpose is not evident from its name still needs a summary.

<!-- <example-no-comment-needed> -->
```typescript
export const REQUEST_TIMEOUT_MS = 30_000;

export { chunk } from './chunk';
export type { SelectionProps } from './selection';
```
<!-- </example-no-comment-needed> -->

## Keeping Comments Accurate

* Update or remove a comment in the same change that alters the behavior it describes.
* Before finishing, check each claim in a comment against the code: constraints, ordering, mutation, empty results, and documented errors.
* Document only behavior the implementation provides or the declared contract promises. Do not describe planned behavior.
* A documentation comment does not prove correctness. Tests and review verify behavior.

## References

* [TSDoc](https://tsdoc.org/) for tag syntax and semantics
* [JSDoc Reference in the TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html) for the distinction between documentation tags and JavaScript type annotations

© microsoft · MIT · microsoft/hve-core

Похожие правила IDE

Все правила IDE по теме «Код-ревью и рефакторинг» →
typescript-quality claude-dev-suite Скилл typescript-quality для Claude Code: настраивает ESLint, Biome и строгий tsconfig для TypeScript и JavaScript. Включается, когда в проекте расходятся типы и множатся правила линтера. CX Codex +1 1 100установок typescript PyModel С рекомендациями по типам и настройке TypeScript 7. Помогает разбирать tsconfig.json, сложные типы, асинхронный код и структуру модулей. CX Codex +1 657установок javascript-typescript-code-quality-cursorrules-pro PatrickJS Правило javascript-typescript-code-quality-cursorrules-pro задаёт стиль для JavaScript и TypeScript: простой, читаемый и тестируемый код с небольшими изменениями. Подходит для задач в Cursor. CX Codex +1 ★ 41 178звёзд репо jsdoc-typescript-docs patricio0312rev Скилл jsdoc-typescript-docs для Claude Code расставляет JSDoc-комментарии в TypeScript-коде и собирает из них документацию через TypeDoc. Закрывает функции, интерфейсы и типы без описаний. CX Codex +1 572установок Doc Bridge AgentsKit-io MCP-сервер Doc Bridge для Claude Code и Codex: собирает из документации репозитория контракт для агента — стартовый файл, список правимых файлов и команды проверок. Останавливает агента, когда тот лезет не в тот пакет. CX Codex +1 ★ 10звёзд репо doc-updater Affaan Mustafa doc-updater — субагент Claude Code, который синхронизирует документацию и карты архитектуры с кодовой базой. Обновляет устаревшие README.md и схемы. CX Codex ★ 6 739звёзд репо

Из того же набора148

Весь набор →
review-artifacts Правило review-artifacts для Claude Code сохраняет результаты код-ревью в согласованной структуре. Оно применяется к файлам в .copilot-tracking/reviews/code-reviews/. CX Codex +1 ★ 1 627звёзд репо customer-card-render Скилл customer-card-render превращает канонические markdown-артефакты Design Thinking в YAML-определения слайдов PowerPoint. Дальше их собирает в готовую презентацию общий пайплайн скилла powerpoint. CX Codex +1 ★ 1 627звёзд репо evaluation-design Скилл evaluation-design помогает составить тестовые датасеты и сопроводительные руководства для диалоговых агентов и RAG-систем. Задаёт вопросы по одному и фиксирует требования. CX Codex +1 ★ 1 627звёзд репо pester Правило задаёт соглашения для тестов PowerShell на Pester. Оно помогает Claude Code оформлять тестовые файлы и изолировать проверки по структуре репозитория. CX Codex +1 ★ 1 627звёзд репо engagement-reporting Скилл engagement-reporting формирует еженедельные отчёты о ходе проекта с опорой на первоисточники и создаёт черновики писем в Outlook. CX Codex +1 ★ 1 627звёзд репо hve-builder Скилл hve-builder помогает создавать и дорабатывать промпты, инструкции, агентов и другие скиллы. Он также проводит проверку качества или механическую валидацию без изменения файлов. CX Codex +1 ★ 1 627звёзд репо bash Правило задаёт единые конвенции для Bash-скриптов: strict mode, структуру с main(), форматирование, обработку ошибок и copyright-заголовки Microsoft. CX Codex +1 ★ 1 627звёзд репо incident-response Скилл incident-response помогает дежурным инженерам и SRE расследовать инциденты в Azure: оценивать критичность, писать диагностические запросы и готовить отчёты о причинах сбоя. CX Codex +1 ★ 1 627звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой