RQ-045 調査結果 (ChatGPT Deep Research)

RQ ID: RQ-045
調査日: 2026-05-15
調査ツール: ChatGPT (Deep Research)
元ファイル: 内部運用ドキュメントの組織化ベストプラクティス調査報告.pdf（10ページ）
後続作業: ADR-0040 起草インプット

結論の要約

公開されている実務例を見る限り、ソフトウェアプロジェクトの「内部運用ドキュメント」に単一の業界標準ディレクトリはありません。ただし、かなり強い収束はあります。具体的には、運用手順は中央の置き場に集約すること、文書タイプとライフサイクルを frontmatter などのメタデータで明示すること、研究・提案・意思決定・実運用手順は同じ "知識体系" に置いても別タイプとして扱うこと、そしてAIエージェント向け文書は「常時読む短いルート文書」と「必要時だけ読む詳細ルール／スキル」に分けることです。Diátaxis は文書を利用者ニーズ別に分け、GitHub Docs・Microsoft Learn・Docusaurus・MkDocs は frontmatter とナビゲーション情報でページの種類を機械可読化し、AWS・GitLab・Prometheus は runbook / playbook を中央管理し、OpenAI と Anthropic はエージェント向け指示ファイルとスキルを正式に階層化しています。

bizlp プロジェクトに対する結論を先に言うと、docs/_internal/ の全量を arc42 の operations/ に吸収するのは非推奨です。 arc42 の公式テンプレートでは運用に関わる内容は主に Runtime View、Deployment View、Crosscutting Concepts、Architectural Decisions にまたがっており、そこで扱うべきなのは「システム運用に直接関係する情報」です。一方、現在の _internal には、ワークフロー、研究記録、AI エージェント用テンプレート、ADR 補助、ビジネス資料まで含まれており、これは arc42 の運用セクションよりも広い「内部ハンドブック」領域です。したがって、_internal は内部ハンドブックとして再編し、その中から "真にシステム運用で使う文書" だけを operations 相当に昇格させ、実行される プロンプトやエージェント手順は .claude/ / .agents/ 側へ分離するのが最も整合的です。

あなたのプロジェクトは、まだ小規模チームではあるものの、すでに「構造化投資の ROI が出る段階」に入っています。これは厳密な業界人数閾値があるという意味ではなく、AWS が runbook を中央管理し新メンバーの立ち上がりを早めることを勧め、GitHub Docs が content model によって混在する文書を維持可能にし、OpenAI / Anthropic が大きなロジックは別プロジェクト向けにルート指示・ネスト指示、必要時ロードを備えていることから導ける実務上の判断です。加えて、あなたの文脈では「Jr. 参加」「日常的に Claude Code が docs/ を読む」「_internal がすでに混合状態」という三条件が揃っています。

業界事例サマリー

この表の「AIナビゲーション適性」と「小規模チーム適性」は、公開仕様そのものではなく、本報告の評価です。評価軸は、ルートからの発見しやすさ、階層の安定性、必要なときだけ深い文書を読む仕組みがあるか、文書の役割が名前やメタデータで判別できるかです。特に OpenAI / Anthropic のエージェント設計は「ルート文書＋局所 override ＋ on-demand skill」という構造を明示しているため、この観点では最も高く評価できます。

実務的に重要なのは、「隠すこと」と「分類すること」は別問題だという点です。_internal/ や .internal/ は静的サイト生成や公開除外には便利ですが、それだけでは文書タイプの混在を解決しません。逆に frontmatter だけで分類しても、公開対象と対象の境界が曖昧だと将来のアクセス制御に弱くなります。うまくいっているプロジェクトは、この二つを併用しています。

命名規則と研究記録の扱い

命名規則と frontmatter 設計

