モジュール開発ガイド

目次

  1. はじめに
  2. モジュール概要
  3. サイズ基準
  4. ディレクトリ構造と命名規則
  5. 開発手順
  6. 品質基準
  7. ベストプラクティス
  8. アンチパターン
  9. 実装例
  10. 検証とテスト

はじめに

このガイドは、AI指示書キットのモジュラーシステムにおけるモジュール開発の統一的な指針を提供します。すべてのモジュール開発者は、このガイドラインに従って一貫性のある高品質なモジュールを作成してください。

モジュール概要

モジュールの種類

  1. 簡潔版(通常版) - module_name.md
    • エッセンスのみを含む効率的な指示書
    • AIのコンテキストウィンドウを考慮した最適化版
    • 一般的な使用ケースに対応
  2. 詳細版 - module_name_detailed.md
    • 完全な情報を含む包括的な指示書
    • 高度な使用ケースや詳細な要件に対応
    • ベストプラクティスと理論的背景を含む

モジュールカテゴリ

サイズ基準

明確なサイズガイドライン

簡潔版

詳細版

サイズ比率

トークン数の計算方法

# 日本語の場合(概算)
トークン数 ≈ 文字数 × 0.7

# 英語の場合(概算)
トークン数 ≈ 単語数 × 1.3

より正確な計算には、OpenAIのtiktokenライブラリを使用することを推奨します。

ディレクトリ構造と命名規則

ディレクトリ構造

modular/
├── ja/                     # 日本語版
│   └── modules/
│       ├── core/
│       ├── tasks/
│       ├── skills/
│       └── ...
├── en/                     # 英語版
│   └── modules/
│       └── ...
└── metadata/              # メタデータ
    └── ja/
        └── modules.json

命名規則

  1. ファイル名
    • すべて小文字
    • 単語はアンダースコア(_)で区切る
    • 簡潔版: module_name.md
    • 詳細版: module_name_detailed.md
  2. モジュールID
    • プレフィックス + アンダースコア + 名前
    • 例: task_code_generation, skill_critical_thinking

開発手順

1. 調査フェーズ

  1. 要件分析
    • 対象ユーザーの特定
    • 使用シナリオの明確化
    • 必要な機能の洗い出し
  2. ベストプラクティス調査
    • 業界標準の調査
    • 既存ソリューションの分析
    • 専門家の知見収集

2. 設計フェーズ

  1. 構造設計
    • セクション構成の決定
    • 変数プレースホルダーの定義
    • 条件分岐の設計
  2. コンテンツ設計
    • 必須要素の特定
    • オプション要素の定義
    • 例示の準備

3. 実装フェーズ

  1. 詳細版の作成
    • 完全な情報を含める
    • 理論的背景を説明
    • 豊富な例を提供
  2. 簡潔版の作成
    • 詳細版からエッセンスを抽出
    • 最重要ポイントのみ残す
    • 実用性を重視

4. 検証フェーズ

  1. 自動検証
    bash scripts/validate-modules.sh
    
  2. 手動レビュー
    • 内容の正確性確認
    • 使いやすさの評価
    • サイズ基準の遵守確認

品質基準

必須要件

  1. 構造
    • YAMLフロントマターの存在
    • 適切なセクション分け
    • 明確な指示
  2. 内容
    • 具体的で実行可能な指示
    • 曖昧さのない表現
    • 実用的な例
  3. 形式
    • Markdownの正しい使用
    • 一貫したフォーマット
    • 適切なコードブロック

推奨要件

  1. 可読性
    • 短い段落
    • 箇条書きの活用
    • 視覚的な区切り
  2. 拡張性
    • 変数プレースホルダーの活用
    • 条件分岐の提供
    • カスタマイズポイントの明示

ベストプラクティス

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

チェック項目

  1. 構造チェック
    • YAMLフロントマターの妥当性
    • 必須フィールドの存在
    • IDの一意性
  2. サイズチェック
    • 行数の確認
    • トークン数の推定
    • 比率の計算
  3. 品質チェック
    • Markdownの構文
    • リンクの有効性
    • 変数の整合性

関連資料


最終更新日: 2025-01-26