AGENT SKILL

no-comments

TSDoc とコメントを規約に沿って追加・整備する。新規関数・型の TSDoc 追加、既存コメントの改善に使用する。

License 许可
MIT
最近更新
2026-11-12
Stars
★ 0
Forks
0

01 前言 Front Matter

name
no-comments
description
TSDoc とコメントを規約に沿って追加・整備する。新規関数・型の TSDoc 追加、既存コメントの改善に使用する。

02 资源文件 1

03 SKILL.md 正文

TSDoc・コメント整備

指定されたファイル(またはディレクトリ配下の TypeScript ファイル)に対して、TSDoc とコメントを追加・改善する。


対象スコープの決定

引数 スコープ
ファイルパス そのファイルのみ
ディレクトリパス 配下の .ts / .tsx ファイル
なし git diff で変更されたファイル

基本方針

  • TSDoc は短く要点だけ(目安 3〜6 行)。
  • 関数内コメントは理由を書く(なぜその分岐や処理が必要か)。
  • オブジェクト周辺コメントは文脈を書く(値の意味、優先順位、未指定時の扱い)。
  • 既存コメントは整理対象(冗長なら短く、薄ければ補強)。
  • 挙動は変えない(コメント改善のみ)。

絶対ルール

  • TSDoc は /** ... */ を使う。
  • 日本語で書く。
  • コメントに型を書かない。
    • NG: @param {string} id / id: string
  • 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行だけ補足する(前提、検証観点、壊れやすい箇所)。

作業手順

  1. 対象ファイルを Read で読み込む
  2. 以下の観点でコメントを追加・改善する
    • export 関数: 目的: / 内容: / @param / @returns / @example を確認
    • 型定義: 役割と利用文脈のコメントを確認
    • 関数内: 分岐理由・早期 return 理由・副作用の明示を確認
  3. Edit ツールでコメントのみを変更する(コードの挙動は変えない)

作業後セルフチェック

  • TSDoc は短く保てているか。
  • TSDoc 本文に 目的: と 内容: があるか。
  • export 関数に @returns があるか。
  • export 関数に入力例/出力例が分かる @example があるか。
  • 関数内コメントに「判断理由」が書かれているか。
  • 型をコメントに書いていないか。

04 同仓库更多 Skills

seiei-sogen
seiei-sogen/agent-skills

why

「なぜ X はこの動きなのか」「なぜ Y を選んだのか」、設計の根拠説明、リグレッション、ポストモーテム、データに裏付けられたしきい値に使う。利用可能な MCP を発見し、各証拠カテゴリ(ソース管理、issue トラッカー、長文ドキュメント、リアルタイムチャット、インフラ可観測性、エラートラッキング、プロダクト分析ウェアハウス)を並列で問い合わせ、決定とトレードオフについて引用付きの読み解きを返す。実行時の振る舞いには how を使う。

★ 0
seiei-sogen
seiei-sogen/agent-skills

what-did-i-get-done

ユーザーが指定した期間に自分が作成したコミットを、簡潔な状況報告に要約する

★ 0
seiei-sogen
seiei-sogen/agent-skills

unslop

あらゆる文章から AI の痕跡を削る。常に適用しなければならない。

★ 0
seiei-sogen
seiei-sogen/agent-skills

typescript-best-practices

TypeScript のベストプラクティス。.ts または .tsx ファイルを読むか編集するときに使う。

★ 0
seiei-sogen
seiei-sogen/agent-skills

thermo-nuclear-code-quality-review

抽象化の質、巨大ファイル、スパゲッティ条件分岐の増殖について、極めて厳格な保守性レビューを行う。thermo-nuclear なコード品質レビュー、thermonuclear レビュー、深いコード品質監査、または特に厳しい保守性レビューに使う。

★ 0
seiei-sogen
seiei-sogen/agent-skills

technical-writing

階層化されたテクニカルライティング標準。Diátaxis の構造、Google developer style の文、STE の指示ルール、Global English の構文。/technical-writing、またはドキュメント、RFC、readme、PR の説明、コミットメッセージを書いたりレビューしたりするときに使う。

★ 0