人間と AI の両方にとって使いやすい「標準的な方式」は、厳密には単一標準ではなく、YAML frontmatter とファイルシステム由来のナビゲーションを組み合わせる方式です。GitHub Docs は frontmatter をテストで検証し、Microsoft Learn は ms.topic、所有者、日付などを必須にし、Docusaurus は tags / id / slug を frontmatter で調整し、MkDocs も front-matter をページテンプレートへ渡します。Anthropic の .claude/rules も YAML frontmatter の paths で適用範囲を限定します。つまり、「パスで大分類、frontmatter で機械分類」が現在の実務上の共通解です。

命名規則は、GitHub Docs と Docusaurus の実践をベースにすると、かなり素直に設計できます。具体的には、ファイル名は kebab-case、セクション入口は index.md か README.md、ファイルツリーは可能な限りナビゲーションを反映、ルール/ガイド類はトピック名そのものをファイル名にする、という形です。GitHub Docs は新規記事をタイトル由来の kebab-case で命名するよう求め、Docusaurus はファイルシステムがサイドバー構造を反映するよう推奨し、Anthropic は rules ファイルを testing.md や api-design.md のような説明的ファイル名で置くよう案内しています。

この観点から、bizlp プロジェクトには次のような最小共通 frontmatter を勧めます。これは単一プロダクトの公式標準ではなく、GitHub Docs / Microsoft Learn / Azure ADR / Docusaurus / Claude rules の共通部分を寄せた実務上の推奨スキーマです。

---
title: Git workflow
short_title: Git workflow
type: workflow         # workflow | runbook | playbook | research | prompt | policy | setup | tracking
status: active         # draft | active | accepted | superseded | archived
visibility: internal   # public | internal | restricted
audience: both         # human | agent | both
owner: bizlp
reviewed_on: 2026-05-15
review_cycle_days: 90
related_adrs: [ADR-0039]
tags: [git, workflow]
system_scope: repo
agent_load: on-demand  # always | on-demand | never
---

特に効くのは、type、status、visibility を必ず分けることです。type は「何の文書か」、status は「今どういう段階か」、visibility は「誰に見せるか」であり、この三者を一つの語で兼用すると検索にも自動分類にも弱くなります。Microsoft Learn は記事種別・所有・更新日を、Azure ADR は status を、それぞれ別フィールドとして扱っています。

調査記録と研究メモの扱い

RQ のような探索的ドキュメントは、恒久的な reference 文書として扱うより、RFC / proposal / research stream として扱う方が成功しやすいです。Rust RFCs と Vue RFCs は明確なライフサイクルを持ち、Python PEP は固定 ID と永続的な履歴を持ち、dotnet/vblang は proposals と meetings を分け、実装済み提案と rejected 提案をアーカイブします。Prometheus も proposals を「現在と過去の提案の単一の場所」と位置づけています。

したがって、bizlp の RQ-001〜044 は、単なる research_prompts/ の羅列ではなく、少なくとも次のライフサイクルを持たせるのがよいです。open → active → synthesized → archived です。ここで synthesized は「結論が ADR / spec / runbook / guide に昇格済み」を意味し、元の RQ は削除せずアーカイブへ移します。Python PEP が「番号は変えず、版管理履歴が歴史記録になる」としているのは、この考え方に非常に近いです。

運用上は、質問本体・調査プロンプト・証拠/所見・昇格先リンクを分けるのが実用的です。つまり、RQ-045.md に問い・範囲・結論要約を置き、実際に使ったプロンプトは prompts/、途中メモは notes/、最終的に反映された ADR や spec は derived_to: などで相互リンクします。こうすると、一時的な探索ノイズを残しつつ、AI と人間の双方が「最終結論」と「探索の経路」を区別できます。これは Vue / Rust の RFC 運用、vblang の proposals + meetings + archive の分離と整合します。

AIエージェント向け文書の設計原則

