review-docs

ドキュメントのレビュー

包括的なドキュメントレビューです。Docus／Nuxt Content 向けに最適化されていますが、あらゆる Markdown ドキュメントに対応しています。

ワークフローの概要

このスキルでは、5 つのステップでレビューを行います。

1. プロジェクトタイプの検出 - Docus／Nuxt Content と一般的な Markdown のどちらかを特定します
2. 構造の分析 - ドキュメントの構成、ロケール、セクションを把握します
3. 技術的な検証 - フロントマター、MDC 構文（該当する場合）、ファイル名を確認します
4. コンテンツ品質のレビュー - 明瞭さ、SEO、構成、i18n を評価します
5. レポートの生成 - 分類された、実行可能な推奨事項を提示します

優先度

• 重大 - デプロイを妨げる、またはエラーの原因となる問題（フロントマターの欠落、無効な MDC 構文）
• 重要 - UX／SEO に大きな影響を及ぼす問題（メタデータの不備、受動態、不明瞭な見出し）
• あると便利 - 仕上げや最適化の提案（コールアウトの追加、例の改善）

想定される結果

このスキルが生成するのは、詳細なレポートのみです。レビュー後、希望があれば特定した問題の修正を提案します。

---

ステップ 1：プロジェクトタイプの検出

目標： Docus／Nuxt Content プロジェクトか、一般的な Markdown ドキュメントかを判断します。

検出の指標

Docus／Nuxt Content を確認する項目：

1. package.json の依存関係：

   • "docus" - Docus テーマ
   • "@nuxt/content" - Nuxt Content モジュール
   • "@nuxtjs/mdc" - MDC サポート

2. 設定ファイル：

   • @nuxt/content モジュールを含む nuxt.config.ts または nuxt.config.js
   • content.config.ts - コンテンツコレクションの設定

3. コンテンツの構成：

   • content/ または docs/content/ ディレクトリ
   • サブディレクトリ内の .navigation.yml ファイル
   • Markdown ファイル内の MDC 構文（::component-name）

4. プロジェクトの構成：

   • 番号付きディレクトリ（1.getting-started/、2.guide/）
   • navigation、seo フィールドを含むフロントマター

プロジェクトタイプの分類

タイプ A：Docus／Nuxt Content プロジェクト

• Docus 固有の検証をすべて適用します
• MDC コンポーネント構文を確認します（u- 接頭辞の要件）
• Nuxt Content のフロントマター構造を確認します
• ナビゲーションファイル（.navigation.yml）を確認します
• 技術的な検証をすべて実施します

タイプ B：一般的な Markdown ドキュメント

• 基本的な Markdown の検証のみ行います
• 一般的なフロントマター（title、description、date、author）を確認します
• 標準的な Markdown 構文を確認します
• コンテンツ品質（SEO、明瞭さ、構成）を重視します
• Docus 固有の技術チェックは行いません

検出結果

検出後、レポートに次の内容を記載します。

Project Type: [Docus/Nuxt Content | Generic Markdown]
Validation Mode: [Full (Docus-specific) | Basic (Markdown-only)]

検出したタイプに応じて検証手順を調整します：

• タイプ A（Docus）： すべてのステップを完全な検証付きで実施します
• タイプ B（一般）： Docus 固有のチェックは省略し、コンテンツ品質に重点を置きます

---

ステップ 2：ドキュメント構造の分析

コンテンツディレクトリの特定

ドキュメントのコンテンツディレクトリを探します。

• docs/content/ を確認します（最も一般的）
• content/ を確認します（ルートレベル）
• app/content/ を確認します（別の配置場所）

ロケールの検出

サブディレクトリを調べ、言語の構成を特定します。

単一言語（ロケールのサブディレクトリなし）：

content/
├── index.md
├── 1.getting-started/
└── 2.guide/

多言語（ロケールのサブディレクトリあり）：

content/
├── en/
│   ├── index.md
│   ├── 1.getting-started/
│   └── 2.guide/
└── fr/
    ├── index.md
    ├── 1.getting-started/
    └── 2.guide/

検出ロジック：

