FlorianBruniaux/claude-code-ultimate-guide

source-command-audit-whitepapers

このスキルは、ユーザーが移行済みソースコマンド audit-whitepapers の実行を依頼したときに使用します。

コマンドテンプレート

ホワイトペーパー＆レキャップカード監査

すべてのホワイトペーパー（FR + EN）およびレキャップカード（FR + EN）に対する包括的な鮮度と品質の監査です。各ドキュメントを現在のガイドバージョンに対してスコアリングし、FR/ENパリティをチェックし、メタデータの整合性を検証します。

引数

• --fix - 更新提案とフロントマターパッチを生成します（ファイルは変更しません）
• --verbose - 失敗のみでなく、すべての基準を表示します
• --cards-only - レキャップカードのみを監査します（メインホワイトペーパーはスキップ）
• --wp-only - メインホワイトペーパーのみを監査します（レキャップカードはスキップ）

使用法

/audit-whitepapers                  # 完全監査（失敗のみ表示）
/audit-whitepapers --fix            # 監査＋優先順位付き更新提案
/audit-whitepapers --verbose        # 全基準の詳細表示
/audit-whitepapers --cards-only     # レキャップカードのみ
/audit-whitepapers --wp-only        # ホワイトペーパーのみ

---

フェーズ1：発見

目的: 監査対象のすべてのドキュメントを特定し、一覧化します。

手順

1. 現在のガイドバージョンを読み取る: プロジェクトルートの VERSION ファイルを読み取ります。これがすべてのドキュメントが同期すべきターゲットバージョンです。

2. ディレクトリをスキャン して .qmd ファイルを探します:

   whitepapers/fr/         (メインホワイトペーパー FR)
   whitepapers/en/         (メインホワイトペーパー EN)
   whitepapers/recap-cards/fr/    (レキャップカード FR)
   whitepapers/recap-cards/en/    (レキャップカード EN)
   

3. 各ファイルを分類:

   • メインホワイトペーパー: whitepapers/fr/ または whitepapers/en/ 内の [0-9][0-9]-*.qmd に一致するファイル
   • チートシート: *cheatsheet*.qmd に一致するファイル（別途追跡、スコアリング対象外）
   • カスタムホワイトペーパー: 外部パートナー（strangebee、purchasely、devwithai）からの *-whitepaper.qmd または *-cheatsheet.qmd に一致するファイル — スコアリングから除外し、別途リスト
   • レキャップカード: recap-cards/fr/ または recap-cards/en/ 内のすべての .qmd ファイル
   • バンドル/インクルード: fiches-recap-serie.qmd、fiches/ サブディレクトリ内のファイル — 除外（構成ドキュメントのため）

4. 各対象ファイルのYAMLフロントマターを解析（最初の --- と2番目の --- の間を読み取る）。以下を抽出:

   • title, subtitle, author, date
   • version（メインWPとレキャップカードで追跡されるガイドバージョン）
   • wp-version（ホワイトペーパー独自のセマンティックバージョン、メインWPのみ）
   • guide-version（レキャップカードで使用される明示的なガイドバージョンフィールド）
   • card-number, category, difficulty（レキャップカードのみ）
   • series（メインWPのみ）

5. 発見サマリーを表示:

   ガイドバージョン: {VERSION}
   検出: メインホワイトペーパー {N} 件 ({FR}/{EN} FR/EN)、レキャップカード {N} 件 ({FR}/{EN} FR/EN)
   除外: カスタムファイル {N} 件 (strangebee、purchasely、devwithai)、バンドルファイル {N} 件
   

---

フェーズ2：バージョンギャップ分析（ファイルあたり40ポイント）

目的: 各ドキュメントがガイドに対してどの程度最新かをスコアリングします。

セマンティックバージョン比較ロジック

バージョン文字列を MAJOR.MINOR.PATCH として解析します。鮮度の指標は minor_gap = current_minor - file_minor（同じMAJORを使用）です。MAJORが異なる場合は、致命的として扱います。

メインホワイトペーパーの場合、ガイドバージョンフィールドは version です。 レキャップカードの場合、ガイドバージョンフィールドは guide-version です（存在しない場合は version にフォールバック）。

スコアリングテーブル