OpenAI と Anthropic の公式ガイドは、AI エージェント向け文書の置き方についてかなり明確です。常時読ませたいルールはルート文書に短く書き、局所的・手続き的・長文のものはネスト指示やルール、skills に分ける、という設計です。Codex は AGENTS.md を作業前に読み、プロジェクトルートから作業ディレクトリまで階層的に指示を連結します。Claude Code は CLAUDE.md / CLAUDE.local.md を作業開始時に読み込み、サブディレクトリの CLAUDE.md はその配下のファイルを読んだときだけ読みます。Anthropic はさらに「具体的で簡潔な指示ほど一貫して従いやすい」「200 行を超えるファイルは文脈を圧迫しやすい」と明言しています。

docs/ の外に置くべきもの

プロンプト自体が "実行資産" である場合は、docs/ の外へ出した方がよいです。 具体的には、AGENTS.md、CLAUDE.md、.claude/rules/、.claude/skills/、.agents/skills/ のような、ツールが正式に発見・ロードする場所です。OpenAI の skills は .agents/skills に置いて、リポジトリ内の現在位置からルートまで走査されます。Anthropic の skills は SKILL.md で定義し、同じ指示やチェックリストを何度も貼っているなら skill 化せよ、CLAUDE.md の一部が procedure になったなら skill 化せよ、と案内しています。どちらも本文は必要時だけロードされるため、長い手順書を常時コンテキストに入れなくて済みます。

このため、dev_spec_prompt_template.md、ui_spec_prompt_template.md、Decision Pipeline のプロンプト設計書のうち、エージェントが直接読む・呼び出す・再利用するものは、長期的には docs/_internal/ ではなく .claude/skills/ または .agents/skills/ に寄せるのが推奨です。 そこでは prompt は「文書」ではなく「ワークフロー定義」になります。Anthropic は skill に supporting files や動的コンテキスト注入を持たせられ、OpenAI も scripts / references / assets を skill ディレクトリに同梱できます。

docs/ の中に置くべきもの

逆に、人間向けの説明、設計理由、レビュー記録、テンプレート利用ガイド、ライフサイクル方針は docs/ 側に残すべきです。Anthropic は CLAUDE.md が @ 構文で README やワークフローガイドを参照できることを示しており、既存の AGENTS.md から import して重複を避けることを示しています。つまり、ツールが読む"薄い入口"と、人間が読む"詳しい解説"を分けるのが正式サポートされたやり方です。

したがって、最適解は docs/ 内か外かの二択ではなく「二層構造」です。docs/_internal/agents/ には方針・設計・レビュー・使い方を置き、.claude/ や .agents/ には実行されるルール・skills・テンプレート実体を置きます。これなら、Claude Code や Codex は軽く・局所的にナビゲートでき、人間は docs/ 側で文脈と理由を追えます。

AI エージェントが自律ナビゲートしやすい構造原則

AI エージェント向けには、設計原則を四つに絞るのが有効です。

1. ルートに短い入口を置くこと。AGENTS.md や CLAUDE.md は repo layout、重要ディレクトリ、実行コマンド、禁止事項、完了条件だけを書くのが適しています。
2. 局所ルールは近いディレクトリに寄せること。OpenAI も Anthropic も、作業ディレクトリに近い指示を後勝ちで読む構造です。
3. 手続きは skill / hook / automation に寄せること。Anthropic は固定タイミングで必ず実行したいものは hooks に置くよう勧め、AWS と arc42 は運用手順は可能な限り自動化すべきとしています。
4. ファイル名と適用範囲を明示することです。Claude rules の paths はこのための仕組みです。

推奨ディレクトリ構造案

以下の三案は、現在の docs/_internal/ 相当の混在コンテンツを整理するための具体案です。結論だけ先に言うと、今すぐ採るべき土台は「案A」で、AIプロンプト資産だけは「案C」のやり方を先行導入するのが最も現実的です。 これは、移行コストを抑えつつ、将来の agent-first な文書運用へ滑らかに移れるためです。

案A: 内部ハンドブック型

