モジュールテンプレート活用ガイド

概要

このドキュメントは、AI指示書キットのモジュール作成において、テンプレートを活用して効率的に開発する方法を説明します。特にPhase 0アプローチと各カテゴリのテンプレート活用に重点を置いています。

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

モジュールタイプ

1. Core（コア）

システムの基本構造を定義する必須モジュール

role_definition: 役割定義
constraints: 制約事項
output_format: 出力形式

2. Tasks（タスク）

具体的な作業内容を定義

例: code_generation、data_analysis、documentation

3. Skills（スキル）

特定の能力や技術を提供

例: api_design、testing、error_handling

4. Methods（方法論）

作業アプローチや方法論を定義

例: agile、lean、design_thinking

5. Domains（ドメイン）

業界固有の知識と慣習

例: fintech、healthcare、education

6. Roles（役割）

AIの振る舞いやペルソナを定義

例: mentor、reviewer、consultant

7. Quality（品質）

品質レベルや基準を定義

例: production（本番品質）

8. Expertise（専門知識）

深い専門知識と最新ベストプラクティス

例: software_engineering、machine_learning

開発プロセス

Phase 0: テンプレート使用による初期作成

0.1 適切なテンプレート選択

# 1. カテゴリに応じたテンプレートを選択
modular/ja/templates/  # 日本語版
modular/en/templates/  # 英語版
├── task_template.yaml      # タスクモジュール用
├── skill_template.yaml     # スキルモジュール用
├── expertise_template.yaml # 専門知識モジュール用
├── role_template.yaml      # ロールモジュール用
├── method_template.yaml    # 方法論モジュール用
├── domain_template.yaml    # ドメインモジュール用
├── quality_template.yaml   # 品質モジュール用
└── core_template.yaml      # コアモジュール用

0.2 テンプレートからの新規作成

# 1. テンプレートをコピー
cp modular/ja/templates/task_template.yaml modular/ja/modules/tasks/new_task.yaml

# 2. プレースホルダーを実際の値に置換
# [MODULE_NAME] → 実際のモジュール名
# [タスク名] → 実際のタスク名
# [詳細説明] → 実際の説明
# etc.

# 3. 不要なセクションを削除・必要なセクションを追加

# 4. 検証スクリプトで確認
python3 scripts/validate_module_yaml.py modular/ja/modules/tasks/new_task.yaml tasks

0.3 テンプレート活用のメリット

一貫性: 標準的な構造とフィールドを保証
完全性: 必要なメタデータの漏れを防止
品質: 依存関係フィールドのオブジェクト形式を自動適用
効率性: プレースホルダー置換で迅速な作成

Phase 1: 計画

1.1 モジュールタイプの決定

判断基準:
  Core: システムの基本動作に必要
  Tasks: 具体的な成果物を生成
  Skills: 特定の技術的能力
  Methods: プロセスや手順
  Domains: 業界特有の知識
  Roles: AIの振る舞い
  Quality: 品質基準
  Expertise: 深い専門知識（最新トレンド含む）

1.2 スコープ定義

提供する機能の明確化
他モジュールとの境界設定
依存関係の特定

Phase 2: 研究・調査

2.1 情報収集

# 調査結果の保存先
docs/references/[category]/[module_name]_research.md

2.2 ベストプラクティス調査

業界標準の確認
最新トレンドの把握（特にExpertiseモジュール）
実装例の収集

Phase 3: 設計

3.1 構造設計

## 基本構造（全モジュール共通）
概要
主要機能/原則
実装詳細
使用例
ベストプラクティス（該当する場合）

3.2 変数設計

変数設計原則:
  - 明確な命名: [category]_[specific_function]
  - 適切なデフォルト値: 最も一般的な設定
  - 拡張性: 将来の追加を考慮
  - enum型の活用: 選択肢を明確に

Phase 4: 実装

4.1 Markdownファイル作成

# [モジュール名]

## 概要
[簡潔で明確な説明]

## [メインセクション]
### 1. [サブセクション]
[詳細内容]

## 変数の活用例
### パターン1: [使用シナリオ]
```yaml
[変数設定例]

#### 4.2 YAMLメタデータ作成
```yaml
id: [category]_[name]
name: [日本語名]
description: [詳細な説明]
version: 1.0.0
category: [category]
subcategory: [subcategory]

variables:
  - name: "[variable_name]"
    description: "[説明]"
    type: "enum"
    values: [...]
    default: "[default_value]"

dependencies:
  required: []
  optional: []

compatible_tasks: []

tags: []

examples: []

Phase 4.5: 簡潔版の作成

簡潔版作成の重要性

詳細版を基に簡潔版を作成することで、深い理解に基づいた確かな要約が可能になります。

4.5.1 作成プロセス

手順:
詳細版の完成確認: 広く深い調査とベストプラクティスを含む
エッセンスの抽出: 最も重要な概念とパターンを特定
実用性の重視: すぐに使えるクイックリファレンスとして再構成
サイズ目標: 詳細版の20-30%以下（トークン効率を考慮）

