最終更新: 2026/06/22 18:56
commonid: rq-045-internal-docs-organization-resu…type: research-resultstatus: archived

RQ-045 調査結果 (Claude Research)

RQ ID: RQ-045
調査日: 2026-05-15
調査ツール: Claude Research
元ファイル: Internal Documentation Organization Best Practices_ bizlp Project Analysis and Recommendations.pdf（14ページ）
後続作業: ADR-0040 起草インプット

ソフトウェアプロジェクトにおける「内部運用ドキュメント」の組織化ベストプラクティス

現代のソフトウェア開発において、コードベースそのものと同等、あるいはそれ以上の戦略的価値を持つのが「内部運用ドキュメント」の情報アーキテクチャである。特に、AIエージェント（Claude Code など）が日常的に自律型アシスタントとして開発ワークフローに介入する環境下では、人間の開発者とAIエージェントの双方が、文脈の喪失や認知的負荷を被ることなく効率的にナビゲーションできる構造の構築が不可避となっている。プロジェクトが小規模な段階であっても、意思決定記録（ADR）、技術仕様書（arc42）、未整理の運用ワークフロー、AIプロンプト、そして探索的な調査記録（RQ）が混在する状況は、知識のサイロ化と技術的負債の温床となり得る。

本レポートは、アーキテクチャの意思決定記録、仕様書、および運用ドキュメントの混在という課題に対し、ソフトウェアエンジニアリング業界の先行事例、情報アーキテクチャの標準的なフレームワーク、AIエージェントにおけるコンテキスト・エンジニアリングの原則、および小規模チームにおける構造化投資の費用対効果（ROI）の観点から包括的な分析を行う。そして、プロジェクトの成熟度と将来のスケールアップを見据えた、最適なディレクトリ構造と運用管理方針のベストプラクティスを提示する。

1. 内部運用ドキュメントの業界標準と先行事例

1.1 業界事例サマリー

構造パターン採用組織・プロジェクト主な対象ドキュメント種別AIナビゲーション適性小規模チーム適性
隠しディレクトリ方式 (.internal/, _internal/)一般的なOSSプロジェクト、GitHub の標準的な運用チーム固有の運用ガイド、裏議書などのビジネス資料、公開不要な運用メモ低（検索スコープから除外されやすく、ノイズが混入しやすい）高（導入が極めて容易であり、初期コストが低い）
機能・目的別分離方式 (ops/, runbooks/, prompts/)Octopus Deploy、運用成熟度の高い SRE チーム障害対応用ランブック、インシデント対応手順、LLMプロンプト高（責務が明確であり、AIツールが対象を特定しやすい）中（分類基準の維持が必要であり、ディレクトリが肥大化するリスク）
フラット + Frontmatter 方式（タグ付け分類）大規模ナレッジベース、Diátaxis 採用組織調査記録（RQ）、一時的メモ、すべての運用ドキュメント極めて高（メタデータによる高度な機械的フィルタリングが可能）高（事前の厳密な構造設計が不要であり、柔軟にスケール可能）
arc42 + Diátaxis 統合方式大規模エンタープライズプラットフォーム、Gatsby 等のドキュメント基盤アーキテクチャ決定、システム概念、チュートリアル、参照用 API中（階層が深くなりやすく、AIのコンテキストウィンドウを消費する）低（初期の設計投資コストが過大であり、維持負担が大きい）

1.2 代表的な組織化パターンの詳細な洞察

隠しディレクトリ方式は、パブリックなリポジトリにおいて外部ユーザーから内部の文脈を隠蔽するための慣習として広く用いられている。docs/_internal/ のようなプレフィックスを用いることで、既存の公開向けドキュメントツリーを変えることなく、チーム固有のプロセスやビジネスに関する資料を物理的に隔離できるという利点がある。しかし、この方式は致命的な欠陥を孕んでいる。それは、情報の用途が「内部向けであること」以外に定義されていないため、ワークフロー、調査記録、ツール設定、さらには稟議書といった性質の全く異なる情報が無秩序に放り込まれる、いわゆる「情報のゴミ箱化（Context Rot）」を引き起こしやすい点である。結果として、情報検索の効率が著しく低下し、特にAIエージェントにとっては無関係な文脈を読み込んでしまうノイズの源泉となる。

