最終更新: 2026/06/22 18:56
commonid: rq-045-internal-docs-organization-prompttype: promptstatus: active

RQ-045 内部運用ドキュメント組織化ベストプラクティス調査プロンプト（docs/_internal/ 整理方針 ADR 起草前）

RQ ID: RQ-045
作成日: 2026-05-15
調査トリガー: ADR-0039（arc42+feature-folder 構造刷新）が docs/_internal/ を対象外としており、パイプライン・ワークフロー・運用ガイド系ドキュメントの置き場と管理方針が未定義のまま。ADR 起草の前に業界知見を収集する。
関連 ADR: ADR-0039（ドキュメント構造刷新）、ADR-0042（LLM プロンプトライフサイクル管理）
3 モデル並列調査: Gemini Deep Research / Claude Research / GPT-4o Deep Research に同一プロンプトを投入する

プロジェクト背景（モデルへの文脈提供）

調査対象プロジェクトの特性:

  • 規模: ソロ開発（まもなく 1 名 Jr. 参加）、GAS + LangGraph + Cloudflare Workers + GitHub Actions
  • ドキュメント体系: ADR（意思決定記録）が 42 本、開発仕様書が 150+ 本、アーキテクチャ資料、テスト資料などを docs/ 配下で管理
  • ADR-0039 適用済み領域: docs/dev/（仕様書）、docs/arch/（アーキテクチャ）、docs/spec/ を arc42+feature-folder 構造に再編中。この 3 ディレクトリは整理対象として明確に定義されている。
  • 未整理領域: docs/_internal/ — 30 本以上のファイルが混在。以下がその内訳:
カテゴリ代表ファイル件数概算
ワークフローガイドgit_workflow.md, trunk_based_workflow.md, customer_discovery_workflow.md, backlog_pipeline_workflow.md4
Decision Pipeline 関連decision_pipeline/（README + 5 プロンプト設計書 + 設計メモ + テストケース + 移行記録）10+
AI エージェント向けテンプレートdev_spec_prompt_template.md, ui_spec_prompt_template.md, prompt_lifecycle_guide.md3
調査管理research_questions.md, research_prompts/（RQ-001〜044、40+ ファイル）40+
運用・セットアップhooks_setup.md, migration_guide.md, workspace_rules.md, ui_verification.md, ai_agent_tips.md5
トラッキングBUG_tracking.md, changelog.md, TODO_future.md, todo_master_tables.md4
ADR 補助adr_reviews/（並列レビュー記録）, adr_skill_setup/（ツール設定素材）6
ビジネス資料biz/（稟議書テンプレート、経費規程、コンサル資料）10
その他failure_patterns.md, data_maintenance.md, guidelines_spec_template.md3
  • AI エージェント利用: Claude Code が docs/ を毎日参照。ナビゲーション効率が開発速度に直結する（ADR-0039 で「1 機能あたり平均 7.4 回のツール呼び出し」が課題として実測済み）。
  • 将来要件: Jr. エンジニア参加後のオンボーディング効率、業務委託者向けアクセス制御の検討

調査してほしいこと

Q1. 業界標準・先行事例の調査

ソフトウェアプロジェクトにおける「内部運用ドキュメント」（ADR・仕様書・コードとは別の、ワークフロー・プロセス・ガイド・調査記録類）のディレクトリ構造について:

  1. 代表的な組織化パターンを 3〜5 種類挙げ、それぞれの採用事例・メリット・デメリットを整理してください。特に:

    • docs/_internal/ や docs/.internal/ のような「隠しディレクトリ」方式
    • ops/, runbooks/, playbooks/ など機能別ディレクトリ方式
    • docs/ 配下に統合して type frontmatter で分類する方式（Diátaxis, arc42 拡張）
    • ADR + OpsDoc の統合管理（Decision Records + Operations Documentation）

  2. 命名規則・frontmatter 設計 — 人間と AI エージェント両方が機械的に分類できる標準的な方式はありますか？

  3. 調査記録・研究メモの扱い — RQ（Research Question）のような一時的・探索的ドキュメントをどう管理するのがベストプラクティスですか？アーカイブ戦略も含めて教えてください。

Q2. LLM プロンプト・AI エージェント向けドキュメントの特殊性

AI エージェント（Claude Code 等）が参照するプロンプトテンプレート・ワークフローガイドの管理について:

  1. 「コードと並走するプロンプトドキュメント」をどのディレクトリ・形式で管理するのが推奨されますか？ prompts/ を docs/ の外に出す vs 内に置く、それぞれの根拠を教えてください。
  2. AI エージェントが自律的にナビゲートしやすいドキュメント構造の設計原則はありますか？（AGENTS.md, CLAUDE.md 等の設計ガイドラインを参照しつつ）

Q3. arc42 フレームワークとの統合判断

arc42 ドキュメント構造（本プロジェクトで採用中）は「architecture/ domains/ research/ data/ operations/ implementation/」の 6 軸を定義していますが、docs/_internal/ のような「ワークフロー + 調査記録 + ツール設定」の混合コンテンツは arc42 の文脈でどう扱うのが適切ですか？

  1. arc42 の operations/ セクション（operations/itgc/）に統合する vs 独立ディレクトリとして維持する、それぞれの利点・欠点
  2. 「内部チーム向け運用ガイド」と「外部公開ドキュメント」を同一リポジトリで共存させるパターン（たとえば _internal/ プレフィックスで公開対象外を示す慣習）

Q4. 小規模チームへの適合性

ソロ〜3 名規模のソフトウェアプロジェクトで「ドキュメントの組織化に過剰投資しない」ための判断基準を教えてください:

  1. どの規模（ファイル数・チーム人数）になったら構造化投資が ROI 正当化されますか？
  2. 最小限の組織化でスケールアップに備えるための「将来拡張可能なフラット構造」はどのようなものですか？

期待するアウトプット形式

以下の構成で回答してください:

1. 業界事例サマリー（表形式）

構造パターン採用組織・プロジェクト主な対象ドキュメント種別AI ナビゲーション適性小規模チーム適性

2. 推奨ディレクトリ構造案（3 案）

本プロジェクトの docs/_internal/ 相当コンテンツを整理するための、具体的なディレクトリ構造案を 3 パターン提示してください。各案に:

  • ディレクトリツリー（tree 形式）
  • 採用の根拠
  • 移行コスト（低/中/高）
  • AI エージェント適性（理由付き）

3. Q3 の arc42 統合判断への具体的回答

arc42 の operations/ への統合 vs 独立 _internal/ 維持、どちらが本プロジェクトの状況に適しているか、理由を含めて結論を出してください。

4. 推奨事項まとめ（bizlp プロジェクト向け）

調査者（bizlp）が次のセッションで ADR を起草するための「意思決定のインプット」として、3〜5 点の具体的推奨事項をリストアップしてください。