• 直下のサブディレクトリが 2 文字のコード（en、fr、es、de など）なら、多言語です
• 直下のサブディレクトリが番号付き（1.getting-started など）なら、単一言語です

ドキュメントのセクション一覧

各ロケール内の番号付きディレクトリをすべて特定します。

• 1.getting-started/
• 2.guide/ または 2.concepts/
• 3.api/ または 3.essentials/
• 4.advanced/ または 4.ai/

各セクションについて、次の項目を記録します。

• セクション名
• .navigation.yml ファイルの有無
• ページ数（.md ファイルの数）
• ページのファイル名

コアファイルの確認

必須ファイルがあるか確認します。

• 各ロケールのルートに index.md がある
• 各セクションディレクトリに .navigation.yml がある
• 番号付きファイルがパターンに沿っている（1.introduction.md、2.installation.md）

構造マップの作成

レポート用に構造を記録します。

Project: [project-name]
Locales: [en, fr] (or "Single language")
Sections:
  - 1.getting-started: 5 pages, .navigation.yml ✅
  - 2.guide: 8 pages, .navigation.yml ✅
  - 3.api: 3 pages, .navigation.yml ❌ (missing)

---

ステップ 3：技術的な検証

ステップ 1 で検出したプロジェクトタイプに応じて検証内容を調整します。

Docus/Nuxt Content プロジェクト向け (タイプ A)

references/technical-checks.md を使用して、完全な技術的検証を実行します。

検証項目:

1. Frontmatter 構造 - 必須: title、description。任意: navigation、seo、links
2. MDC コンポーネント構文 - すべての Nuxt UI コンポーネントには u- プレフィックスが必須 (::u-page-hero、:::u-button)
3. コードブロックのラベル - ファイルを表すすべてのコードブロックには説明的なラベルが必要 (```vue [App.vue]、```ts [config.ts])
4. コード言語の一貫性 - コード例はプロジェクトの言語スタックと一致させる必要があります (例: プロジェクトが TypeScript を使用している場合は TypeScript、Vue の <script setup> には lang="ts")
5. パッケージマネージャーの網羅性 - ::code-group のインストールブロックは、プロジェクト/エコシステムがサポートするすべてのパッケージマネージャーを網羅する必要があります
6. コードプレビュー - 視覚的にレンダリング可能な例 (テーブル、リスト、レンダリングされた markdown など) には ::code-preview を使用します
7. コードグループの範囲 - 同等の代替手段 (パッケージマネージャー、フレームワークのバリアントなど) のみをグループ化します — 無関係な手順 (インストールコマンド + 設定ファイルなど) を混在させないでください
8. ファイル命名 - 番号付きのディレクトリ/ファイル、ケバブケース、各セクションの .navigation.yml
9. 非表示ページ - ルートとして存在すべきだがサイドバーに表示すべきでないページには navigation: false を使用します

よくある重大なエラー:

• u- プレフィックスの欠落: ::page-hero → ::u-page-hero であるべき
• 必須 frontmatter の欠落: title、description
• 無効な .navigation.yml 構造
• セクションの index.md の欠落によるセクションルート URL の 404

完全な検証ルール、例、エラーパターンについては references/technical-checks.md を参照してください。

汎用 Markdown プロジェクト向け (タイプ B)

簡易検証 - Docus 固有のチェックはスキップします:

基本的な Frontmatter 検証:

• 一般的なフィールドを確認: title、description、date、author、tags
• 厳密な要件はありません - 推奨事項のみです
• frontmatter が完全に欠落している場合は指摘します

標準 Markdown 構文:

• 基本的な markdown (見出し、リスト、リンク、コードブロック) を検証します
• 壊れた内部リンクを確認します
• 画像パスが存在することを確認します

スキップ:

• MDC コンポーネント構文 (該当しません)
• Nuxt Content の frontmatter 構造
• .navigation.yml ファイル
• Docus 固有の規約

重点項目:

• コンテンツ品質 (次のステップ)
• SEO 最適化
• 明瞭さと読みやすさ
• 全体的な構造

---

ステップ 4: コンテンツ品質レビュー