機能・目的別分離方式は、ドキュメントの「実行目的」に基づく分類である。特にランブック（運用手順書）は、ITサービス管理において、反復的なプロセスを合理化し、人的エラーを減らすために不可欠な要素として独立して管理されることが多い。ランブックの最大の価値は「単純性」にあり、障害発生時や深夜の緊急対応時において、技術的に完璧な説明よりも、迅速に問題を解決するための直線的な手順が求められる。このため、インシデント対応手順やデプロイパイプラインのガイドを docs/_internal/ の奥深くに隠すことは非効率的であり、ルートレベルに runbooks/ や workflows/ を設けて明確に分離することが推奨される。

Diátaxis フレームワークは、ユーザーの意図に基づき情報を統合管理する方式である。Diátaxis は、ドキュメントを「Tutorials（チュートリアル）」「How-to guides（ハウツーガイド）」「Reference（リファレンス）」「Explanation（解説）」の4つの象限に分類する。このフレームワークの優れた点は、情報の性質を認知心理学的な観点から明確に分離していることにある。内部チームのワークフローやランブックは明確に「ハウツーガイド」に該当し、アーキテクチャの背景説明は「解説」に、API仕様は「リファレンス」に該当する。このアプローチを採用する組織では、物理的なディレクトリの深さよりも、Frontmatter による論理的な分類タグを重視する傾向がある。

1.3 メタデータ設計と命名規則の標準化

人間とAIエージェントの双方が機械的に分類・検索できる標準的な情報アーキテクチャの構築において、YAML Frontmatter を活用したメタデータの付与がベストプラクティスとして確立しつつある。AIエージェント（特に Claude Code のようなターミナルベースのツール）は、リポジトリ全体を横断する際に grep や glob といったファイル操作プリミティブを使用する。物理的な深いディレクトリ構造は、探索のためのツール呼び出し回数を増加させ（実測された「1機能あたり平均 7.4 回の呼び出し」はまさにこれに起因する）、コンテキストウィンドウの無駄な消費（Context Bloat）を招く。

したがって、ファイルパス自体は浅く保ち、ファイルのヘッダに以下のような標準化された Frontmatter を配置し、意味論的な構造を持たせることが推奨される。

---
id: doc-045
type: workflow
domain: customer_discovery
status: active
audience: internal
---

この設計により、AIエージェントに対して「type: workflow かつ status: active のファイルを検索せよ」という明確なプロンプトを与えることができ、ファイル群のナビゲーション効率が飛躍的に向上する。また、ファイル名自体も機械可読性を高めるために、一貫したスネークケースやキャメルケースを使用し、特殊文字を避け、内容を的確に表す短い名称（例：setup_cloudflare_workers.md）にすることが求められる。

1.4 調査記録（RQ）と研究メモのアーカイブ戦略

調査記録（Research Question: RQ）のような探索的かつ一時的なドキュメントの管理は、一般的なソフトウェア仕様書とは異なるライフサイクルを持つ。学術的なソフトウェアリポジトリ管理の実践から学ぶべき教訓として、RQ のスコープ設定は反復的で漸進的なものであり、調査の進捗に応じた動的な管理が必要とされる点が挙げられる。現在 40 件以上存在する調査プロンプトや一時メモを、未整理のまま _internal/ に蓄積することは、検索時のノイズを大きくさせるだけである。

RQ ドキュメントの管理におけるベストプラクティスは、メタデータスキーマを用いてステータスを厳密に追跡することである。例えば、open（調査中）、partially_answered（部分的に回答あり）、answered（回答済み）、reframed（再構成）、closed（終了）といった状態を定義する。

アーカイブ戦略としては、不要になったファイルを単に削除して Git の履歴（git log --diff-filter=D）にのみ依存するアプローチは推奨されない。Git の履歴から情報を復元することは可能だが、AIエージェントが過去の文脈を検索（RAG やセマンティック検索）する際のハードルが著しく高くなるためである。代わりに、docs/research/archive/ などの専用アーカイブディレクトリにファイルを移動するか、ファイル名の先頭に YYYYMMDD_ などの日付プレフィックスを付与し、Frontmatter で status: archived と明記した上で、検索インデックスの優先順位を下げる手法が適切である。これにより、過去の知見を保護しつつ、日常的な検索のノイズを低減することができる。

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

