no-comments
TSDoc とコメントを規約に沿って追加・整備する。新規関数・型の TSDoc 追加、既存コメントの改善に使用する。
- License 许可
- MIT
- 最近更新
- 2026-11-12
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- no-comments
- description
- TSDoc とコメントを規約に沿って追加・整備する。新規関数・型の TSDoc 追加、既存コメントの改善に使用する。
02 资源文件 1
- 参考文档agents/openai.yaml43 B
03 SKILL.md 正文
TSDoc・コメント整備
指定されたファイル(またはディレクトリ配下の TypeScript ファイル)に対して、TSDoc とコメントを追加・改善する。
対象スコープの決定
| 引数 | スコープ |
|---|---|
| ファイルパス | そのファイルのみ |
| ディレクトリパス | 配下の .ts / .tsx ファイル |
| なし | git diff で変更されたファイル |
基本方針
- TSDoc は短く要点だけ(目安 3〜6 行)。
- 関数内コメントは理由を書く(なぜその分岐や処理が必要か)。
- オブジェクト周辺コメントは文脈を書く(値の意味、優先順位、未指定時の扱い)。
- 既存コメントは整理対象(冗長なら短く、薄ければ補強)。
- 挙動は変えない(コメント改善のみ)。
絶対ルール
- TSDoc は
/** ... */を使う。 - 日本語で書く。
- コメントに型を書かない。
- NG:
@param {string} id/id: string
- NG:
- TSDoc 本文の先頭に
目的:と内容:を必須で書く。目的:その関数/型が必要な理由を1文で書く。内容:何をするか(または何を保持するか)を1文で書く。
- export される関数には
@returnsを必須で付ける。 - export される関数には入力例と出力例が分かる
@exampleを必須で付ける。- 形式は簡潔でよい(
入力:/出力:の2行で可)。
- 形式は簡潔でよい(
- 曖昧語(「適切に」「必要に応じて」「よしなに」など)は使わない。
TSDoc の最小テンプレート(関数)
/**
* 目的: この関数が必要な理由を1文で書く。
* 内容: 何をするかを1文で書く。
* @param value 入力値の意味と制約を書く。
* @returns 返り値の意味と失敗時の扱いを書く。
* @example
* 入力: `normalize(" user-001 ")`
* 出力: `"user-001"`
*/
タグ運用
@param: 型ではなく「意味・制約・空値時の扱い」。@returns: 必須。返り値の意味、nullやfalseを返す条件を明記。@example: 必須(export 関数)。入力例と出力例を最短で示す。@throws: 呼び出し側が対処すべき例外がある場合のみ。- 不要なタグは増やさない。
型・オブジェクトコメント方針
interface/typeの先頭に、役割と利用文脈を1〜2文で書く。- プロパティには必要に応じて以下を補足する。
- 値の意味
- 未指定時の扱い
- 他プロパティとの優先順位や関係
- 設定オブジェクトやマッピングは、定義直前に「なぜこの形か」を1〜2行で書く。
関数内コメント方針(丁寧寄り)
- 段階ごとに短い見出しコメントを入れる(前処理 / 検証 / 実行 / 後処理)。
- 早期 return / throw には停止理由を書く。
- ループは「何を抽出・集計しているか」を書く。
- DB更新、外部API呼び出し、ログ出力は副作用として明示する。
- コードの言い換えだけのコメントは書かない。
テストコメント方針
describe/itは「何を・条件・結果」が分かる日本語名にする。- 必要ならテスト本体へ1〜2行だけ補足する(前提、検証観点、壊れやすい箇所)。
作業手順
- 対象ファイルを Read で読み込む
- 以下の観点でコメントを追加・改善する
- export 関数:
目的:/内容:/@param/@returns/@exampleを確認 - 型定義: 役割と利用文脈のコメントを確認
- 関数内: 分岐理由・早期 return 理由・副作用の明示を確認
- export 関数:
- Edit ツールでコメントのみを変更する(コードの挙動は変えない)
作業後セルフチェック
- TSDoc は短く保てているか。
- TSDoc 本文に
目的:と内容:があるか。 - export 関数に
@returnsがあるか。 - export 関数に入力例/出力例が分かる
@exampleがあるか。 - 関数内コメントに「判断理由」が書かれているか。
- 型をコメントに書いていないか。
04 同仓库更多 Skills
why
「なぜ X はこの動きなのか」「なぜ Y を選んだのか」、設計の根拠説明、リグレッション、ポストモーテム、データに裏付けられたしきい値に使う。利用可能な MCP を発見し、各証拠カテゴリ(ソース管理、issue トラッカー、長文ドキュメント、リアルタイムチャット、インフラ可観測性、エラートラッキング、プロダクト分析ウェアハウス)を並列で問い合わせ、決定とトレードオフについて引用付きの読み解きを返す。実行時の振る舞いには how を使う。
what-did-i-get-done
ユーザーが指定した期間に自分が作成したコミットを、簡潔な状況報告に要約する
unslop
あらゆる文章から AI の痕跡を削る。常に適用しなければならない。
typescript-best-practices
TypeScript のベストプラクティス。.ts または .tsx ファイルを読むか編集するときに使う。
thermo-nuclear-code-quality-review
抽象化の質、巨大ファイル、スパゲッティ条件分岐の増殖について、極めて厳格な保守性レビューを行う。thermo-nuclear なコード品質レビュー、thermonuclear レビュー、深いコード品質監査、または特に厳しい保守性レビューに使う。
technical-writing
階層化されたテクニカルライティング標準。Diátaxis の構造、Google developer style の文、STE の指示ルール、Global English の構文。/technical-writing、またはドキュメント、RFC、readme、PR の説明、コミットメッセージを書いたりレビューしたりするときに使う。