Update Checklist

checklist.yaml 差分更新 SKILL

このスキルについて

index.mdx の変更に応じて、既存の checklist.yaml を差分更新する手順書。新規生成（generate-checklist SKILL）と異なり、人間レビューで確定済みの項目（severity・text・sub_items・note）を保護しつつ、変更が必要な項目のみを更新する。

関連プロンプト・SKILL の役割分担

• .github/prompts/generate-checklist.md: ルール抽出方法の詳細仕様（抽出対象・除外パターン・見出し処理・sub_items 判別・severity 推測・Do/Don't 変換）。新規項目の抽出はこのプロンプトを参照する。
• .github/prompts/update-checklist.md: 既存 checklist.yaml と再抽出結果の突き合わせ・差分マージ方法に専念。Layer 2 除外方針も含む。
• 本 SKILL: スキップ判定・親ページの扱い・severity 横串確認・Layer 1 重複チェック・文体パターン等の 運用判断 を担う。

前提条件

• 既存 checklist.yaml の確認: src/content/articles/products/components/<dir>/checklist.yaml
• ディレクトリ名解決: src/content/articles/products/components/ 配下を直接探索する（コンポーネント名を kebab-case 化したディレクトリ名。ネストする場合あり）
• 参考例: src/content/articles/products/components/button/checklist.yaml

更新フロー

Step 1: 対象を特定

依頼文から対象コンポーネントを抽出。複数指定可。コンポーネント名 → ディレクトリ名の解決は src/content/articles/products/components/ 配下を find / glob で探索する（コンポーネント名を kebab-case 化したディレクトリ名。ネストする場合あり）。

Step 2: 入力を読み込む

各対象について以下を読む。

• 変更後の index.mdx
• index.mdx から import されている .mdx（_components/*.mdx 等）
• 既存の checklist.yaml（更新前の確定版）
• eslint ルール名一覧: .github/data/eslint-rule-names.txt

Step 3: スキップ判定（更新後の index.mdx で再評価）

index.mdx の変更内容によっては、既存 checklist.yaml ごと不要になる場合がある。以下のパターンに該当するか再評価する。

スキップになりやすいパターン:

• Every Layout 外部委譲: Stack / Cluster / Center / Sidebar / Reel 等。機能説明のみで指示文がない
• 索引のみの親ページ: Combobox 親、Dropdown 親。子コンポーネントへのリンク集のみ
• 機能説明のみ: SectioningContent 等。「〜できます」の記述はあるが Do/Don't がない
• 自動挙動・props 規約のみ: AppHeader 等。「props を渡すと自動で〜になる」「props に入れる内容のフォーマット規約」のみ
• deprecated 指定: frontmatter に deprecated: true がセットされているコンポーネントは deprecatedMessage で代替を示すため checklist.yaml 不要 (例: AppLauncher)
• description で十分カバーされる内容: 「〜の場合に使う」「〜の場合は使わない」が description と重複している場合 (例: Header / Calendar / LanguageSwitcher / Disclosure)
• mdx 冒頭の見出しなし説明文に規定が含まれ Layer 1 でカバーされる場合: 冒頭文がそのまま Layer 1 として SKILL.md に取り込まれるため、Layer 3 に入れると重複する

スキップ判定の例外（1 項目でも残すべきケース）:

• a11y 必須ルール: アクセシブルな名前付与・代替テキスト等 (例: Badge のドット表示時のアクセシブル名)
• レイアウト判断ルール: 他コンポーネントとの組み合わせ判断 (例: SpreadsheetTable の Reel 組み合わせ)

スキップが妥当と判断したら、既存項目をすべて削除する旨を報告して更新を打ち切る。

Step 4: 差分マージ案を作成

.github/prompts/update-checklist.md のステップ 0〜4 に従う。要点:

• 既存項目は極力維持: severity・text・sub_items・note を上書きしない
• 変更が必要な項目のみ更新: index.mdx の変更に影響を受ける項目を特定
• 新規項目は severity を提案: 既存項目の severity パターンを参照して整合性を取る
• 削除が必要な項目を明示: index.mdx から削除された記述に対応する項目は削除
• Layer 2 でカバー済みの項目は除外: eslint ルール名と意味的に一致するものは出力に含めない
• ハルシネーション禁止: mdx に書かれていない知識は使わない。リンク先も辿らない

Step 5: 運用観点のセルフレビュー

差分マージ案を出力する前に、運用観点で精査する。

5-1. 各新規項目の精査

新規項目に対して以下を自問する。Yes が出たら削除候補としてマークする。

• これは smarthr-ui の自動挙動の説明か？（props を渡すと自動で〜になる、等）
• これは props 規約のフォーマット指定のみか？（実装者の判断材料を含まないか）
• description で同等内容が既に言及されているか？

5-2. severity 横串確認

新規項目および severity 提案を含む項目について、特徴的な表現（「モーダルに表示します」「を使わない」等）を、既存の checklist.yaml で検索する。

grep -r "<特徴的な表現>" src/content/articles/products/components/**/checklist.yaml