docs/
    arch/
    dev/
    spec/
    _internal/
        index.md
        operations/
            runbooks/
            setup/
            maintenance/
            qa/
        workflows/
        research/
            index.md
            questions/
            prompts/
            findings/
            archive/
        agents/
            guides/
            templates/
            reviews/
        project/
            tracking/
            adr-support/
        biz/

• 採用の根拠: 現在の docs/_internal/ をそのまま「内部向け境界」として活かしつつ、catch-all をやめて役割別に浅く分け直すことにあります。隠し/除外ディレクトリという考え方自体は Docusaurus・MkDocs・Jekyll などで広く見られますし、GitLab のように「公開対象と運用対象を分類しながら同じ知識体系の中で扱う」考え方とも相性がよいです。
• 移行コスト: 低。既存ファイルの多くはディレクトリの付け替えで済み、docs/arch / docs/dev / docs/spec の arc42 再編と正面衝突しません。追加で必要なのは、index.md と最小 frontmatter を足し、_internal をビルドや公開導線から明示的に除外することです。なお、prefix だけに依存するのではなく、除外設定を明示する方が安全です。
• AIエージェント適性: 高。理由は、エージェントにとって重要なのは「公開/非公開」よりも「安定した経路」であり、operations / workflows / research / agents / project / biz のような固定された上位バケットは、ルートの AGENTS.md / CLAUDE.md から参照しやすいからです。ただし、この案だけでは prompt の実行資産がまだ docs/ 側に残るため、その部分は将来的に案Cに寄せる余地が残ります。

案B: docs/ 統合分類型

docs/
    arch/
    dev/
    spec/
    operations/
        runbooks/
        setup/
        maintenance/
    research/
        rq/
        prompts/
        findings/
        archive/
    agents/
        lifecycle/
        templates/
        reviews/
    handbook/
        workflows/
        workspace/
        tracking/
    biz/

• 採用の根拠: _internal という可視的な境界をやめ、すべてを docs/ 配下の第一級カテゴリーに昇格し、frontmatter で visibility: internal を付ける方式です。GitHub Docs や Microsoft Learn に近い思想で、文書タイプは path と metadata の両方で判定します。Diátaxis 的にも、how-to / reference / explanation の軸と、internal/public の可視性軸を直交させやすい構造です。
• 移行コスト: 中。ディレクトリ移動に加えて、全ページに近い範囲で frontmatter の付与・見直しが必要になり、公開ビルドを持つ場合は visibility を解釈する仕組みも要ります。MkDocs Material の meta plugin のようにフォルダ単位メタデータを使えると、繰り返しはかなり減らせます。
• AIエージェント適性: 中〜高。frontmatter が整えば機械分類はしやすい一方で、エージェントはサイトビルド済みのナビゲーションよりも raw file path を直接読むことが多いため、path 名そのものの意味が少し薄くなります。visibility と type を読める環境では強いですが、単純な grep / Read ベースの agent には、案Aや案Cほど即効性はありません。

案C: docs と agent assets の分離ハイブリッド型

docs/
    arch/
    dev/
    spec/
    _internal/
        operations/
            runbooks/
            setup/
            maintenance/
        research/
            questions/
            findings/
            archive/
        agents/
            lifecycle/
            reviews/
            governance/
        handbook/
            workflows/
            project/
        biz/

AGENTS.md
CLAUDE.md

.claude/
    rules/
        docs-authoring.md
        decision-pipeline.md
        research.md
    skills/
        rq-research/
            SKILL.md
            references/
        spec-drafting/
            SKILL.md
            assets/

.agents/
    skills/
        repo-overview/
        review-checklist/

