メニュー
コード変更に対して永続的なコメント（Why・制約・境界条件）を自動付与する。差分の依存グラフを解析し、2パス処理（意図マップ構築→役割別コメント生成）でレビュアーと将来の開発者の理解を助ける。「コメントを付けて」「アノテーションして」「レビューしやすくして」「comment annotation」と言われた時に使用する。
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
SOC 職業分類に基づく
| name | comment-annotator |
| context | fork |
| description | コード変更に対して永続的なコメント（Why・制約・境界条件）を自動付与する。差分の依存グラフを解析し、2パス処理（意図マップ構築→役割別コメント生成）でレビュアーと将来の開発者の理解を助ける。「コメントを付けて」「アノテーションして」「レビューしやすくして」「comment annotation」と言われた時に使用する。 |
コード変更に永続的なコメントを付与する。レビュアーと将来の開発者が「なぜこのコードがこうなっているか」を理解できる状態を作る。
コメントの根拠は現在のコードとテストが主軸。PR説明文やコミットメッセージは補助情報として使う。
Target Resolution → Pass 1: Intent Map → Pass 2: Role-Based Comments → Finalize
#123main..feature/xxxsrc/auth/handler.ts src/auth/types.tsgit branch --show-current で現在のブランチ取得git diff <base>...HEADgit diff + git diff --cached以下のファイルはコメント対象外:
変更の全体像を軽量に把握する。コメントはまだ書かない。
各変更ファイルを以下のいずれかに分類:
| 役割 | 判定基準 |
|---|---|
| entry | ルーティング定義、main関数、CLI entrypoint |
| controller | HTTPハンドラ、RPCハンドラ、イベントハンドラ |
| middleware | 認証・認可・ロギング・エラーハンドリング等の横断的関心事 |
| service | ビジネスロジック、オーケストレーション |
| domain | エンティティ、値オブジェクト、型定義 |
| repository | DB/外部API/ファイルI/Oアクセス |
| worker | バックグラウンドジョブ、キュー消費、定期タスク |
| migration | DBマイグレーション、データ変換スクリプト |
| utility | 汎用ヘルパー、共通関数 |
| config | 設定、定数、環境変数 |
| infra | CI/CD、Dockerfile、IaC、ビルド設定 |
| ui | UIコンポーネント、テンプレート、スタイル |
| test | テストファイル |
言語・フレームワーク固有のパターンで判定する。複数の役割にまたがるファイルは主要な役割を選ぶ。
変更ファイル + 1段階の依存先 + 1段階の呼び出し元 + 関連テスト
手順:
呼び出し元検出の注意:
暗黙的依存のチェック:
深掘り条件（2段階以上をたどる場合）:
変更されたシンボルのうち、他ファイルから参照されるもの（公開シンボル）に限定して要約:
Symbol: functionName(args) -> returnType
Purpose: [1文]
Changed: [今回の変更内容]
Constraints: [前提条件・不変条件・副作用、なければ省略]
以下のソースから変更の目的を1-3文で要約:
Pass 1 の意図マップを入力に、ファイルごとにコメントを付与する。
コードとテストから読み取れる事実だけを書く。
各役割で焦点を変える。コードの翻訳は書かない。
| 役割 | コメントの焦点 |
|---|---|
| entry / controller | この要求が何を達成するか、責務の切り替え点 |
| middleware | 適用条件、順序依存、スキップ条件 |
| service | 処理順序の理由、トランザクション境界、再試行・冪等性の前提 |
| domain | 不変条件、状態遷移ルール、禁止される状態 |
| repository | クエリの意図、パフォーマンス特性、障害時の挙動 |
| worker | 実行頻度、リトライ戦略、冪等性、障害復旧 |
| migration | 可逆性、データ変換ルール、ロック・ダウンタイムの有無 |
| utility | 境界条件、暗黙の前提、スレッドセーフ性 |
| config | 環境差異、変更時の影響範囲 |
| infra | 依存関係、実行順序、環境前提 |
| ui | 状態管理、ユーザー操作フロー、アクセシビリティ |
| test | 検証するシナリオ、何を保証し何を保証しないか、回帰防止の対象 |
ファイル処理時にコンテキストとして渡す情報:
コメント挿入後、以下を確認する:
Edit ツールで各ファイルにコメントを挿入する。変更完了後に以下のサマリを出力:
## Review Annotation Summary
### 変更意図
[1-3文の要約]
### 注目ポイント
- [レビュアーが特に確認すべき箇所と理由]
### 追加・更新したコメント一覧
| ファイル:行 | 役割 | コメント内容 |
|------------|------|-------------|
| src/auth/handler.ts:42 | controller | [コメント本文] |
| src/auth/rate-limit.ts:15 | service | [コメント本文] |
変更ファイルが20以上の場合:
| Reference | Purpose |
|---|---|
| references/comment-templates.md | 役割別の具体的なコメント例集（例文が必要な時に参照） |
デザインシステムの構築・運用を体系的に行うスキル。ドキュメント（要件定義・ブランドガイドライン）からDesign Tokens・コンポーネント体系・ガバナンスまでを一貫して設計する。思考フレームワーク（Double Diamond・Atomic Design・Design Tokens 3層）の適用、暗黙的デザイン判断の形式知化（DDR/QOC/RFC）、UIインベントリ収集（手動+MCP自動化）を統合する。ゼロから体系的に構築する用途向け。既存の単発UIから再利用可能な構造を抽出するにはrelational-design-pluginのdesign-system-backflowスキルを使用すること。Use when: 「デザインシステムを構築して」「デザインシステムを設計して」「デザイントークンを定義して」「デザイン原則を策定して」「UIインベントリを作って」「デザインガバナンスを設計して」「デザイン判断を記録して」と言われた時。
iOS/Androidモバイルアプリのデザインを体系的に行うスキル。Apple HIG・Material Design 3などプラットフォームガイドラインに準拠し、ナビゲーション・レイアウト・コンポーネント・モーション・アクセシビリティを適切に設計する。デザイン判断の観察・関係・仮説・撤回可能性をtraceとして残したい場合はrelational-design-pluginを使用すること。Use when: 「モバイルアプリをデザインして」「iOSアプリのUIを設計して」「Androidアプリの画面を作って」「モバイルのナビゲーションを設計して」「タッチUIを改善して」「アプリのアクセシビリティを対応して」と言われた時。
Webアプリの個別画面・コンポーネントのデザインを体系的に行うスキル。デザインプロセス・レイアウト・コンポーネント設計・インタラクション・アクセシビリティなどWebデザインの確立された手法を適用する。デザインシステム全体の構築・運用はdesign-system-builderスキルを使用すること。デザイン判断の観察・関係・仮説・撤回可能性をtraceとして残したい場合はrelational-design-pluginを使用すること。Use when: 「Webアプリをデザインして」「UIを設計して」「画面をデザインして」「レスポンシブ対応して」「アクセシビリティを改善して」「コンポーネントを設計して」「カラーパレットを決めて」と言われた時。
Use this skill when a design assumption, user segment, business goal, constraint, or product requirement has changed and you need to analyze which design hypotheses, decisions, artifacts, copy, or components should be retracted or revised. Requires a Relational Design trace session with recorded observations/relations/hypotheses/decisions to analyze against — not a general "redo this design" request.
Use this skill to critique an existing UI, frontend implementation, wireframe, flow, or visual design through Relational Design relations: user state, business intent, action risk, trust, information density, reversibility, accessibility, and implementation constraints. This is a relation-based critique, not a general design-methodology review — for platform-guideline or design-system compliance review, use design-plugin instead.
Use this skill after creating or reviewing a design artifact to extract reusable design-system knowledge: semantic tokens, components, variants, interaction rules, copy patterns, accessibility constraints, and governance notes. This only backflows structure out of an artifact that already exists — to build or govern a design system from scratch (Design Tokens layers, Atomic Design, DDR/QOC/RFC, UI inventory), use design-plugin's design-system-builder instead.