このステップはすべてのプロジェクトタイプに適用されます (Docus と汎用 Markdown の両方)。

4 つの観点からコンテンツ品質を評価します。詳細なチェックリストについては参照ファイルを参照してください。

明瞭さのレビュー

references/clarity-checks.md を使用して以下を確認します:

• 話法とトーン: 能動態、現在形、二人称
• 文の構造: 目標 15〜20 語、冗長な表現を避ける
• 段落の構造: 2〜5 文、見出し間に 200〜400 語
• アクションベースの見出し: ガイドのページタイトル (H1) と見出し (H2/H3) には動作動詞を使用します (Nuxt パターン)
  • 例: 「Create Your First Module」、「Configure your app」、「Build a Plugin」
  • 例外: Getting Started (名詞)、API (関数名)、Concepts (説明的)
• 用語: 一貫した命名、技術用語の定義
• コード例: 完全で、コピー&ペースト可能、現実的、ファイルラベル付き

SEO レビュー

references/seo-checks.md を使用して以下を確認します:

• タイトル: 50〜60 文字、キーワードを含む、一意
• 説明: 120〜160 文字、魅力的、一意
• 見出し: 単一の H1、論理的な階層 (H1→H2→H3)、説明的
• URL: ケバブケース、説明的、安定
• リンク: 説明的なアンカーテキスト、「Next steps」セクション
• コンテンツの長さ: ランディングページは 300 語以上、ガイドは 400 語以上、セクションごとに 200〜400 語
• 画像: 代替テキスト、カラーモードのバリアント

構造レビュー

references/structure-checks.md を使用して、以下をチェックします。

• 階層: 最大 3 レベル、論理的な進行
• 構成: セクションごとに 2～15 ページ、.navigation.yml が存在すること、適切なアイコン
• 流れ: 論理的な進行、「Next Steps」リンク、孤立したページがないこと
• ランディングページ: ヒーロー、機能、クイックスタート
• 一貫性: ページ間で類似した構造

i18n レビュー（多言語の場合）

references/i18n-checks.md を使用して、以下をチェックします。

• 並列構造: ロケール間で同一のディレクトリ、ファイル、ページ数
• 翻訳の完全性: 同程度のコンテンツ量（±30%）、同一の見出し
• ナビゲーション: 同一のアイコン、翻訳されたタイトル
• ロケール固有: 言語の混在がないこと、正しい内部リンク、翻訳されたコメント

---

ステップ 5: レポートを生成する

assets/report-template.md を使用して、包括的なレビューレポートを作成します。

プロジェクトの種類に応じてレポートを調整します:

• Docus/Nuxt Content: すべてのセクションを含めます（技術、SEO、明瞭性、構造、i18n）
• 汎用 Markdown: コンテンツ品質に焦点を当てます（SEO、明瞭性、構造）、Docus 固有の技術的な問題は省略します

レポートの構造

# Documentation Review Report

**Generated:** [current date and time]
**Project:** [project name from package.json or directory]
**Reviewed:** [X] pages across [Y] sections in [locales]

---

## Executive Summary

- **Critical Issues:** [count] (must fix - block deployment/cause errors)
- **Important Issues:** [count] (significant impact on UX/SEO)
- **Nice-to-Have:** [count] (polish and optimization recommendations)

**Overall Assessment:** [1-2 sentence summary of documentation quality]

---

## Critical Issues

[List all Critical issues grouped by category]

### Technical: MDC Syntax Errors

#### Missing u- prefix on Nuxt UI components

**File:** `/content/en/1.getting-started/1.introduction.md:15`

**Problem:** Page hero component missing `u-` prefix