• 採用の根拠: 人間向け文書と、エージェントが直接実行・読込する資産を分けることです。Anthropic は CLAUDE.md・.claude/rules/・skills を、OpenAI は AGENTS.md・.agents/skills を正式サポートしており、どちらも「ルートの短い指示」から「必要時だけ読む詳細手順」へ情報を分割する設計です。これは、あなたのプロジェクトのように AI エージェントが毎日 docs/ を読むケースと非常に相性がよいです。
• 移行コスト: 中〜高。文書の棚卸しに加え、「これは人間向け説明書か」「これは agent runtime asset か」を判定する作業が必要になります。ただし、Anthropic は CLAUDE.md から @AGENTS.md や @docs/... を import でき、OpenAI は nested AGENTS.md と .agents/skills を併用できるため、段階的移行は可能です。最初から完全分離を目指さなくても構いません。
• AIエージェント適性: 最も高い。理由は、skills が on-demand にロードされ、ルート文書は短く保て、パス別ルールでコンテキスト汚染を減らせるからです。Anthropic は procedure 化した文書は skill 化を勧め、OpenAI は progressive disclosure を前提に skill を設計しています。日常的に agent が repo を歩く前提なら、この案が最も自然です。

arc42 との統合判断

arc42 の公式テンプレートを見ると、運用に関する内容は単独の「チーム運用マニュアル置き場」ではなく、Runtime View、Deployment View、Crosscutting Concepts、Architectural Decisions に分散して表現されます。 特に Runtime View は起動・停止・エラーを含む運用シナリオ、Deployment View は複数環境や本番利用に必要な要素、Tip 7-9 は「運用に必要な実務を説明し、可能なら自動化しろ」という立場を明示しています。つまり、arc42 でいう operations は「システムを動かすための情報」であって、「チームのあらゆる内部文書」を意味しません。

そのため、本プロジェクトでは「arc42 の operations/ へ全面統合」ではなく、「真の運用文書だけ統合し、その他は独立 _internal で維持」が適切です。 具体的には、hooks_setup.md、migration_guide.md、ui_verification.md、data_maintenance.md、failure_patterns.md のような、システムの起動・保守・検証・障害対応に直接効くものは operations 側へ寄せられます。一方、git_workflow.md、customer_discovery_workflow.md、research_prompts/、adr_reviews/、biz/ は、arc42 の運用セクションではなく、内部ハンドブック・研究・ガバナンス・ビジネスの領域です。これは AWS が playbook は調査、runbook は対処として分け、playbook から runbook へリンクさせる設計を勧めていることとも整合します。意思決定と運用文書は強くリンクすべきだが、同じ種類の文書として潰さない方がよいということです。

「内部チーム向け運用ガイド」と「外部公開ドキュメント」を同一リポジトリで共存させる点については、_internal/ プレフィックスは有効な"シグナル"だが、アクセス制御の代替ではない、というのが実務上の答えです。Docusaurus / MkDocs / Jekyll はそれぞれ _ や . の扱いが異なるため、prefix だけに頼ると将来のツール変更に弱いです。GitLab は、公開コードと制限付き運用プロジェクトを分類しつつ、必要なら mirror を公開側にも置くという運用をしています。したがって、同一 repo 共存を続けるなら、パス規約 ＋ frontmatter visibility ＋ ビルド除外設定 ＋ リポジトリ権限設計の四層で考えるべきです。

将来、Jr. や業務委託者向けアクセス制御を本格的に考えるなら、最初に分離候補として検討すべきは biz/ です。 GitLab の canonical location の考え方でも、アクセスは project purpose と data classification に紐づけるべきとされます。ビジネス資料は、システム運用ナレッジや agent ガイドよりも機密性要件が独立しやすいため、同じ repo に残すメリットより、将来の権限設計を簡単にするメリットの方が大きくなりがちです。

bizlp プロジェクト向け推奨事項

1. ADR の結論としては、docs/_internal/ を廃止するのではなく「内部ハンドブック」として再定義してください。 そのうえで operations / workflows / research / agents / project / biz / archive のような上位バケットへ分割し、catch-all をやめるのが最も低コストで効果が高いです。隠し/除外ディレクトリの慣行自体は成立しますが、prefix だけに依存せずビルド除外も明示してください。