AI時代のソフトウェア開発において、ドキュメントの概念は根本的な変容を遂げている。かつてドキュメントは「人間の開発者が読み物」であったが、現在では「AIエージェントが自律的にタスクを遂行するための行動規範（Behavioral Contract）」としての側面を強く持つようになった。このパラダイムシフトにより、プロンプトテンプレートやワークフローガイドの配置場所や記述形式について、新たな業界標準が形成されつつある。

2.1 コンテキスト・エンジニアリングの台頭とパラダイムシフト

AIの活用が高度化するにつれ、「プロンプトエンジニアリング」から「コンテキストエンジニアリング」へと焦点が移っている。プロンプトエンジニアリングが単発の指示の最適化に注力するのに対し、コンテキストエンジニアリングは、LLM の推論時に最適な情報（トークン）のセットをキュレーションし、維持する戦略を指す。

AIエージェントの実運用において、性能低下の最大の原因はモデルの能力不足ではなく、コンテキストの構築方法の誤りにある。コンテキストの質を管理する上で最も重要な構造的決定の一つが、「静的コンテキスト（Static Context）」と「動的コンテキスト（Dynamic Context）」の分離である。静的コンテキストは、システムプロンプト、エージェントの役割定義、ツールスキーマ、そしてコーディング規約などの「固定されたルール」であり、これらは各リクエストで再利用されるため、接頭辞キャッシュ（Prefix Caching）の恩恵を受けやすい。一方、動的コンテキストは、現在のユーザー入力やツールによるファイル検索結果など、タスクごとに変動する「状態」である。

2.2 プロンプトドキュメントの最適な配置場所

この静的・動的コンテキストの分離原則を踏まえると、「コードと並走するプロンプトドキュメント」は、結論として docs/ の外に出し、ルートディレクトリ直下の prompts/ または .github/prompts/、あるいはAIエージェント固有のディレクトリ（skills/）で管理することが強く推奨される。

その根拠は、ドキュメントとプロンプトの機能的差異にある。docs/ に格納されるアーキテクチャ記述や知識ベースは、AIにとって「必要に応じて検索して参照する動的コンテキスト」である。対して、Decision Pipeline で用いるようなプロンプトテンプレートや、AIエージェント向けのシステム指示は、AIが自身をどのように振る舞わせるかを定義する「実行可能なコードの延長」であり、静的コンテキストとしてロードされるべきものである。

多くのAIエージェント実装（GitHub Copilot、Claude Code、独自の LangGraph ワークフローなど）は、特定のディレクトリを自動的にスキャンしてツールやスキルセットとしてロードするアーキテクチャを採用している。Visual Studio Code の Copilot エージェントは .github/prompts/ フォルダをデフォルトのプロンプトファイル（.prompt.md）の保管場所として認識する。また、Claude Code や OpenAI のエージェント向けに策定されつつある「Agent Skills」のオープンスタンダードでは、SKILL.md を含む独立したスキルディレクトリ（skills/）をルート付近に配置することが提唱されている。

プロンプトを docs/ の深くに埋め込むことは、AIエージェントに対して「自身の実行用設定ファイル」と「プロジェクトの背景知識」を混同させる原因となり、結果として意図しないトークン消費やハルシネーションを引き起こす。

2.3 AIエージェント向け構造設計の原則（AGENTS.md / CLAUDE.md）

AIエージェントがリポジトリ内の情報を効率的にナビゲートし、適切なコンテキストを構築するための設計原則は、「プログレッシブ・ディスクロージャー（漸進的開示）」と「中央ナビゲーションハブの確立」に集約される。

第一に、プロジェクトのルートに配置される CLAUDE.md（またはオープン標準の AGENTS.md）の設計である。このファイルは、人間向けの README.md とは異なり、エージェントがプロジェクト内で活動するための基盤となる指示書である。しかし、ここにすべての詳細を詰め込んではならない。CLAUDE.md を数千行に及ぶ百科事典のように扱ってしまうと、エージェントはセッション開始時に大量のトークンを消費し、本当に必要な背景知識への推論能力を低下させてしまう。ベストプラクティスは、このファイルを「インデックス」または「ルーティング層」として機能させることである。ビルドコマンド、テストの実行方法、主要なコーディング規約の概要といった高頻度で必要となる静的コンテキストのみを記述し、詳細なワークフローやアーキテクチャ規約については @docs/workflows/ui_verification.md のような外部ファイルへの参照（ポインタ）のみを提供する形にとどめるべきである。エージェントは、これらのポインタを起点として、必要に応じてディレクトリ階層を潜り、詳細情報を取得する能力を備えている。