4.5.2 情報の優先順位付け

優先度高（必須）:
  - 実践で使える情報: 理論より実装方法
  - 頻出パターン: 80%のケースをカバーする20%の知識
  - 即効性のある知識: すぐに適用できる内容
  - 判断基準: 選択や意思決定に必要な指針

優先度低（削除対象）:
  - 詳細な理論説明: 背景や歴史
  - 長いコード例: 50行以上の実装例
  - エッジケース: 稀な状況への対応
  - 冗長な説明: 繰り返しや装飾的な表現

4.5.3 構造の最適化テクニック

表形式の活用:
  用途: 比較、選択基準、マトリクス
  例: アーキテクチャ選択表、トラブルシューティング早見表

チェックリスト形式:
  用途: 手順、確認項目、実装ステップ
  例: 品質チェックリスト、デプロイ前確認

早見表形式:
  用途: 問題解決、パラメータ選択、設定値
  例: パフォーマンス指標、エラー対処法

YAMLによる構造化:
  用途: 階層的な情報、設定例、フロー
  例: CI/CDパイプライン、システム構成

4.5.4 認知負荷の軽減

視覚的階層の作成:
- **太字**: 重要なキーワードや概念
- 表: 複数項目の比較や選択
- リスト: 順序や手順の明確化
- コードブロック: 最小限のシグネチャ

7±2の法則:
- 各セクションの項目数を5-9個に制限
- サブセクションも同様に制限
- 情報のグループ化で記憶しやすく

スキャン可能性:
- 明確な見出し構造
- 重要情報を冒頭に配置
- 関連情報を近接配置

4.5.5 具体的な圧縮手法

コード例の圧縮:
  詳細版: 完全な実装例（50-100行）
  簡潔版: シグネチャとキー部分のみ（5-10行）

説明の凝縮:
  詳細版: 理論的背景 + 実装詳細 + 応用例
  簡潔版: 実装ポイント + 使用場面

リスト化:
  詳細版: 段落での説明
  簡潔版: 箇条書きや番号付きリスト

数値化:
  詳細版: 定性的な説明
  簡潔版: 具体的な数値目標や閾値

4.5.6 簡潔版の構成要素

## 保持すべき要素
- コア概念の定義（1-2文）
- 主要パターンの表形式まとめ
- 必須のベストプラクティス（箇条書き）
- 基本的な使用例（最小限）

## 削除・簡略化する要素
- 詳細な実装コード → APIシグネチャのみ
- 理論的説明 → 実践的要点のみ
- 網羅的リスト → 主要3-5項目
- ステップバイステップ → 概要レベル

4.5.7 実例：並列分散処理モジュール

詳細版（22KB）の内容:
  - GPU最適化の詳細コード（100行以上）
  - 理論的背景の説明
  - 複数の実装パターン
  - エッジケースの対処法

簡潔版（7KB）への変換:
  - GPU最適化チェックリスト（10行）
  - パフォーマンス指標の目標値（表形式）
  - 主要フレームワーク選択基準（早見表）
  - トラブルシューティング表

圧縮率: 約32%（7KB/22KB）
実用性: 80%の使用ケースをカバー

4.5.8 ファイル命名

# 命名規則
modular/ja/modules/[category]/[name].md          # 簡潔版（デフォルト）
modular/ja/modules/[category]/[name]_detailed.md # 詳細版

Phase 5: 品質保証

5.1 セルフレビューチェックリスト

## 一般チェックリスト
- [ ] 概要が明確で理解しやすい
- [ ] 構造が論理的で一貫している
- [ ] 実装例が動作可能
- [ ] 変数が適切に定義されている
- [ ] 依存関係が正確
- [ ] タグが包括的

## カテゴリ別追加チェック
### Expertise モジュール
- [ ] 2024-2025年の最新情報を反映
- [ ] 権威ある情報源を参照
- [ ] 理論と実践のバランス
- [ ] 実装可能なコード例

### Skills モジュール
- [ ] 具体的な実装手順
- [ ] エラーハンドリング
- [ ] パフォーマンス考慮

### Methods モジュール
- [ ] プロセスが明確
- [ ] 各ステップの成果物定義
- [ ] 実践的なアドバイス

5.2 テスト

# モジュール生成テスト
python modular/composer.py \
  --modules [module_id] \
  --output test_output.md

# 内容確認
- 正しく生成されるか
- 変数が適切に展開されるか
- 他モジュールとの統合

Phase 6: 国際化

6.1 英語版作成

# ファイル構造
modular/
├── ja/modules/[category]/[name].md
├── ja/modules/[category]/[name].yaml
├── en/modules/[category]/[name].md
└── en/modules/[category]/[name].yaml

6.2 翻訳のポイント

専門用語の正確性
文化的コンテキストの調整
コード例はそのまま維持

ベストプラクティス

1. テンプレート活用による一貫性

