Managing Frontend Knowledge

フロントエンドナレッジ管理

概要

フロントエンド技術のナレッジベースを管理するスキル。3つの主要機能を提供:

1. 実装時の自発的参照（最優先）: Web開発の実装タスク時にナレッジベースを参照し、ベストプラクティスを適用して作業の精度と速度を向上
2. 収集・蓄積: URLや記事からフロントエンド技術を要約してナレッジベースに追加
3. 参照・回答: 蓄積されたナレッジベースから質問に関連する情報を検索して回答

使用場面

実装タスク時の自発的参照（最優先）

• Web開発の実装タスク（コンポーネント作成、レイアウト実装、アニメーション実装など）
• コーディング作業時のベストプラクティス適用
• 最新のCSS/JavaScript機能の活用
• アクセシビリティやパフォーマンスへの配慮

トリガー: ユーザーからの実装依頼、コード作成タスク、機能追加など

収集モード

• URLが渡された場合: 「この記事を保存して」
• 記事内容の追加: 「ナレッジに追加して」
• ナレッジ整理: 「ナレッジを整理して」

参照モード（質問対応）

• フロントエンド技術の質問
• CSS、JavaScript、パフォーマンス、アクセシビリティに関する質問
• 蓄積されたナレッジに基づく回答が必要な場合

パート1: ナレッジ収集・蓄積

実行モード

1. 追加モード（デフォルト）

• URLが渡された場合
• 「この記事を保存して」「ナレッジに追加して」等の依頼

2. 整理モード

• 「ナレッジを整理して」「重複を確認して」等の依頼
• 特定カテゴリの整理: 「css-layout.md を整理して」

収集フロー

Step 1: コンテンツ取得

URLが渡された場合は WebFetch で内容を取得。

Step 2: 要約・構造化

人間が直接参照できるデータ集として、以下を意識:

• 専門用語には簡潔な説明を添える
• コード例は実際にコピペして使えるレベルに
• 「なぜこの方法が良いのか」の理由を明記
• ブラウザサポート状況は具体的に記載

以下のフォーマットで要約：

## [テクニック名]

> 出典: [URL]
> 執筆日: [YYYY-MM-DD]（記事の公開日・更新日。不明な場合は「不明」）
> 追加日: [YYYY-MM-DD]

[1〜3文で概要を説明]

### コード例