第二に、知識のモジュール化と単一責任原則の徹底である。プロンプトエンジニアリングにおける「KERNEL」フレームワークの原則の一つである「Narrow Scope（一つのプロンプトに一つの目標）」は、ドキュメント構造にも適用される。1つのドキュメントファイル内に「仕様」「テストケース」「デプロイ手順」といった複数の関心事を混在させると、エージェントは関連性の低い情報を同時に読み込んでしまい、精度が低下する。ファイル単位で文脈を厳密に分離し、AIが検索ツール（glob や grep など）で目的のファイルのみを的確にヒットできるようにすることが、無駄なツール呼び出し（現在の平均 7.4 回）を削減し、パフォーマンスを最適化する鍵となる。

第三に、明示的な制約（Constraints）の分離である。AIにとって「何をすべきか」と同じくらい重要なのが「何をしてはいけないか」である。例えば、「特定のマイグレーションファイルは編集してはならない」「.env ファイルはコミットしてはならない」といったクリティカルな制約は、各ワークフローの末尾に埋め込むのではなく、ルートの CLAUDE.md に静的コンテキストとして記述し、常にAIの意識（アクティブメモリ）に留めておく必要がある。

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

本プロジェクトでは、docs/dev/、docs/arch/、docs/spec/ において既に arc42 と feature-folder 構造を組み合わせて採用している。この高度に構造化されたアーキテクチャ文書のフレームワークに対し、現在の docs/_internal/（ワークフロー、調査記録、ツール設定などの混合物）をどう扱うかという問題は、情報アーキテクチャ設計における責務の境界線をどこに引くかという議論に帰着する。

3.1 arc42 における「運用（Operations）」の定義と限界

arc42 は、システムの「ソフトウェアアーキテクチャ」を文書化し、ステークホルダー間で共有するための標準的なテンプレートである。arc42 の構造には、「Runtime View（第6章）」「Deployment View（第7章）」「Crosscutting Concepts（第8章）」が含まれており、これらは確かに運用（Operations）に関連する要素を含んでいる。

しかし、arc42 の公式ガイダンスやベストプラクティスを紐解くと、ここで記述されるべきは「運用要件を満たすためのアーキテクチャ上の戦略や構造（例：デプロイメントのトポロジー、分離レベル、可観測性の仕組み）」であることが明確に示されている。arc42 の設計思想において、アーキテクチャ文書に「含めるべきではない」と明記されている要素が存在する。

  • 詳細な内部パーツの分解や依存関係
  • ステップバイステップのインタラクションフローやシナリオの記述（Step-by-step interaction flows）
  • 環境固有の運用詳細（Environment-specific operational details）
  • 頻繁に変更される可能性のあるスプリントレベルの技術的選択

現在の docs/_internal/ に含まれている git_workflow.md、customer_discovery_workflow.md、ツールのセットアップガイドなどは、まさにこの「ステップバイステップのフロー」であり、「頻繁に変更される運用詳細」である。

3.2 統合か独立か：Q3 への具体的回答

結論として、docs/_internal/ 相当の運用コンテンツを arc42 の枠組み（operations/ など）に統合することは推奨されない。独立したディレクトリ、または目的別に再編したルートレベルのディレクトリとして維持すべきである。

この結論に至る最大の理由は、arc42 の目的（システム構造の記述）と運用ドキュメントの目的（人間やAIの行動のガイド）の間に存在する致命的な不一致である。技術文書の品質要件として「正確性（Correct）」と「最新性（Current）」が挙げられるが、静的であるべきアーキテクチャ文書と、日々のプロセス改善で変化する運用ワークフローを同じ場所に格納すると、変更頻度の高い運用ドキュメントの更新がアーキテクチャ文書全体の見通しを悪化させ、保守性を著しく低下させる結果となる。運用手順をアーキテクチャの一部として扱うことは、Diátaxis の文脈で言えば、構造を説明する「Reference/Explanation」の中に、作業手順を示す「How-to」を混入させるアンチパターンに等しい。

3.3 内部ガイドと外部向け仕様の共存パターン

「内部チーム向けの運用ガイド」と「システム全体のアーキテクチャ仕様書」を同一リポジトリ内で共存させるための適切なアプローチは、関心事の分離（Separation of Concerns）をディレクトリ構造レベルで明示することである。