必須: 新規モジュール作成時はテンプレートを使用
標準化: 依存関係はオブジェクト形式（required/optional）を採用
検証: 作成後は必ず検証スクリプトを実行
命名規則: カテゴリプレフィックスの自動適用

2. 一貫性の維持

統一された構造
命名規則の遵守
スタイルガイドの順守

3. 実用性の重視

理論より実践
具体的な例の提供
すぐに使える内容

4. 保守性の確保

明確なバージョニング
更新履歴の記録
依存関係の最小化

5. 協調性

他モジュールとの連携
再利用可能な設計
明確なインターフェース

カテゴリ別ガイドライン

Expertiseモジュール

詳細は EXPERTISE_MODULE_GUIDE を参照

特徴:

深い専門知識
最新トレンドの反映
包括的な実装例
業界標準準拠

Skillsモジュール

特徴:

具体的な技術実装
ステップバイステップ
エラー処理含む
実践的なTips

Methodsモジュール

特徴:

プロセス定義
役割と責任
成果物の明確化
実施手順

トラブルシューティング

問題: モジュールが正しく読み込まれない

確認事項:
  - YAMLの構文エラー
  - IDの重複
  - 必須フィールドの欠落
  
解決方法:
  - YAMLリンターで検証
  - catalog_cache.jsonの確認
  - エラーログの確認

問題: 変数が展開されない

確認事項:
  - 変数名の一致
  - デフォルト値の設定
  - 型の整合性
  
解決方法:
  - 変数定義の見直し
  - テンプレート構文の確認

テンプレート使用ガイド

1. 新規モジュール作成手順

# 1. 適切なテンプレート選択
ls modular/ja/templates/  # 利用可能なテンプレート確認

# 2. テンプレートコピー
cp modular/ja/templates/[category]_template.yaml modular/ja/modules/[category]/[new_module].yaml

# 3. プレースホルダー置換
# エディタで以下を置換：
# [MODULE_NAME] → actual_module_name
# [説明文] → 実際の説明文
# [変数名] → 実際の変数名
# etc.

# 4. 検証実行
python3 scripts/validate_module_yaml.py modular/ja/modules/[category]/[new_module].yaml [category]

# 5. 英語版作成（必要に応じて）
cp modular/en/templates/[category]_template.yaml modular/en/modules/[category]/[new_module].yaml

2. テンプレート活用のチェックリスト

## 作成前チェック
- [ ] 適切なカテゴリのテンプレートを選択
- [ ] 既存の類似モジュールを確認（重複回避）
- [ ] 依存関係を事前に整理

## 編集中チェック
- [ ] id命名規則に従う（例: task_code_generation）
- [ ] dependenciesはオブジェクト形式を使用
- [ ] 必須フィールド（id, name, version, description）を入力
- [ ] 適切なタグを設定

## 完成後チェック
- [ ] 検証スクリプトでエラーなし
- [ ] 英語版も作成（必要に応じて）
- [ ] 統合テストで正常動作確認

3. 依存関係の正しい記述

# ✅ 推奨: オブジェクト形式
dependencies:
  required:
    - skill_api_design
    - core_role_definition
  optional:
    - skill_testing
    - quality_production

# ❌ 非推奨: 配列形式（後方互換性のみ）
dependencies:
  - skill_api_design
  - skill_testing

開発ツール

1. モジュール生成テスト

# 単一モジュールテスト
python modular/composer.py --modules [id]

# 複数モジュール統合テスト
python modular/composer.py --modules [id1] [id2] [id3]

2. 品質チェックツール

# モジュール検証（現在利用可能）
python3 scripts/validate_module_yaml.py [module_path] [category]

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

# 構造チェック（今後実装予定）
scripts/validate-module.sh [module_path]

# スタイルチェック（今後実装予定）
scripts/check-style.sh [module_path]

貢献ガイドライン

1. 新規モジュール提案

Issueで提案
既存モジュールとの差別化を説明
使用例を提示
必須: 適切なテンプレートを使用

2. 既存モジュール改善

小さな改善から開始
後方互換性の維持
テストの追加
推奨: 依存関係をオブジェクト形式に移行

3. レビュープロセス

必須: テンプレート使用の確認
必須: 検証スクリプト実行
セルフチェックリスト完了
プルリクエスト作成
レビューフィードバック対応

4. テンプレート使用義務

新規モジュール作成時は、以下を必須とする：

対応するカテゴリのテンプレートを使用
dependencies フィールドはオブジェクト形式を採用
検証スクリプトでエラーなしを確認
命名規則の遵守（カテゴリプレフィックス必須）

今後の展望

1. 自動化の推進

モジュール生成支援ツール
品質チェック自動化
依存関係の自動解決

2. エコシステムの拡大

コミュニティモジュール
モジュールマーケットプレイス
評価・レビューシステム

3. 高度な機能

条件付きモジュール読み込み
動的モジュール生成
AIによるモジュール推薦

このガイドに従うことで、高品質で再利用可能なモジュールを効率的に開発できます。質問や提案がある場合は、Issueを作成してください。