同じ表現に異なる severity が当たっていれば整合性を取る（例: 「モーダルに表示します」は FilterDropdown も SortDropdown も must）。

5-3. 文体パターンの検知

新規項目・更新項目に対して以下を確認する。

• 「適していません」「不適切」等の否定的事実記述に must が当たっていないか → avoid に変更検討
• 「〜を推奨します」「〜が望ましい」を text にそのまま入れていないか → 「検討してよい」表現に変更
• text にパターン名（「パターン A」等）が含まれていないか → source_section と重複するため除去
• 同見出し下の avoid + 代替ペアが分離していないか → 1 項に統合
• sub-mdx 由来の項目に via xxx.mdx 表記があるか
• WIP モバイルルールに note: "smarthr-ui未実装（モバイル対応時に有効化）" が付いているか

Step 6: 変更内容をレポート

人間レビューに渡す前に、以下を明示する。

• 追加項目（severity 提案理由を併記）
• 削除項目（削除理由として該当 mdx 記述の削除箇所を併記）
• 更新項目（変更前 → 変更後の diff、変更理由）
• Layer 2 でカバー済みのため除外した項目（該当 eslint ルール名を併記）
• 無変更で維持した項目数

Step 7: バリデーション

pnpm --filter ./scripts/generate-skills validate

error がないことを確認。warn は内容に応じて対応。

Step 8: Layer 1 重複チェック

Layer 3 に入れようとしている項目が Layer 1（mdx 冒頭の説明文）と重複していないか確認する。mdx 構造から事前に予測でき（短い「冒頭説明 + props」構造のコンポーネントで重複しやすい）、重複する項目は checklist.yaml から削除する。ErrorScreen 子のように mdx 冒頭の見出しなし説明文がそのまま Layer 1 に取り込まれるケースで起きやすい。

反映結果を手元で確認したい場合のみ、リポジトリルートから pnpm --filter ./scripts/generate-skills generate を実行し、生成された plugins/smarthr-design-system/skills/component-guidelines/components/<PascalCase>.md の Layer 1 部分と突き合わせる（生成物はコミットしない）。

成果物とコミット

この SKILL の成果物は更新後の checklist.yaml のみ。コミット対象は checklist.yaml だけで、コンポーネントガイド（plugins/...）への反映はマージ後に CI（generate-skills.yml）が自動実行する。ローカルで pnpm generate を実行して生成物をコミットする必要はない。

やってはいけないこと

• 既存項目を「より良い表現」に書き換える（人間レビュー済みの確定値）
• mdx 差分外の既存項目に手を入れる
• 元資料にないルールを創作する
• リンク先（外部 URL や別 mdx）を辿って情報を取り込む
• フィールド順を変える（severity → text → source_section → sub_items → note を維持）
• Layer 2 でカバーされる項目を note 付きで出力に残す（generate-checklist と方針統一）
• mdx 差分と無関係に note の内容だけを理由に既存項目を削除・変更する（note 付き項目の扱いに疑問があれば、削除せず人間に報告して確認を取る）

よくある判断パターン