moai-workflow-project

MoAI ワークフロープロジェクト - 統合プロジェクト管理システム

ドキュメント生成、多言語サポート、テンプレート最適化を、インテリジェントな自動化と Claude Code との統合を備えた統一アーキテクチャに統合した、包括的なプロジェクト管理システムです。

対象範囲：ドキュメント管理、言語の初期化、テンプレート最適化を単一の統合システムに集約し、初期化から保守までのプロジェクトライフサイクル全体をサポートします。

対象：プロジェクトのセットアップ、ドキュメント生成、多言語サポート、パフォーマンス最適化を行う Claude Code エージェント。

---

クイックリファレンス

主な機能：

• ドキュメント管理：テンプレートベースの生成と多言語サポート
• 言語の初期化：検出、設定、ローカライズ
• テンプレート最適化：パフォーマンス最適化を伴う分析
• 統合インターフェース：すべての機能を利用できる単一のエントリーポイント

主な特徴：

• プロジェクトタイプの自動検出とテンプレート選択
• 多言語ドキュメント（英語、韓国語、日本語、中国語）
• ベンチマークによるインテリジェントなテンプレート最適化
• SPEC 主導のドキュメント更新
• 複数形式でのエクスポート（Markdown、HTML、PDF）

サポート対象のプロジェクトタイプ：Web アプリケーション、モバイルアプリケーション、CLI ツール、ライブラリ、ML プロジェクト。

---

実装ガイド

モジュールアーキテクチャ

3 つの機能領域：

• ドキュメント管理：テンプレートベースの生成、プロジェクトタイプの検出、多言語サポート、SPEC との連携、複数形式でのエクスポート
• 言語の初期化：自動検出、設定管理、エージェントプロンプトのローカライズ、ロケール管理
• テンプレート最適化：複雑さの分析、パフォーマンス最適化、バックアップと復元、ベンチマーク

主なワークフロー

3 つのワークフロー（プロジェクトの初期化、SPEC からのドキュメント生成、テンプレートのパフォーマンス最適化）があります。それぞれが 3 ステップのパターン（設定 → 実行 → 結果の確認）に従います。初期化と設定に関するインタビューでは、schemas/tab_schema.json で定義された質問構成を確認します。

詳しい手順については、主なワークフローの詳細を参照してください。

言語とローカライズ

言語の自動検出：ファイルの内容、設定ファイル、システムロケール、ディレクトリ構成を分析します。

多言語ドキュメント：言語別ディレクトリ（例：docs/ko、docs/en）、言語のネゴシエーション、自動リダイレクトをサポートします。

エージェントプロンプトのローカライズ：言語別の指示、文化的コンテキスト、トークンコストの最適化に対応します。

トークンコストの分析とロケールの設定については、言語とローカライズの詳細を参照してください。

テンプレート最適化

パフォーマンス分析：ファイルサイズ、複雑さ、パフォーマンスのボトルネック、最適化の機会、リソース使用量、バックアップの推奨事項を確認します。

最適化手法：空白の削減、構造の最適化、複雑さの軽減、パフォーマンスキャッシュ。

設定管理

統合設定では、プロジェクトのメタデータ、言語設定とコスト、ドキュメントのステータス、テンプレート最適化の結果、モジュールの初期化状態を管理します。

言語設定：conversation_language（ユーザー向け）、agent_prompt_language（内部向け。コストを抑えるため、英語がよく使われます）、ドキュメントの言語（言語ごと）。

更新すると、設定ファイルの変更、ドキュメント構造の更新、テンプレートのローカライズが行われます。

すべてのフィールドとサポート対象の言語メタデータについては、設定スキーマと言語フィールドを参照してください。

---

高度な実装

高度なパターン（カスタムテンプレート、パフォーマンスキャッシュ、バッチ処理、統合ワークフロー）については、references/reference.md と references/examples.md を参照してください。

---

リソース

パフォーマンス指標

操作	標準的な所要時間
ドキュメント一式の生成	2-5 秒
言語検出の分析	約 500 ms
テンプレートの最適化	10-30 秒
設定の更新	約 100 ms

メモリ：基本は約 50MB、大規模プロジェクトでは +10-50MB、最適化キャッシュは 5-20MB です。

ファイルサイズ：ドキュメントはプロジェクトあたり 50-200KB、最適化バックアップは元ファイルと同じサイズ、設定は 5-10KB です。

---

連携に適したツール

• moai-foundation-core：コア実行パターンと SPEC 駆動のワークフロー
• moai-foundation-cc：Claude Code の連携と設定
• moai-workflow-docs：統合ドキュメント管理
• moai-workflow-templates：テンプレート最適化戦略
• moai-library-nextra：ドキュメントアーキテクチャ

よくある合理化

合理化	実際のところ
「プロジェクトドキュメントの設定は一度きりなので、最新の状態に保つ必要はない」	古くなった product.md と tech.md は、それらを参照して作成されるすべての SPEC を誤った方向に導きます。これらは常に更新されるドキュメントです。
「コードベースはあまり変わらないので、structure.md は正確なままだろう」	ディレクトリを追加する PR のたびに structure.md は不正確になります。/moai project を実行するたびに同期してください。
「技術スタックは把握しているので、tech.md は必要ない」	tech.md はあなたのためのものではありません。行動する前にプロジェクトのコンテキストを確認するすべてのエージェントのためのものです。
「codemaps の生成には時間がかかりすぎる」	codemaps は、すべてのファイルを読まずにエージェントがファイル単位で状況を把握できる唯一の成果物です。その価値はコストに見合います。
「機能の完成後にプロジェクトドキュメントを書く」	事後に作成したドキュメントには、意図したことではなく、実装したことが記録されます。機能実装前のドキュメントが開発の指針になります。

