モジュール開発ガイド
目次
はじめに
このガイドは、AI指示書キットのモジュラーシステムにおけるモジュール開発の統一的な指針を提供します。すべてのモジュール開発者は、このガイドラインに従って一貫性のある高品質なモジュールを作成してください。
モジュール概要
モジュールの種類
- 簡潔版(通常版) -
module_name.md
- エッセンスのみを含む効率的な指示書
- AIのコンテキストウィンドウを考慮した最適化版
- 一般的な使用ケースに対応
- 詳細版 -
module_name_detailed.md
- 完全な情報を含む包括的な指示書
- 高度な使用ケースや詳細な要件に対応
- ベストプラクティスと理論的背景を含む
モジュールカテゴリ
- core: 基本的な構成要素(役割定義、制約、出力形式)
- tasks: 具体的なタスク(コード生成、文書作成、分析)
- skills: 特定のスキル(批判的思考、API設計、テスト)
- expertise: 専門知識(機械学習、ソフトウェア工学)
- domains: ドメイン知識(ヘルスケア、金融、教育)
- methods: 方法論(アジャイル、リーン、スクラム)
- quality: 品質基準(プロダクション対応)
- roles: 役割(アドバイザー、コンサルタント、メンター)
サイズ基準
明確なサイズガイドライン
簡潔版
- 推奨行数: 50-200行
- 最大行数: 300行(これを超える場合は分割を検討)
- 推奨トークン数: 1,000-4,000トークン
- 最大トークン数: 6,000トークン
詳細版
- 推奨行数: 200-600行
- 最大行数: 800行(これを超える場合は必ず分割)
- 推奨トークン数: 4,000-16,000トークン
- 最大トークン数: 20,000トークン
サイズ比率
- 推奨比率: 詳細版は簡潔版の2.5-4.0倍
- 最大比率: 5.0倍
- 最小比率: 1.5倍
トークン数の計算方法
# 日本語の場合(概算)
トークン数 ≈ 文字数 × 0.7
# 英語の場合(概算)
トークン数 ≈ 単語数 × 1.3
より正確な計算には、OpenAIのtiktokenライブラリを使用することを推奨します。
ディレクトリ構造と命名規則
ディレクトリ構造
modular/
├── ja/ # 日本語版
│ └── modules/
│ ├── core/
│ ├── tasks/
│ ├── skills/
│ └── ...
├── en/ # 英語版
│ └── modules/
│ └── ...
└── metadata/ # メタデータ
└── ja/
└── modules.json
命名規則
- ファイル名
- すべて小文字
- 単語はアンダースコア(_)で区切る
- 簡潔版:
module_name.md
- 詳細版:
module_name_detailed.md
- モジュールID
- プレフィックス + アンダースコア + 名前
- 例:
task_code_generation
,skill_critical_thinking
開発手順
1. 調査フェーズ
- 要件分析
- 対象ユーザーの特定
- 使用シナリオの明確化
- 必要な機能の洗い出し
- ベストプラクティス調査
- 業界標準の調査
- 既存ソリューションの分析
- 専門家の知見収集
2. 設計フェーズ
- 構造設計
- セクション構成の決定
- 変数プレースホルダーの定義
- 条件分岐の設計
- コンテンツ設計
- 必須要素の特定
- オプション要素の定義
- 例示の準備
3. 実装フェーズ
- 詳細版の作成
- 完全な情報を含める
- 理論的背景を説明
- 豊富な例を提供
- 簡潔版の作成
- 詳細版からエッセンスを抽出
- 最重要ポイントのみ残す
- 実用性を重視
4. 検証フェーズ
- 自動検証
bash scripts/validate-modules.sh
- 手動レビュー
- 内容の正確性確認
- 使いやすさの評価
- サイズ基準の遵守確認
品質基準
必須要件
- 構造
- YAMLフロントマターの存在
- 適切なセクション分け
- 明確な指示
- 内容
- 具体的で実行可能な指示
- 曖昧さのない表現
- 実用的な例
- 形式
- Markdownの正しい使用
- 一貫したフォーマット
- 適切なコードブロック
推奨要件
- 可読性
- 短い段落
- 箇条書きの活用
- 視覚的な区切り
- 拡張性
- 変数プレースホルダーの活用
- 条件分岐の提供
- カスタマイズポイントの明示
ベストプラクティス
1. エッセンスの抽出
# 悪い例(冗長)
このモジュールは、ソフトウェア開発において重要な役割を果たすテスト駆動開発(TDD)の
実践方法について詳しく説明します。TDDは1990年代後半にKent Beckによって...
# 良い例(簡潔)
## TDD実践手順
1. 失敗するテストを書く
2. テストを通す最小限のコードを書く
3. リファクタリング
2. 変数の効果的な使用
## 設定
- 言語:
- テストフレームワーク:
- カバレッジ目標: %
3. 条件分岐の活用
### Webアプリケーション固有の考慮事項
- レスポンシブデザイン
- ブラウザ互換性
アンチパターン
1. 過度な抽象化
# 避けるべき
適切な方法で実装してください。
# 推奨
以下の手順で実装してください:
1. 入力検証
2. ビジネスロジック処理
3. 結果の返却
2. サイズ基準の無視
# 避けるべき
- 1,000行を超える詳細版
- 10行未満の簡潔版
- 詳細版の10%しかない簡潔版
3. 構造の欠如
# 避けるべき
すべての内容を1つのセクションに詰め込む
# 推奨
明確なセクション分けと階層構造
実装例
簡潔版の例
---
module_id: task_code_review
version: 1.0.0
category: tasks
name: "コードレビュー"
description: "体系的なコードレビューの実施"
author: dobachi
created_date: 2024-12-20
updated_date: 2024-12-20
tags: ["code-review", "quality", "collaboration"]
---
# コードレビュータスク
## 目的
コード品質の向上と知識共有
## レビュー観点
### 1. 機能性
- 要件の充足
- エッジケースの考慮
- エラーハンドリング
### 2. 可読性
- 命名の適切性
- コメントの質
- 構造の明確さ
### 3. 保守性
- DRY原則
- SOLID原則
- テストカバレッジ
## 出力形式
```markdown
## レビュー結果
**総評**: [LGTM/要修正/要議論]
### 良い点
- ...
### 改善提案
- ...
### 必須修正
- ...
## 検証とテスト
### 自動検証の実行
```bash
# 単一モジュールの検証
bash scripts/validate-modules.sh modular/ja/modules/tasks/code_review.md
# 全モジュールの検証
bash scripts/validate-modules.sh --all
# サイズチェックを含む検証
bash scripts/validate-modules.sh --check-size
チェック項目
- 構造チェック
- YAMLフロントマターの妥当性
- 必須フィールドの存在
- IDの一意性
- サイズチェック
- 行数の確認
- トークン数の推定
- 比率の計算
- 品質チェック
- Markdownの構文
- リンクの有効性
- 変数の整合性
関連資料
最終更新日: 2025-01-26