モジュール品質保証ガイド

概要

このドキュメントでは、モジュールの品質を確保するための検証方法、ツールの使い方、品質メトリクスについて説明します。

📄 注記: このドキュメントは02-development-guideの補完資料です。まずメインガイドをご確認ください。

品質基準

必須要件

  1. 構造的品質
    • YAMLフロントマターの完全性
    • 適切なMarkdown構文
    • 一貫したセクション構成
  2. 内容的品質
    • 具体的で実行可能な指示
    • 曖昧さのない表現
    • 実用的な例の提供
  3. サイズ要件
    • 簡潔版: 50-200行（推奨）、最大300行
    • 詳細版: 200-600行（推奨）、最大800行
    • トークン効率の考慮

検証ツールの使用方法

基本検証: validate-modules.sh

メタデータのみの検証

# 全モジュールの検証
./scripts/validate-modules.sh

# 特定カテゴリの検証
./scripts/validate-modules.sh --category tasks

サイズチェックを含む包括的検証

# サイズチェック付き検証
./scripts/validate-modules.sh --check-size

検証結果の読み方

成功例

🔍 モジュールメタデータ検証を開始します...
📏 サイズチェック: 有効
📂 言語: ja
  📁 カテゴリ: tasks
    ✓ blog_writing.yaml
    ✓ code_generation.yaml
    ✓ data_analysis.yaml

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 検証結果サマリー
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
総ファイル数: 15
✓ 正常: 15
⚠ 警告: 0
✗ エラー: 0

✅ すべてのモジュールが検証に合格しました！

警告例

📂 言語: ja
  📁 カテゴリ: tasks
    ⚠ project_planning.yaml
      [WARNING] project_planning.md: 250 lines, ~3750 tokens
        - 行数（250）が推奨最大値（200）を超えています
    ⚠ [RATIO WARNING] blog_writing pair
        - サイズ比率（5.2）が推奨最大値（4.0）を超えています

エラー例

📂 言語: ja
  📁 カテゴリ: tasks
    ✗ thesis_writing.yaml
      - 必須フィールド「description」が欠落しています
      [ERROR] thesis_writing_detailed.md: 1050 lines, ~15750 tokens
        - 行数（1050）が最大値（800）を超えています

品質メトリクス

サイズメトリクス

自動計測項目

基準値

簡潔版:
  推奨行数: 50-200行
  警告閾値: 250行
  エラー閾値: 300行
  推奨トークン: 1,000-4,000
  最大トークン: 6,000

詳細版:
  推奨行数: 200-600行
  警告閾値: 800行
  エラー閾値: 1,000行
  推奨トークン: 4,000-16,000
  最大トークン: 20,000

サイズ比率:
  推奨: 2.5-4.0倍
  最大: 5.0倍
  最小: 1.5倍

内容品質メトリクス

チェック項目

  1. 変数プレースホルダー
    • 形式の一貫性
    • 適切な変数名の使用
    • 必要な箇所での変数化
  2. 例の充実度
    • 実用的な使用例の提供
    • 入力と出力の明確な対応
    • 複数パターンの例示
  3. 指示の明確性
    • ステップバイステップの手順
    • 曖昧さのない表現
    • 実行可能な具体性

レビューチェックリスト

作成者セルフチェック

構造チェック

内容チェック

サイズチェック

レビュアーチェック

技術的正確性

使いやすさ

一貫性

トラブルシューティング

よくあるエラーと解決法

1. YAMLパースエラー

# ❌ 誤り
description: これは"引用符"を含む説明です

# ✅ 正しい
description: "これは\"引用符\"を含む説明です"

2. ID命名規則違反

# ❌ 誤り（tasksカテゴリの場合）
id: "project_planning"

# ✅ 正しい
id: "task_project_planning"

3. サイズ超過

# 対策1: 冗長な説明を削除
詳細な理論的背景は詳細版に移動

# 対策2: リストを簡潔化
- 重要なポイント1
- 重要なポイント2
（詳細版で詳しく説明）

# 対策3: コード例を最小化
// コアロジックのみ表示
function main() {
  // 詳細実装は外部リンク参照
}

パフォーマンス最適化

検証速度の向上

# 単一ファイルの検証
./scripts/validate-modules.sh path/to/specific/module.yaml

# 特定カテゴリのみ検証
find modular/ja/modules/tasks -name "*.yaml" | head -5 | xargs ./scripts/validate-modules.sh

大量モジュールの管理

# 並列処理での高速検証（将来実装予定）
./scripts/validate-modules.sh --parallel --workers 4

継続的品質改善

定期チェックの仕組み

週次レビュー

月次改善

品質向上のための提案

  1. 自動化の拡充
    • CI/CDでの自動検証
    • プルリクエスト時の品質チェック
    • 品質スコアの可視化
  2. ツールの改善
    • より正確なトークン数計測
    • 内容品質の自動評価
    • インタラクティブな修正提案
  3. コミュニティの活用
    • ピアレビューの促進
    • 品質改善の共有
    • ベストプラクティスの蓄積

関連資料

最終更新日: 2025-01-26