2. operations に昇格させるのは「システムを動かすための文書」だけに限定してください。 arc42 と AWS の考え方に合わせると、runbooks、maintenance、verification、migration、incident response は operations 向きですが、研究質問、ワークフロー一般、ADR レビュー、プロンプト設計メモ、ビジネス資料まで入れるとスコープが崩れます。

3. AI エージェントが直接使う prompt / checklist / workflow は、docs/ ではなく .claude/ / .agents/ へ移してください。 具体的には、repo ルートに短い AGENTS.md / CLAUDE.md を置き、繰り返し使う手順は skills、局所ルールは .claude/rules に分けるのが公式設計に合います。docs/_internal/agents/ には利用方針・レビュー・ライフサイクル説明を残す、という二層化が最も実務的です。

4. RQ 群は research/ の正式ストリームにし、open / active / synthesized / archived の状態を持たせてください。 受理・却下・実装後アーカイブを区別する RFC / PEP / vblang の運用が、探索的文書の整理に最も近い先例です。削除ではなく、固定 ID を持つ履歴として残す方が、将来の ADR 起草や再調査で圧倒的に強いです。

5. "必ず守るべき手順" は文書だけにとどめず、hook / CI / automation へ寄せてください。 Anthropic は固定タイミングで必ず効かせたい指示は hooks を使うべきだと明言し、AWS と arc42 も runbook / setup の自動化を推奨しています。つまり、ドキュメント構造の改善と同時に、「守らせたいルールは実行系へ移す」ことが、最終的には最も少ないドキュメント負債を生みます。

引用文献

1. Diátaxis - https://diataxis.fr/
2. arc42 Template Overview - https://arc42.org/overview
3. AWS Well-Architected - Operational Excellence: OpsReady to Support Use Runbooks
4. Docusaurus documentation - https://docusaurus.io/docs/next/create-doc
5. GitLab Handbook - https://handbook.gitlab.com/handbook/
6. GitHub Docs Contributing - Style Guide and Content Model
7. Rust RFCs - https://rust-lang.github.io/rfcs/
8. OpenAI Codex - AGENTS.md Guide - https://developers.openai.com/codex/guides/agents-md
9. (same)
10. (same as 4)
11. GitHub Docs - Writing for GitHub Docs: Using YAML Frontmatter
12. (same)
13. (same)
14. (same as 6)
15. Python PEPs - https://peps.python.org/
16. Vue RFCs - https://github.com/vuejs/rfcs/blob/master/README.md
17. (same as 8)
18. OpenAI Codex Skills - https://developers.openai.com/codex/skills
19. Anthropic Claude Code Slash Commands - https://docs.anthropic.com/en/docs/claude-code/slash-commands
20. Anthropic Claude Code Memory - https://docs.anthropic.com/en/docs/claude-code/memory
21. (same)
22. OpenAI Codex Learn Best Practices - https://developers.openai.com/codex/learn/best-practices
23. (same)
24. Docusaurus (same as 4)
25. MkDocs - https://www.mkdocs.org/about/release-notes/
26. (same as 22)
27. GitHub Docs Contributing (same as 6)
28. MkDocs Material - https://squidfunk.github.io/mkdocs-material/plugins/meta/
29. (same)
30. Anthropic Claude Code Memory (same as 20)
31. (same)
32. (same as 22)
33. arc42 (same as 2)
34. (same as 3)
35. Docusaurus (same as 4)
36. GitLab Handbook Engineering - https://handbook.gitlab.com/handbook/engineering/infrastructure-platforms/projects/
37. (same as 4)
38. arc42 Runtime View Documentation - https://docs.arc42.org/section-6/
39. OpenAI Codex Learn Best Practices (same as 22)
40. Vue RFCs (same as 16)
41. Anthropic Claude Code Memory (same as 20)