ソフトウェア工学の実用的なアプローチとして、リポジトリ内でドキュメントのスコープをトップレベルのディレクトリ名で宣言する手法が一般的である。

  • docs/：システムのアーキテクチャ、仕様、機能設計を記述する領域（arc42 の管轄）
  • workflows/ または runbooks/：チームメンバーが「どのように働くか」を規定するステップバイステップのガイドライン
  • prompts/：AIエージェントが「どのようにタスクを処理するか」を規定するテンプレート群

このように情報の用途に応じて分離することで、人間の開発者もAIエージェントも、「システムの構造を知りたい」のか「日々の作業手順を知りたい」のかによって、探索すべきスコープを即座に絞り込むことができる。

また、将来要件として挙げられている「業務委託者向けのアクセス制御」を考慮する場合、リポジトリ全体を共有しつつ特定の情報のみを制限する運用が必要になる。この場合、プレフィックス（_internal/ のような _ や .）による紳士協定的な隠蔽は、セキュリティ上の実効性が薄い。代わりに、アクセスを制限すべきビジネス資料（稟議書など）や機密性の高い運用ガイドを完全に別のディレクトリ（例：biz/ や restricted_ops/）に分離し、Git のサブモジュール化を行うか、GPG と git-crypt 等の暗号化ツールを用いて特定のディレクトリのみを保護するアプローチが現実的である。小規模なフェーズにおいては、情報の「用途」によるディレクトリ分割を徹底することが、結果として将来のアクセス制御の基盤を構築することに繋がる。

4. 小規模チームへの適合性と ROI

ソロ開発から将来的にジュニアエンジニア 1 名が加わるという本プロジェクトのフェーズにおいて、情報アーキテクチャの設計で最も警戒すべきアンチパターンは「将来の大規模化を見据えた過剰なエンジニアリング」である。ドキュメントの構造化は、それ自体が目的化すると開発のベロシティを著しく低下させ、本来の目的である価値提供を遅延させる。

4.1 構造化投資の ROI と判断基準

小規模チームにおけるドキュメント構造化の投資対効果（ROI）は、「ルールの維持にかかる継続的なコスト」と「情報検索やオンボーディングで節約される時間（生産性の向上）」のトレードオフによって決定される。

構造化への移行を正当化するための具体的な判断基準として、以下の経験則が有効に機能する。

  1. 「3の法則（Rule of Three）」の適用 ソフトウェアのリファクタリングにおける有名なヒューリスティックに「3の法則（コードが3回重複したら抽象化してリファクタリングせよ）」がある。ドキュメントの組織化においても、この法則が適用できる。「同じ種類のファイル（例：ワークフロー文書、RQ 記録）が3つを超えた時点」で、初めて専用のディレクトリ構造や標準的なメタデータを導入すべきである。現在の docs/_internal/ には既に 40 以上の RQ ファイルや複数のワークフロー、AIテンプレートが存在しているため、この領域における構造化投資の ROI はすでに十分に正当化される規模に達していると言える。

  2. コンテキスト・スイッチングによるブロック時間の発生 ソロ開発者であっても、過去の設計理由や運用手順を思い出すために、コードや複数のドキュメントファイルを行ったり来たりする時間（コンテキスト・スイッチング）が週に数時間に及ぶ場合、それは現在の構造が限界を迎えている強いシグナルである。AIエージェントが「1機能あたり平均 7.4 回」もツールを呼び出しているという事実は、AIにとってもコンテキスト・スイッチングのコストが肥大化していることを示しており、構造化の緊急性を裏付けている。

  3. オンボーディングのボトルネック化 チームメンバー（ジュニアエンジニアなど）が新たに参加する直前のフェーズは、ドキュメントの質と構造を評価する最大の試金石となる。作業手順や環境構築について、口頭やチャットで繰り返し説明しなければならない事項が存在する場合、それは暗黙知を明示的なワークフロー・ドキュメント（How-to guide）として切り出し、適切な場所に配置すべきである。これにより、オンボーディングの立ち上がり時間が短縮され、即座に ROI として還元される。

4.2 スケールアップに備えるフラット構造と「3の法則」

過剰な初期投資を避けつつ、将来のプロジェクト規模拡大（スケールアップ）に備えるためのアプローチは、「物理的な階層は極力浅く保ち（フラット構造）、論理的な意味付けと分類をメタデータに委譲する」ことである。