基準	ポイント	検出条件
ガイドバージョンが最新（0-1マイナーバージョン遅れ）	15	minor_gap <= 1
ガイドバージョンがやや古い（2-3マイナーバージョン遅れ）	10	minor_gap 2-3（部分得点、15ポイントと置き換え）
ガイドバージョンが古い（4-10マイナーバージョン遅れ）	5	minor_gap 4-10（部分得点）
wp-versionフィールドが存在し、有効なセマンティックバージョン	5	フィールドが存在し、\d+\.\d+\.\d+ に一致（WPのみ）
wp-versionがFR/ENペアで一貫	10	対応するファイルで同じ wp-version 値（WPのみ）
guide-versionがFR/ENペアで一貫	10	対応するファイルで同じ guide-version（または version）（カードのみ）

新鮮度ラベル:

• 0-1マイナーバージョン遅れ: 新鮮
• 2-3マイナーバージョン遅れ: やや古い
• 4-10マイナーバージョン遅れ: かなり古い
• 11以上マイナーバージョン遅れ: 致命的

注: ガイドバージョンの15、10、5ポイントは相互排他的です（最上位のみ付与）。

---

フェーズ3：コンテンツ鮮度チェック（ファイルあたり20ポイント）

目的: ホワイトペーパーがカバーするガイドセクションが、最終更新以降に変更されたかどうかを検出します。

ホワイトペーパーとガイドのマッピング（埋め込み）

WP#	FRファイル名接頭辞	ENファイル名接頭辞	ガイドセクション
00	00-introduction	00-series-introduction	guide/ultimate-guide.md Ch.1-2
01	01-prompts	01-effective-prompts	Ch.2 プロンプトセクション
02	02-personnalisation	02-customization	Ch.3 メモリ、Ch.4 エージェント、Ch.5 スキル
03	03-securite	03-security	Ch.7 フック、セキュリティセクション
04	04-architecture	04-architecture	Ch.2 内部構造、アーキテクチャセクション
05	05-equipe	05-team	Ch.3 チーム設定、Ch.9 CI/CD
06	06-privacy	06-privacy	Ch.2 データ/プライバシーセクション
07	07-guide-reference	07-reference-guide	Ch.10 リファレンス
08	08-agent-teams	08-agent-teams	Ch.9 エージェントチーム
09	09-apprendre	09-learning	guide/roles/learning-with-ai.md
10	10-budget	10-ai-budget	ビジネス/ROIコンテンツ

手順

1. 各メインホワイトペーパーについて、date フィールドを抽出します。日付が YYYY-MM-DD 形式でない場合は、それを解析します（例：「2026-02-12」または「March 2026」）。
2. git log --since="{date}" --oneline -- guide/ultimate-guide.md guide/roles/ guide/core/ を実行して、ホワイトペーパーの日付以降にガイドコンテンツに影響を与えたコミット数をカウントします。
3. スコア:

基準	ポイント	検出条件
WP日付以降にガイドコミットなし	10	git log が0コミットを返す
WP日付以降にコミットが少数（1-5）	7	1-5コミット（部分）
中程度のコミット（6-15）	4	6-15コミット（部分）
多数のコミット（>15）	0	15コミット超
このWPのマッピングが定義されている	5	WP番号が上記マッピングテーブルに存在
Git履歴にアクセス可能	5	git log コマンドがエラーなく実行される

レキャップカード: 詳細なGit分析はスキップします。minor_gap に基づいてフラットな鮮度スコアを付与:

• 0-1遅れ: 20 pts
• 2-3遅れ: 15 pts
• 4-10遅れ: 8 pts
• 11以上遅れ: 0 pts

---

フェーズ4：FR/ENパリティチェック（ファイルあたり20ポイント）

目的: すべてのドキュメントに、他言語で完全でバージョンが一致する対応ドキュメントが必要です。

ペアリング戦略

メインホワイトペーパー: 2桁の数字接頭辞でマッチング（例：00、03、10）。FRとENのファイル名は異なりますが、接頭辞は一貫しています。

レキャップカード: 同一ファイル名でマッチング（両方の言語ディレクトリで同じファイル名を使用）。

スコアリングテーブル

基準	ポイント	検出条件
他言語に対応ファイルが存在	10	一致する接頭辞（WP）または同一名（カード）のファイルを検出
wp-versionがペア間で一致	5	同じ wp-version 値（WPのみ）
ガイドバージョンがペア間で一致	5	同じ version/guide-version 値

ペアのFRとENファイルのパリティスコアは同一と見なします（ペアが完全な場合、両方に20ポイント；片方が欠落している場合、存在するファイルのパリティスコアは0）。

---