注意すべき兆候

• product.md にコードベースに存在しない機能が記載されている
• tech.md に記載されたフレームワークのバージョンが、実際の依存関係ファイルと異なる
• structure.md にディスク上に存在するディレクトリが記載されていない
• プロジェクトにソースファイルが 10 個以上あるのに、codemaps/ ディレクトリが空、または存在しない
• /moai project の最終実行から 30 日以上経過している（ファイルの更新日時を確認してください）

検証

• product.md が存在し、現在の製品範囲を説明している（README と照合してください）
• tech.md に記載された依存関係が、実際のロックファイル（package.json、go.mod など）と一致している
• structure.md のトップレベルディレクトリが、プロジェクトルートでの ls の出力と一致している
• codemaps/ に、主要なパッケージまたはモジュールごとに少なくとも 1 つの codemap ファイルが含まれている
• 3 つすべてのドキュメントが、現在のセッション中または前回の構造変更以降に更新されている
• 生成されたドキュメントにプレースホルダーテキスト（「TODO」、「TBD」）が残っていない

---

テンプレートの最適化（moai-workflow-templates から統合）

コードのひな形、フィードバックテンプレート、スキャフォールディング、プロジェクトテンプレートの最適化です。

主な機能

• コードテンプレートライブラリ：FastAPI、React、Vue、Next.js のひな形
• GitHub のイシューフィードバックテンプレート：6 種類（バグ、機能、質問、ドキュメント、パフォーマンス、セキュリティ）
• プロジェクトテンプレートの最適化：サイズ削減、複雑さの分析、スマートマージ
• テンプレートのバージョン管理、バックアップの検出と復元

テンプレート適用のワークフロー

1. テンプレートのカテゴリを特定します：コードのひな形、フィードバックテンプレート、またはプロジェクトのスキャフォールド
2. プロジェクトのスタックと言語に合ったテンプレートのバリエーションを選択します
3. カスタマイズ変数（プロジェクト名、作者、ライセンス、フレームワークのバージョン）を適用します
4. レンダリング結果をスキーマまたは既存の規約に照らして検証します
5. 必要に応じてテンプレートオプティマイザーを実行し、冗長性を削減します

テンプレート最適化のプロセス

分析指標：ファイルサイズ、複雑さスコア、冗長性の割合、読み込みパフォーマンス。 最適化手法：空白の削減、重複の排除、構造の簡素化。 最適化を適用する前に、必ずバックアップを作成してください（backup: true）。

---

ドキュメント生成（moai-docs-generation から統合）

Sphinx、MkDocs、TypeDoc、OpenAPI、Nextra を使用した技術ドキュメント生成です。プロジェクト設定の検出、既存のドキュメントサイトとの統合方法、フレームワークのドキュメントと技術ガイドの内容を最新に保つためのベストプラクティスを扱います。

対応ジェネレーター

ジェネレーター	用途	主な形式
Sphinx	Python プロジェクト、API ドキュメント	RST / Markdown
MkDocs	一般的なプロジェクト	Markdown
TypeDoc	TypeScript ライブラリ	TypeScript JSDoc
OpenAPI / Swagger	REST API	YAML / JSON
Nextra	Next.js ドキュメントサイト	MDX

生成ワークフロー

1. プロジェクトの種類を検出し、適切なジェネレーターを選択します
2. ドキュメントのソースを抽出します：docstring、JSDoc、OpenAPI 仕様、SPEC ドキュメント
3. .moai/config/sections/language.yaml からプロジェクトの言語とブランディングを適用します
4. 設定された形式（Markdown、HTML、PDF）で出力を生成します
5. /moai sync の成果物を更新します：README、CHANGELOG、API リファレンス

---

JIT ドキュメント読み込み（moai-workflow-jit-docs から統合）

JIT ドキュメント（just in time docs）は、ユーザーの意図と会話のコンテキストに基づき、必要に応じてドキュメントを見つけて読み込む仕組みです。

主なツール

• WebSearch/WebFetch（, ）：公式ライブラリドキュメント
• WebFetch / WebSearch：最新のオンラインドキュメント
• Read、Grep、Glob：ローカルプロジェクトのドキュメント

トリガーパターン

• ユーザーがライブラリやフレームワークに関する具体的な技術的な質問をする
• 技術キーワード（ライブラリ名、フレームワーク名、API 名）が検出される
• ドメインの専門知識が必要になる（認証、データベース、デプロイ）
• 実行フェーズで実装ガイダンスが必要になる

読み込みの優先順位

1. ローカルプロジェクトのドキュメント（.moai/、README、SPEC ドキュメント）
2. WebSearch/WebFetch（公式の、バージョンが一致したライブラリドキュメント）
3. WebSearch + WebFetch（最新のオンラインリソース）

トークン予算：JIT 読み込みあたり 5000 トークンです。ソースが予算を超える場合は要約します。