**Current:**
\`\`\`markdown
::page-hero
#title
Welcome
::
\`\`\`

**Should Be:**
\`\`\`markdown
::u-page-hero
#title
Welcome
::
\`\`\`

**Impact:** Component will not render, causing build errors

---

### Technical: Missing Frontmatter

[Similar format for each issue]

---

## Important Issues

[List all Important issues grouped by category: SEO, Clarity, Structure]

### SEO: Suboptimal Metadata

[Details with file paths and recommendations]

### Clarity: Passive Voice

[Details with examples and suggested rewrites]

### Structure: Poor Navigation

[Details with organizational recommendations]

---

## Nice-to-Have Suggestions

[List optimization suggestions by category]

### SEO Optimizations
- **[File]**: [Suggestion]

### Clarity Improvements
- **[File]**: Consider adding `::tip` callout for [specific content]

### Structure Enhancements
- **[Section]**: Consider splitting into subsections

---

## Locale-Specific Issues

[Only if multi-language detected]

### French (`/fr/`)
- [Translation issues]

---

## Statistics

### Content Overview

| Section | Pages (en) | Pages (fr) | Avg Words/Page |
|---------|------------|------------|----------------|
| Getting Started | [X] | [X] | ~[XXX] |
| Guide | [X] | [X] | ~[XXX] |

### Issue Breakdown

| Category | Critical | Important | Nice-to-Have | Total |
|----------|----------|-----------|--------------|-------|
| Technical | [X] | [X] | [X] | [X] |
| SEO | [X] | [X] | [X] | [X] |
| Clarity | [X] | [X] | [X] | [X] |
| Structure | [X] | [X] | [X] | [X] |
| i18n | [X] | [X] | [X] | [X] |
| **Total** | **[X]** | **[X]** | **[X]** | **[X]** |

---

## Positive Highlights

[Call out 2-3 things done well]
- Good use of callouts and code examples
- Consistent MDC component usage
- Well-organized section structure

---

## Recommended Action Plan

### Priority 1: Fix Critical Issues (Today)
1. [Specific actionable items]

**Estimated fixes:** [X] files

### Priority 2: Important Issues (This Week)
1. [Specific actionable items]

**Estimated fixes:** [X] files

### Priority 3: Nice-to-Have (Next Sprint)
1. [Specific actionable items]

**Estimated fixes:** [X] files

---

## Next Steps

**Would you like me to:**

1. **Fix all Critical issues** - I can automatically correct MDC syntax and frontmatter issues
2. **Rewrite specific sections** - Point out which pages need clarity improvements, and I'll rewrite them
3. **Optimize SEO metadata** - I can update all titles and descriptions to optimal lengths
4. **Restructure content** - If sections need reorganization, I can help restructure
5. **Complete translations** - If you need i18n content completed

**Or specify what you'd like to focus on first.**

レポート生成のガイドライン

具体的に:

• 正確なファイルパスと行番号を含めます
• 現在のコードと推奨コードを提示します
• 各問題がなぜ重要か（影響）を説明します

実行可能に:

• 明確な修正手順を提供します
• コード例を含めます
• 影響度で優先順位を付けます

バランスよく:

• 良い点を強調します
• 些細な問題で圧倒しないようにします
• 影響度の高い改善に焦点を当てます

レポートを生成した後:

• ユーザーが希望する場合は、問題の修正を提案します
• 特定のカテゴリやファイルに対応できるようにします
• 重大な問題から始めることを提案します

---

クイックリファレンス

最もよくある問題:

• Nuxt UI コンポーネントに u- プレフィックスがない（::page-hero → ::u-page-hero）
• SEO 説明が短すぎる（120～160 文字必要）
• 指示に受動態が使われている（「can be done」→「do it」）
• 一般的な見出し（「Configuration」→「Configure your app」）
• コードブロックにファイル名ラベルがない（ファイルを表すすべてのブロックには付けるべきです）
• コードの言語がプロジェクトのスタックと一致していない（例: TypeScript プロジェクトの Vue <script setup> に lang="ts" がない）
• ::code-group のインストールブロックでパッケージマネージャーの網羅が不完全（エコシステム/プロジェクトと照合してください）
• 無関係なステップが ::code-group にまとめられている（例: インストールコマンド + 設定ファイル）— 別々のブロックに分けてください
• レンダリングされたプレビューが明瞭性を高める箇所に ::code-preview がない（テーブル、リストなど）
• セクションのランディングページがない → セクションのルート URL で 404 になる（必要に応じて navigation: false を付けた index.md を追加してください）

完全なチェックリストと例については、リファレンスファイルを参照してください。