\```css
/* または js/html */
[実用的なコード例]
\```

### ユースケース
- [具体的な使用場面1]
- [具体的な使用場面2]

### 注意点
- [ブラウザサポート、制限事項など]

---

Step 3: カテゴリ判定

以下のカテゴリから最適なものを選択（新しい階層構造）：

Step 4: 重複チェックと処理方針の決定

重要: ナレッジ追加前に必ず既存ナレッジとの重複をチェックする。

4-1. 既存ナレッジの検索

以下のコマンドで該当トピックの既存ファイルを検索：

# キーワードで検索（例: Container Query）
find knowledge -type f -name "*.md" | xargs grep -l "container.*query\|@container"

# ファイル名で検索
find knowledge -type f -name "*container*"

4-2. 処理方針の決定

4-3. 古い情報の判断基準

以下の場合は「古く有用でない」と判断し、ナレッジ化しない：

• ブラウザサポートが終了した技術（例: IE11専用のハック）
• 非推奨になった API/構文（公式ドキュメントで deprecated）
• より良い代替手段がある古い手法（例: Polyfill が不要になった機能）
• セキュリティ上の問題がある実装
• 5年以上前の記事で、現在の標準と乖離している内容

ただし、以下は例外的に保存：

• 歴史的価値のある情報（「なぜこの書き方が避けられるようになったか」の理解）
• レガシーコード保守に必要な情報（明示的に「レガシー」とタグ付け）

4-4. 分割と統合の判断

分割すべき場合:

• 1つのファイルが500行を超える
• 複数の独立したトピックが含まれる
• 異なるカテゴリに属する情報が混在

統合すべき場合:

• 同じトピックが複数ファイルに分散している
• 内容が薄い複数ファイルを1つにまとめた方が理解しやすい
• 相互に強く関連するトピック（例: Container Query と Container Query Units）

Step 5: ファイル更新

1. ~/.claude/skills/managing-frontend-knowledge/knowledge/[カテゴリ]/[ファイル名].md を Read
2. 処理方針に従って更新：
   • 新規: Write ツールで新規ファイル作成
   • 追記: Edit ツールで既存ファイルの末尾に追加
   • 更新: Edit ツールで既存セクションを置き換え
   • 統合: 複数ファイルの内容を統合して1つのファイルを作成
3. ファイルが存在しない場合は新規作成し、YAML frontmatterを追加
4. YAML frontmatter形式:

   ---
   title: タイトル
   category: css/layout (カテゴリパス)
   tags: [タグ1, タグ2, タグ3]
   browser_support: ブラウザ対応状況
   created: YYYY-MM-DD
   updated: YYYY-MM-DD
   ---
   

Step 6: 確認

追加完了後、以下を報告：

• 追加したテクニック名
• 保存先カテゴリ
• 要約内容のプレビュー

複数テクニックを含む記事の場合

1つの記事に複数のテクニックがある場合：

• 各テクニックを個別エントリとして追加
• 同じ出典URLを記載
• 関連がある場合は相互参照を記載

複数カテゴリにまたがる記事の場合

記事の内容が複数のカテゴリに関連する場合は、無理に1つのファイルに押し込めない。

分割の判断基準

分割時のルール

1. 各ファイルで自己完結させる: そのファイルだけ読んでも理解できるように
2. 重複は最小限に: 共通部分は概要のみ、詳細は適切なカテゴリで
3. 相互参照を明記: 関連ナレッジへのリンクを必ず記載

分割例

例: 「アクセシビリティを考慮したアニメーション実装」という記事

accessibility-link-underline.md:
  - prefers-reduced-motion の必要性と判定方法
  - 関連: css-animation.md の「モーション軽減対応」

css-animation.md:
  - モーション軽減対応のCSS実装パターン
  - 関連: accessibility-link-underline.md の「prefers-reduced-motion」

報告フォーマット

✅ ナレッジを追加しました（2カテゴリに分割）

📁 accessibility-link-underline.md
   📝 prefers-reduced-motion の考慮

📁 css-animation.md
   📝 モーション軽減対応パターン

🔗 相互参照を設定済み

類似ナレッジの検出と統合（追加時）

追加前に既存ナレッジとの類似性を確認：

チェック項目

1. 同一URL: 既に存在する場合は更新として扱う
2. 類似テクニック: 同じ概念・機能を扱っている場合

類似が見つかった場合のアクション

• 矛盾なし: 既存エントリに統合して強化
• アップデート: 新情報で既存を更新（旧情報は「以前の方法」として残す場合あり）
• 矛盾あり: 両論併記し、推奨を明示
• 別観点: 別エントリとして追加（相互参照を記載）

統合時の報告

🔄 類似ナレッジを検出・統合しました

既存: 「CSS Grid の基本」（執筆: 2023-06）
新規: 「Grid Layout 実践ガイド」（執筆: 2024-08）

→ 統合: 「CSS Grid レイアウト完全ガイド」として強化
  - 基本構文（既存）+ 実践パターン（新規）を統合
  - ブラウザサポート情報を最新化

カテゴリが不明な場合

ユーザーに確認するか、最も近いカテゴリに追加。 新カテゴリが必要な場合は SKILL.md のカテゴリ一覧も更新。

出力例（追加モード）

✅ ナレッジを追加しました

📁 カテゴリ: css-layout.md
📝 テクニック: Container Queries の実践的パターン
🔗 出典: https://example.com/container-queries

### 追加内容プレビュー:
> コンテナクエリを使用してコンポーネント単位の
> レスポンシブデザインを実現する方法...

整理モード

「ナレッジを整理して」「重複チェックして」等で発動。

整理タスク

1. 類似ナレッジの統合

統合プロセス:

1. 類似エントリを検出したら内容を比較
2. 矛盾がないか確認（矛盾がある場合は執筆日が新しい方を優先、または両論併記）
3. 問題なければ1つの強いナレッジに統合

統合の判断基準:

• 同一テクニック: 完全統合（より詳細・最新の情報を残す）
• アップデート関係: 新情報で上書き、旧情報は「以前の方法」として注記
• 補完関係: 両方の知見を合わせてより包括的なエントリに
• 矛盾あり: 両論併記し、どちらが推奨かを明記

統合後のフォーマット:

## [テクニック名]

> 出典: [URL1], [URL2]（複数の場合はカンマ区切り）
> 執筆日: [最新の執筆日]（統合元: [日付1], [日付2]）
> 追加日: [最初の追加日] / 統合日: [YYYY-MM-DD]

[統合された包括的な説明]

2. 古い情報の更新

• 執筆日が2年以上前のエントリを優先確認
• ブラウザサポートが変わったもの
• より良い方法が登場したもの
• 非推奨になったもの（削除 or 注記追加）

3. カテゴリの再編成

• 肥大化したカテゴリの分割提案
• 誤分類の移動
• 関連テクニックの相互参照追加

4. フォーマット統一

• コード例の書式統一
• セクション構造の統一
• 不足情報（ユースケース、注意点）の補完提案

整理フロー

1. 対象カテゴリファイルを Read
2. 以下を分析:
   • 重複エントリ
   • 古い情報（執筆日から2年以上経過、または執筆日不明で追加日から1年以上経過）
   • フォーマット不統一
   • 肥大化（20エントリ以上）
3. 改善提案をリスト化
4. ユーザー承認後に実行

出力例（整理モード）

📊 css-layout.md の分析結果

エントリ数: 15件
最終更新: 2025-01-15

### 検出された課題

1. 🔄 重複の可能性
   - 「Flexbox gap」と「Flexbox の gap プロパティ」が類似

2. ⚠️ 古い情報
   - 「IE対応のGrid fallback」（執筆: 2021-03）
     → IE サポート終了済み、削除を推奨

3. 📝 フォーマット不統一
   - 3件のエントリに「ユースケース」セクションがない

### 推奨アクション
- [ ] 重複を統合する
- [ ] 古い情報を削除する
- [ ] フォーマットを統一する

実行しますか？

定期整理の推奨

以下のタイミングで整理を実行:

• カテゴリが20エントリを超えたとき
• 3ヶ月に1回の定期メンテナンス
• 大きな仕様変更があったとき（新ブラウザ機能など）

パート2: ナレッジ参照（実装時・回答時）

使い方

実装タスク時の自発的参照（推奨）

Web開発の実装タスクやコーディング作業を行う際、以下の流れで自発的にナレッジベースを参照する：

1. タスク内容からキーワードを抽出

   • 例: 「レスポンシブなカードコンポーネント」→ Container Query、Grid、clamp()
   • 例: 「アニメーション実装」→ View Transitions、prefers-reduced-motion
   • 例: 「モーダル実装」→ dialog要素、Popover API

2. 該当カテゴリを特定 (上記カテゴリ一覧を参照)

3. ナレッジファイルを Read

   • ~/.claude/skills/managing-frontend-knowledge/knowledge/ 内の該当ファイル

4. ベストプラクティスを適用して実装

   • ナレッジに基づいた最新の手法を使用
   • ブラウザサポート情報を考慮
   • アクセシビリティやパフォーマンスの考慮事項を反映

効果: 作業の精度向上、実装速度向上、最新のベストプラクティス適用

質問への回答時

1. ユーザーの質問からキーワードを抽出
2. 上記カテゴリ一覧から該当するファイルを特定
3. ~/.claude/skills/managing-frontend-knowledge/knowledge/ 内の該当ファイルを Read
4. 蓄積された知識を基に回答

ディレクトリ構造

knowledge/
├── INDEX.md                          # 全体インデックス
├── css/
│   ├── layout/                       # Grid, Flexbox, 配置
│   ├── animation/                    # Transitions, アニメーション
│   ├── visual/                       # filter, mask, shape
│   ├── typography/                   # フォント, テキスト
│   ├── selectors/                    # @scope, :has, 擬似クラス
│   ├── values/                       # clamp, 単位, カスタムプロパティ
│   ├── components/                   # Popover, Anchor Positioning
│   └── theming/                      # light-dark, テーマ
├── javascript/
│   ├── patterns/                     # DOM, イベント, パターン
│   └── animation/                    # requestAnimationFrame, 補間
├── html/                             # モダンHTML, セマンティック
├── cross-cutting/
│   ├── performance/                  # 最適化, Core Web Vitals
│   ├── accessibility/                # WCAG, a11y
│   └── browser-compat/               # ブラウザバグ, 回避策
├── apple-style-guide/               # Appleライティング規約
├── human-interface-guidelines/      # Apple HIG、デザイン原則
└── material-design-3/               # Material Design 3、デザイン哲学

回答フォーマット

## [質問に対する回答]

[説明]

### コード例

\```css
/* または js/html */
\```

### ユースケース
- [具体的な使用場面]

### 参考
- [出典URL（あれば）]

該当カテゴリがない場合

1. 一般的な知識で回答
2. 「ナレッジベースに該当情報がありません」と伝える
3. 必要に応じてナレッジ収集機能での追加を提案

複数カテゴリにまたがる場合

関連する複数のファイルを Read して総合的に回答する。 例: 「スクロールアニメーション」→ css-animation.md + performance.md

注意事項

• カテゴリファイルが存在しない場合はエラーにせず、ある情報で回答
• 出典URLがある場合は必ず記載
• コード例は実用的なものを優先