フェーズ5：メタデータ品質（ファイルあたり20ポイント）

目的: フロントマターの完全性、フィールド形式、および同じタイプのファイル間での一貫性を検証します。

メインホワイトペーパー（最大20ポイント）

基準	ポイント	検出条件
必須フィールドが存在	6	title、subtitle、author、date、version、wp-version、series のすべてが存在
version がセマンティックバージョンパターンに従っている	3	\d+\.\d+\.\d+ に一致
wp-version がセマンティックバージョンパターンに従っている	3	\d+\.\d+\.\d+ に一致
date が解析可能で、未来の日付ではない	3	有効な日付、今日以降ではない
series 値が一貫している	2	「Codex Ultimate Guide」と等しい
wp-version が欠落していない（空または不在でない）	3	フィールドに空でない値がある

レキャップカード（最大20ポイント）

基準	ポイント	検出条件
必須フィールドが存在	5	title、subtitle、card-number、category、difficulty、guide-version、author、version、date のすべてが存在
card-number がファイル名接頭辞と一致	4	例：card-number の C01 がファイル名の c01- と一致
category が言語にとって有効	4	FR: 「Technique」「Methodologie」「Conception」のいずれか；EN: 「Technical」「Methodology」「Design」のいずれか（ENで「Conceptual」は不整合としてフラグ）
difficulty が有効な値	3	「beginner」「intermediate」「advanced」のいずれか
guide-version と version フィールドが互いに一致	4	両方のフィールドが存在し、同じファイル内で同じ値を持つ

自動検出する既知の問題: EN Cシリーズカードは2つの異なるカテゴリ値を使用（c01-c05で「Conceptual」、c06以降で「Design」）。レポートのメタデータ問題セクションでこの不整合を明示的にフラグします。

---

フェーズ6：スコアリングとグレーディング

スコア計算式（ファイルあたり）

合計 = バージョンギャップ (40) + コンテンツ鮮度 (20) + FR/ENパリティ (20) + メタデータ品質 (20)
スコア = (合計 / 100) * 100  [パーセンテージ]

グレードスケール

グレード	スコア	ステータス
A	90-100	新鮮、完全同期
B	80-89	良好（本番閾値）
C	70-79	近いうちに更新が必要
D	60-69	古い、優先すべき
F	<60	致命的：コンテンツが古くなっている可能性

全体的な健全性スコア

加重健全性 = (WPスコアの合計 * 2 + カードスコアの合計 * 1) / (WP数 * 2 + カード数 * 1)

ホワイトペーパーは2倍の重み付け（各20〜80ページに対し、レキャップカードは2ページ）。古いホワイトペーパーはより大きなリスクをもたらします。

---

フェーズ7：レポート

以下のMarkdownレポートを出力します。個別ファイルの内訳は <details> ブロックを使用して、トップレベルをスキャンしやすくします。

# ホワイトペーパー＆レキャップカード監査

**日付**: {today}
**ガイドバージョン**: {VERSION}
**全体的な健全性**: {score}% ({grade})
**監査対象ファイル数**: {total}（ホワイトペーパー {wp_count} 件、レキャップカード {card_count} 件）

---

## バージョンステータスダッシュボード

| ステータス | ホワイトペーパー | レキャップカード | 合計 |
|--------|-------------|-------------|-------|
| 新鮮（0-1マイナー遅れ）   | N | N | N |
| やや古い（2-3マイナー遅れ）   | N | N | N |
| かなり古い（4-10遅れ）   | N | N | N |
| 致命的（11以上遅れ）      | N | N | N |

**現在使用中のバージョン**:
- メインWP 00-09: {version}（マイナーバージョン {gap} 遅れ）
- メインWP 10: {version}（マイナーバージョン {gap} 遅れ）
- レキャップカード: {guide-version}（マイナーバージョン {gap} 遅れ）

---

## ホワイトペーパースコア

| WP# | タイトル | version | Gap | wp-version | パリティ | スコア | グレード |
|-----|-------|---------|-----|------------|--------|-------|-------|
| 00  | ...   | ...     | -N  | ...        | OK/gap | N%    | X     |
...

<details>
<summary>個別基準の内訳（WP 00）</summary>

| フェーズ | 基準 | 結果 | ポイント |
|-------|-----------|--------|--------|
| バージョンギャップ | ガイドバージョンが最新 | 致命的 (-11) | 0/15 |
| バージョンギャップ | wp-versionが有効なセマンティックバージョン | OK | 5/5 |
| ... | ... | ... | ... |
| **合計** | | | **N/100** |
</details>