深いディレクトリツリー（例：docs/_internal/workflows/engineering/frontend/）は、ファイルの置き場所に関する些末な議論を生み出し、またAIエージェントがディレクトリをスキャンして全体像を把握する際のレイテンシを増加させる。代わりに、フラットなディレクトリ構造（例：runbooks/workflows/ の直下にすべて配置）を採用し、ファイル命名規則と Frontmatter によって文脈を付与する。

ファイル命名規則の標準化による拡張性の確保：ファイル名は短く、一貫性を持たせ、目的が一目でわかるように構成する。

  • 良い例：setup_cloudflare_workers.md（何についてのセットアップ手順か明確）
  • 悪い例：setup.md（コンテキストが不明確で衝突しやすい）、how_to_setup_the_new_cloudflare_workers_environment.md（長すぎてノイズになる）

このフラットな構造と明確な命名規則の組み合わせは、人間の開発者にとっては検索や一覧化が容易であり、AIエージェントにとっては一括でのコンテキスト読み込み（Glob パターンの適用によるファイルの特定）が最も機能しやすい、シンプルかつ堅牢な形となる。

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

現在の docs/_internal/ 相当のコンテンツ（30以上の混在ファイル、およびRQなど 40 以上のファイル）を整理するため、プロジェクトの現状、将来のオンボーディング要件、そしてAIエージェントのコンテキスト効率を総合的に考慮したディレクトリ構造案を3パターン提示する。

案1: 責務分離・意図主導型（Separation of Concerns / Intent-Driven）- 最も推奨

ドキュメントの「性質」と「用途」に基づいて、docs/ から実行・運用系のコンポーネントを完全に分離するパターン。システム構造（arc42）、運用手順、プロンプト、調査をトップレベルで独立させる。

/ (Project Root)
├── .github/
│   └── prompts/                # [新規] Decision Pipeline等、AIがシステム的に利用するプロンプト群
├── docs/                       # システムアーキテクチャと仕様の保管庫 (arc42/feature-folder 維持)
│   ├── arch/
│   ├── dev/
│   ├── spec/
│   └── research/               # [新規] RQや技術検証の記録（一時的・探索的）
│       ├── active/             # 進行中のRQ
│       └── archive/            # 完了したRQ（YYYYMMDD_RQ-XXX.md 形式）
├── runbooks/                   # [新規] 人間とAI向けのステップバイステップ運用手順
│   ├── workflows/              # git_workflow, backlog_pipeline 等
│   └── setup/                  # hooks_setup, migration_guide 等
├── biz/                        # [新規] 稟議書、経費等の純粋なビジネス資料
├── CLAUDE.md                   # AIエージェントのナビゲーションハブ（runbooks等へのポインタを記載）
└── README.md                   # 人間向けのプロジェクトハブ
  • 採用の根拠: ドキュメント、手順書、プロンプトという全く異なる性質のファイルが混在する現在の問題を根本的に解決する。特にAIエージェントは runbooks/ や .github/prompts/ のような一般的なディレクトリパスを効率的に解釈できる。ビジネス資料（biz/）を完全に切り離すことで、将来的なアクセス制御（サブモジュール化や暗号化）も容易になる。
  • 移行コスト: 中。ディレクトリの移動と Git の履歴管理が必要となる。また、既存の参照リンク（markdown 内部の）の修正が発生する。
  • AIエージェント適性: 極めて高。動的な知識（docs/）と静的な振る舞い（prompts/, runbooks/）が分離されており、不要なビジネス資料をAIの検索スコープから安全に除外できる。Claude Code のナビゲーションと推論が劇的に効率化される。

案2: 隠しディレクトリ拡張型（Extended Hidden Flat）

既存の _internal/ のコンセプトを維持しつつ、その内部をフラットに保ち、名前空間と Frontmatter で分類する最小限の変更アプローチ。

