majiayu000 Documentation Architecture
概要
ドキュメント構造設計・リソース分割・階層設計を専門とするスキル。500行制約に基づく適切なファイル分割とトピックベース組織化により、保守性と発見可能性の高いドキュメントアーキテクチャを実現する。
ワークフロー
Phase 1: 構造分析
目的: 現在のドキュメント構造を評価し、改善点を特定
アクション:
scripts/analyze-structure.mjsで構造を分析- 500行超過ファイルを検出
- 階層深度と命名一貫性を評価
- 改善優先度を決定
Task: agents/analyze-structure.md を参照
Phase 2: 組織化設計
目的: 最適なディレクトリ構造とファイル分割を設計
アクション:
- トピックベースの組織化戦略を決定
- ファイル分割パターンを選択
- 命名規則を統一
- 階層構造を設計
Task: agents/design-organization.md を参照
Phase 3: 構造再編実装
目的: 設計に基づいて構造を再編し、検証する
アクション:
- ディレクトリ構造を作成
- ファイル分割を実行
- 相互参照を更新
scripts/validate-structure.mjsで検証scripts/log_usage.mjsで記録
Task: agents/implement-restructure.md を参照
Task仕様ナビ
| Task | 起動タイミング | 入力 | 出力 |
|---|---|---|---|
| analyze-structure | Phase 1開始時 | 対象ディレクトリ | 分析レポート |
| design-organization | Phase 2開始時 | 分析レポート | 設計書 |
| implement-restructure | Phase 3開始時 | 設計書 | 再編済み構造 |
詳細仕様: 各Taskの詳細は agents/ ディレクトリを参照
ベストプラクティス
すべきこと
| 推奨事項 | 理由 |
|---|---|
| 分析スクリプトを先に実行 | 客観的データに基づく設計 |
| 1ファイル1トピック原則 | 発見可能性と保守性の向上 |
| 4層以下の階層に抑える | 深すぎると発見可能性が低下 |
| 命名規則を統一 | 一貫性による認知負荷軽減 |
| 500行制約を遵守 | 可読性と管理性の確保 |
避けるべきこと
| 禁止事項 | 問題点 |
|---|---|
| 分析なしでいきなり実装 | 不適切な構造設計のリスク |
| 複数トピックの混在 | 発見可能性と保守性の低下 |
| 過度な分割 | 管理コスト増大 |
| 循環参照 | 依存関係の複雑化 |
リソース参照
scripts/（決定論的処理）
| スクリプト | 機能 |
|---|---|
analyze-structure.mjs |
構造分析と違反検出 |
validate-structure.mjs |
構造検証 |
log_usage.mjs |
フィードバック記録 |
references/（詳細知識）
| リソース | パス | 読込条件 |
|---|---|---|
| 組織化パターン | references/organization-patterns.md | 設計時に参照 |
| 命名規則 | references/naming-conventions.md | 命名検討時に参照 |
| 分割戦略 | references/splitting-strategies.md | 分割設計時に参照 |
assets/（テンプレート）
| アセット | 用途 |
|---|---|
structure-template.md |
ドキュメント構造テンプレート |
変更履歴
| Version | Date | Changes |
|---|---|---|
| 2.1.0 | 2026-01-01 | 18-skills.md仕様完全準拠版に再構築 |
| 2.0.0 | 2025-12-31 | 初版作成 |