---

## レキャップカードスコア

| シリーズ | カード数 | 平均guide-version | 平均Gap | 平均スコア | グレード |
|--------|-------|-------------------|---------|-----------|-------|
| T（テクニカル）    | 22 | ... | -N | N% | X |
| M（方法論）  | 22 | ... | -N | N% | X |
| C（概念）   | 13 | ... | -N | N% | X |

<details>
<summary>個別カードスコア</summary>

| カード | カテゴリ | guide-version | Gap | パリティ | メタデータ | スコア | グレード |
|------|----------|---------------|-----|--------|----------|-------|-------|
...
</details>

---

## FR/ENパリティレポート

### ホワイトペーパー
| WP# | FR | EN | wp-version一致 | version一致 |
|-----|----|----|------------------|---------------|
...

### レキャップカード
- **FR数**: {N} | **EN数**: {N}
- **欠落しているFR**: [リストまたは「なし」]
- **欠落しているEN**: [リストまたは「なし」]
- **バージョンの不一致**: [リストまたは「なし」]

---

## メタデータ問題

### 既知の問題：ENレキャップカードのカテゴリ不整合
EN Cシリーズカードは、「Conceptual/Design」カテゴリに2つの異なる値を使用しています:
- 「Conceptual」: c01、c02、c03、c04、c05
- 「Design」: c06、c07、c08、...
推奨: ガイド用語に合わせて「Design」に統一する。
影響ファイル: whitepapers/recap-cards/en/c01-*.qmd から c05-*.qmd（「Conceptual」を「Design」に変更）

### その他の問題
[欠落フィールド、不正な形式、日付の問題などをリスト]

---

## 優先アクションアイテム

### 致命的（グレードF、11以上バージョン遅れ）
[ファイルパス付きで特定のホワイトペーパーをリスト]

### 高（グレードD-F、2以上バージョン遅れ）
[特定のファイルをリスト]

### 中（メタデータ品質、カテゴリ修正）
[特定の問題をリスト]

### 低（微調整、日付調整）
[特定の問題をリスト]

---

## 次のステップ

1. `/update-whitepapers --since {oldest_version}` を実行して、すべての古いWPを更新
2. ENカテゴリの不整合を修正（5ファイル：c01からc05、「Conceptual」を「Design」に変更）
3. 更新後に `/audit-whitepapers` を再実行して進捗を追跡
4. 目標：全ファイルで健全性80%以上（グレードB）

---

修正モード（--fix）

--fix が渡された場合、レポートの後に修正提案セクションを追加します。このセクションは具体的なパッチを提供しますが、ファイルは変更しません。

フロントマターバージョンパッチ

ガイドバージョンが古い各ファイルについて出力:

# ファイル: whitepapers/fr/00-introduction-serie.qmd
# 変更:
version: "3.27.6"  ->  version: "{current_VERSION}"
date: 2026-02-12   ->  date: {today}

カテゴリ修正パッチ（ENレキャップカード）

更新が必要なファイル（カテゴリ: "Conceptual" -> "Design"）:
- whitepapers/recap-cards/en/c01-trust-calibration.qmd
- whitepapers/recap-cards/en/c02-*.qmd
- whitepapers/recap-cards/en/c03-*.qmd
- whitepapers/recap-cards/en/c04-*.qmd
- whitepapers/recap-cards/en/c05-*.qmd

フロントマターへのカテゴリ修正の適用

各影響ファイルについて、レポートセクションで変更を提案します:

# ファイル: whitepapers/recap-cards/en/c01-trust-calibration.qmd
# 変更:
category: "Conceptual"  ->  category: "Design"

---

例

例1：完全監査

/audit-whitepapers

出力は、すべてのホワイトペーパーとレキャップカードを監査する完全なMarkdownレポートで、失敗した基準のみを表示します。

例2：修正モードで監査

/audit-whitepapers --fix

同じレポートに加えて、すべての古いドキュメントのフロントマターパッチ、カテゴリ修正、およびその他のアクションアイテムを含む修正提案セクションが追加されます。

例3：レキャップカードのみの監査

/audit-whitepapers --cards-only

メインホワイトペーパーをスキップして、レキャップカードのみを監査します。

例4：詳細監査

/audit-whitepapers --verbose

合格した基準も含む、すべての基準の完全な内訳を表示します。