/ (Project Root)
├── docs/
│   ├── arch/
│   ├── dev/
│   ├── spec/
│   └── .internal/              # [改名/再編] 公開ドキュメントツリーから隠蔽
│       ├── RQ/                 # 全ての RQ ファイル（フラットに配置、Frontmatter で状態管理）
│       ├── prompts/            # エージェント用テンプレート
│       ├── workflows/          # 運用手順、セットアップ手順
│       └── biz/                # ビジネス資料
├── CLAUDE.md
└── README.md
  • 採用の根拠: 「内部向けの雑多なものは見えない場所に置く」というOSSプロジェクトの伝統的な慣習に即している。docs/ 内部のパス変更だけで済むため、既存の開発フローを大きく変えることなく導入できる。
  • 移行コスト: 低。ディレクトリのリネームとファイルの移動のみで完了する。
  • AIエージェント適性: 中。docs/.internal/ という単一のディレクトリ階層をスキャンすれば済むため、探索のオーバーヘッド自体は少ない。しかし、プロンプト、運用手順、そしてビジネス資料が隣接しているため、AIが検索を実行した際に不要な文脈（ノイズ）を含みやすいという欠点（Context Bloat のリスク）は残存する。

案3: Diátaxis ハイブリッド統合型（Diátaxis Hybrid）

Diátaxis フレームワークの「Tutorials / How-to / Reference / Explanation」の思想をディレクトリ名に取り入れ、ドキュメントの目的に応じて強制的に分類するパターン。

/ (Project Root)
├── docs/
│   ├── arch/                   # (Reference/Explanation 相当)
│   ├── dev/                    # (Reference 相当)
│   ├── spec/                   # (Reference 相当)
│   ├── how-to/                 # [新規]（旧 _internal のワークフロー、セットアップガイド）
│   │   ├── engineering/
│   │   └── business/           # ビジネス資料も手順として吸収するか、別途管理
│   └── research/               # [新規]（Explanation 相当）RQ ファイル群
├── templates/                  # [新規]（旧 _internal のAIエージェント用プロンプト等）
├── CLAUDE.md
└── README.md
  • 採用の根拠: 情報アーキテクチャのベストプラクティスである「ユーザーの意図」に基づいた強固な分類を強制する。すべてのガイドが「どのようにタスクを完了するか」という目的ベースで整理されるため、情報のサイロ化を防ぐことができる。
  • 移行コスト: 高。各ドキュメントの内容を精査し、それが How-to なのか Explanation なのかを判断した上で再配置する必要がある。既存ファイルの分割や書き直し（ドキュメントのリファクタリング）が発生する可能性が高い。
  • AIエージェント適性: 高。エージェントが「手順を知りたい」場合は how-to/ を、「背景を知りたい」場合は research/ または arch/ を参照するという明確な論理的構造が存在するため、意図に沿った的確なツール呼び出しが可能になる。

6. ADR 起草に向けた推奨事項まとめ

次回のセッションで起草される「ADR-XXXX（運用ドキュメント・AIプロンプトの組織化と管理方針）」に向けた意思決定のインプットとして、本調査に基づく以下の5点を具体的に推奨する。

推奨1: 運用・手順（Runbooks/Workflows）をアーキテクチャ（arc42）から分離する

arc42 の operations/ セクションへの運用手順の統合は避け、docs/ の外（または明確に切り離されたルート直下の runbooks/ や workflows/）にステップバイステップの運用ガイドを移行する。これにより、静的なシステム仕様と、頻繁に更新される動的な運用手順のライフサイクルを明確に分断し、AIと人間の双方の検索精度を向上させる。

推奨2: 「実行可能なコンテキスト（LLMプロンプト）」を知識ベースから切り出す

Decision Pipeline 関連やAIエージェント向けテンプレートなど、システムやエージェントが「実行」のために参照するプロンプトファイルは、人間向けのドキュメントとして扱うべきではない。これらは .github/prompts/ または skills/ として独立させ、コードベースの構成要素の一部として厳密にバージョン管理する。

推奨3: CLAUDE.md を「百科事典」から「ナビゲーションハブ」へ再定義する

Claude Code の毎日の参照効率（現状1機能あたり 7.4 回の呼び出しという課題）を改善するため、CLAUDE.md の中に詳細なルールや長大な手順を直接記述するのをやめる。代わりに、「システムアーキテクチャについては docs/arch/ を参照」「顧客発見プロセスについては runbooks/workflows/customer_discovery_workflow.md に従う」といった「ポインタ（インデックス）」の記述に限定し、プログレッシブ・ディスクロージャー（漸進的開示）を実現する。

推奨4: 調査記録（RQ）に状態ベースのライフサイクルとアーカイブ戦略を導入する

40 件以上存在する RQ ファイルは、フラットな docs/research/ 構造に移動した上で、YAML Frontmatter に status: [open | answered | archived] などのメタデータを導入し、状態管理を行う。アーカイブされた RQ は archive/ ディレクトリに移すか、ファイル名に日付プレフィックス（YYYYMMDD_）を付けて、AIの検索時に最新のアクティブなコンテキストと競合してノイズにならないようにする。

推奨5: 構造化投資の上限（Rule of Three）を ADR に明記する

ソロ開発からジュニアエンジニア 1 名が参加する現在のフェーズにおいて、過剰な階層化を防ぐため「同じ目的・性質のファイルが 3 つ未満の場合は、専用のディレクトリを作成せずルートに置くか、既存のフラットな構造に統合する」という原則（Rule of Three）を ADR の制約事項として記録し、将来のチームスケールアップ時の過剰投資を防ぐガイドラインとする。

引用文献

  1. What is Internal documentation? Types, best practices & tools - Port.io
  2. Repository Naming and Documentation Conventions - GitHub
  3. GitHub Repository Best Practices - DEV Community
  4. Runbooks Best Practices | Octopus blog
  5. Introduction to Runbooks - Splunk
  6. Info Architecture for Docs: February 2026 - Fern
  7. Diátaxis (diataxis.fr)
  8. Nine best practices for research software registries and repositories - PMC
  9. Infrastructure in architectural documentation - INNOQ
  10. "Diátaxis" documentation structure - Community - OCaml Discuss
  11. How-to guides - Diátaxis
  12. Claude Code overview - Claude Code Docs
  13. Effective context engineering for AI agents - Anthropic
  14. Effective Context Engineering for AI Agents: A Developer's Guide
  15. Document naming conventions - Records & Information - The University of Melbourne
  16. File management - Cornell Data Services
  17. File Naming | Research Data Management - UBC Library
  18. Naming conventions | Records Management - Data Protection - The University of Edinburgh
  19. Developing research questions in conversation with the literature - PMC
  20. infinitywings/rka: Research Knowledge Agent - GitHub
  21. How to clean up and create a Archiving strategy for a folder on Github - Stack Overflow
  22. File Naming Conventions - Harvard Biomedical Data Management
  23. Context Engineering for AI Agents: A Deep Dive | Towards Data Science
  24. Use prompt files in VS Code
  25. Agent Skills Overview - Agent Skills
  26. AI Agent Skills Explained Simply - Medium
  27. Deep Dive into Context Engineering for Agents - Galileo AI
  28. New research: AGENTS.md files reduce coding agent success rates
  29. A Complete Guide To AGENTS.md - AI Hero
  30. Writing Your First SKILL.md: Step-by-Step | Termdock
  31. I Built the World's First Self-Learning AI Operating System - Medium
  32. The Complete Guide to CLAUDE.md: Memory, Rules, Loading, and Cross-Tool Compression
  33. The Complete Guide to AI Agent Memory Files (CLAUDE.md, AGENTS.md, and Beyond)
  34. AI Engineering Guide: Part 1 — CLAUDE.md and AGENTS.md
  35. After 1000 hours of prompt engineering, I found the 6 patterns that actually matter - Reddit
  36. Claude Code Prompts: Best Templates and Developer Practices - QuantumByte
  37. An introduction to arc42 - Medium
  38. arc42 Template Overview
  39. arc42 chapter 4: Solution strategy
  40. Episode 271 - The Architecture of the Death Star - 20 Years of arc42
  41. Principles of technical documentation - arc42
  42. kriasoft/Folder-Structure-Conventions - GitHub
  43. Standard Go Project Layout - GitHub
  44. Organizing your projects — Reproducible research documentation
  45. Appropriate naming for (GitHub) repositories belonging to the same project
  46. About repositories - GitHub Docs
  47. How to Restrict access to company's sensitive information for a developer from other country? - Stack Overflow
  48. Protecting Sensitive Documentation in Git Repositories - Medium
  49. Locking Down GitHub Enterprise: A Security-First Approach
  50. How Documentation Can Help Your Team Scale - DEV Community
  51. Calculating the ROI of documentation and knowledge bases - KnowledgeOwl
  52. The ROI of investing into Developer Experience | DX Heroes
  53. Challenges and Paths Towards AI for Software Engineering - arXiv
  54. TECHNISCHE UNIVERSITÄT MÜNCHEN Empirical Analysis of the Adoption of Large-Scale Agile Development Methods
  55. Indie Developers - How much documentation do you do? : r/gamedev - Reddit
  56. How to quantify the ROI of documentation to convince leadership? - Reddit