1–50 人スケールの内部ドキュメントサイト構造ベストプラクティス — 3 モデル Deep Research 調査

調査日: 2026-05-27 調査者: [email protected] 目的: ADR-0079 (engineering/corporate 物理サイト分離) 一度目失敗の振り返り。1–3 人 → 50 人スケールで AI 生成主体・Cloudflare Pages ホスティングの内部ドキュメントをどう構造化すべきか、業界事例ベースで判断材料を集める 調査モデル: Claude Opus 4.7 (Managed Agents) / Gemini Deep Research (deep-research-preview-04-2026) / OpenAI o3-deep-research 個別結果: Claude / Gemini / OpenAI 関連 ADR: ADR-0079 (engineering/corporate サイト分離 — 初回失敗)

0. 調査の動機

bizlp は現在 1–3 人体制で 546 ページの内部ドキュメントを Cloudflare Pages で運用、週 ~15 ページのペースで増加中。AI 生成 (Claude Code / Gemini / OpenAI 経由のパイプライン) が主たる執筆手段。ADR-0079 で engineering / corporate (ITGC・戦略) を物理サイト分離する案を試みたが、ビルド・デプロイ複雑性により挫折。再挑戦の是非と、人数フェーズごとの正しい構造化を判断するため 3 モデルで Deep Research を実施した。

1. 調査設問

1. マルチオーディエンス・アーキテクチャ: 1 サイト + ACL / 複数物理サイト / ハイブリッド、10–50 人規模ではどれが定石か
2. ガバナンス・スケーリング: 人数フェーズ (1→5→10→20→50) ごとに何を導入すべきか・最初に何が壊れるか
3. AI 生成コンテンツの品質管理: 80%+ AI 執筆時の quality gate / staleness / 信頼維持の手法
4. Cloudflare Pages のマルチサイトデプロイパターン: Git 連携 ×N projects / GitHub Actions + wrangler / モノレポ path 分割の比較

2. 調査結果

2.1 Claude Opus 4.7 (Managed Agents) — 488s, $2.46

主要発見:

• 「Rule of 10」: 1–15 人は単一サイト + ACL が最適。10–20 人を超えると非公式運用が破綻し CODEOWNERS / controlled_document フラグ / staleness 検出が必須化
• Conway's Law は両刃: ADR-0079 が失敗したのは 1–3 人時点で「分離すべきチーム境界」が物理的に存在しなかったため。チーム境界より先にサイト境界を作ると複雑性だけが増す
• 日本の Ringisho / Nemawashi: 合意形成プロセスが「1 つの共有可能 URL」を流通単位とする文化と相性が良く、統合サイトの方が実は加点要因
• AI 生成への信頼は急落中: 2025 年に AI 生成コードへの信頼度 40% → 29%。30/60/90 日後に静かに壊れる
• 5 つの quality gate: (1) last_verified / owner / certified_for_ai 等の schema-enforced frontmatter, (2) GitHub Actions cron での staleness 自動検出, (3) AI-aware prose linting + CLAUDE.md style guide, (4) リスク比例の human review, (5) writer → critic → human 多段レビュー
• staleness 閾値: ADR は不変、architecture spec 90 日、research 180 日、ITGC policy 365 日、data definition 30 日
• llms.txt + Markdown content negotiation: AI agent 向けトークン消費を 90%+ 削減
• Diátaxis フレームワーク: ADR→Explanation、spec→Reference、procedure→How-to、onboarding→Tutorial にマッピング。混在は AI 生成の最大失敗パターン
• Cloudflare for Teams Free: ≤50 user は $0、自然な天井とちょうど一致
• Architecture: Pages + Access (Zero Trust) で path 別 policy (/docs/eng/* → 全社員、/docs/corp/* → corp チーム、/docs/itgc/* → MFA 必須)

roadmap (4 phase): Phase 1 (now) 単一サイト + 命名規約 + MADR + llms.txt → Phase 2 (5-15) CODEOWNERS + Vale + 2 階層 Access → Phase 3 (15-30) GitHub Actions + wrangler で 2 projects + 四半期 access review → Phase 4 (30-50) 必要なら 3 site + Documentation Steward ロール

2.2 Gemini Deep Research — 627s, $1.12

主要発見:

• モノリス推奨: <50 人では「単一サイト + 論理分離」が最適。物理分離は時期尚早で CI overhead + サイロを生む
• 3 パターン整理: (1) 単一モノリス + path-based Cloudflare Access, (2) 複数 repo 物理分離 (<50 人で運用摩擦深刻), (3) Federated hub (50 人未満では over-engineering)
• Cloudflare Pages SPA default の罠: デフォルトで全 path が index.html にフォールバックするため、Access で守ったはずの制限 path も内容を leak しうる。ルートに strict 404.html を配置して厳密 404 を返す設定が必須
• 3 Tier ガバナンス: Tier 1 (1-5) founder/CTO 集中 + 任意 peer review → Tier 2 (5-15) CODEOWNERS 強制 + branch protection + Git hook で last_modified 自動付与 → Tier 3 (15-50) DevEx/Technical Writer 専任 + ITGC は multi-tier review (engineering lead + compliance officer)
• J-SOX 文脈: 金商法の内部統制要件は SOX より広範。文書化された internal control の評価記録が監査対象
• AI 生成は「production software と同じ厳密さ」で扱う: 確信に満ちた hallucination の沈黙伝播が最大の運用リスク
• 必須 frontmatter schema: owner (CODEOWNERS にマップ), last_verified (ISO 8601, Git の last_modified とは別), certified_for_ai (将来の RAG が安全にインジェスト可能か)
• Spec-Driven Review Workflow: AI が last_verified を空のまま PR 提出 → CODEOWNERS が auto-tag → owner が Cloudflare Pages preview 環境で視覚確認 (raw diff では捉えにくい hallucinated URL や formatting error を検出)
• 自動 lifecycle: GitHub Actions actions/stale が daily で last_verified を scan、閾値超過で issue 自動作成、grace period 後に certified_for_ai: false に降格
• 3 デプロイパターン比較: 2 Pages projects (シンプルだが parallel build & cross-ref が full URL 化) / GitHub Actions + wrangler (柔軟だが 1-3 人には overkill) / 単一 + path routing (最小複雑性だが Access の path 制限が「存在自体」は隠せない)

2.3 OpenAI o3-deep-research — 1190s, $1.53

主要発見:

• 統一サイト推奨を実証データで補強: 知識フラグメント時に 46% の社員が情報を探せず、83% が既存ドキュメントを recreate (archbee.com 引用)
• ハイブリッドが定石: 10–50 人では「1 ポータル + audience 別 navigation + access control」が経験則
• 「10–20 人」が決定的 inflection point: この帯域で tribal knowledge が「成長を能動的に遅延させる」状態に転じる (allymatter.com 引用)
• 5 フェーズ roadmap (より細粒度):
  • 1–5: 書く習慣 + Markdown in Git + ADR + handbook
  • 5–10: document owner 割当・基本 review workflow・access tier (HR/board のみ)・onboarding "Start Here"
  • 10–20: 6 ヶ月毎 review cycle・テンプレ標準化・CODEOWNERS 自動化・Definition of Done に docs 組込・weekly 30min 「ドキュメントスプリント」
  • 20–50: 種別ごとの formal approval (ITGC は CTO/compliance sign-off)・検索投資・読了率トラッキング・専任 Documentation Champion / part-time tech writer
• 「信頼されないドキュメントは無いより悪い」: 数枚の outdated ページを見ただけでエンジニアは docs を見限る。findability / accuracy / ownership が最初に壊れる
• AI 生成は draft 扱い必須: human-in-the-loop で初期は厳格に・特定パイプライン (API doc 生成等) で信頼蓄積後に段階的自動化
• 「ownership 明示」が AI 生成の決定打: 「AI が書いた = 私の責任ではない」を防ぐため CODEOWNERS で各 AI 生成 doc に owner 紐付け必須
• AI を grounding data に bind: structured input (コードコメント / 設計図 / data definition) を起点にすれば hallucination 減
• 再生成の罠: schedule で再生成パイプラインを走らせる場合、「proposed update」モードで diff を出して human approval を経るべき (human edit の上書き防止)
• 透明性ノート: 各 doc に「AI 生成 2024-06-01 / human review 2024-06-02 by Jane Doe」を記録
• 1-3 人向け推奨: 単一 Pages project 継続 + Cloudflare Access の path policy 追加で当面解決。裏で「2 top-level directory に整理 + ビルドスクリプトの section nav 対応」を進めて将来分離を容易化

3. サマリー (3-vendor 統合結論)

3.1 3 者一致点

3.2 不一致・温度差

3.3 bizlp 向け結論

ADR-0079 は再挑戦せず、ADR-0079 の方針を「単一サイト + Access policy + frontmatter schema 強化」に書き換えるのが正解。 3 モデルが一致した上、ADR-0079 初回失敗の真因 (governance 不在で複雑性だけ増した) と矛盾しない。

Immediate (~30 日以内)

1. 物理分離は撤回: ADR-0079 を「単一サイト + 論理分離戦略への転換」として書き換え or supersede
2. Cloudflare Access の path policy 追加: /docs/_internal/* や /docs/itgc/* 等の機微パスに対し group ベースの ACL を設定 (現在は audience 切替ボタンのみで真の access control 不在)
3. frontmatter schema を確定: owner / last_verified (ISO 8601) / controlled_document / generator / confidence / human_reviewed を全 doc 必須化、CI で enforce
4. Cloudflare Pages SPA fallback 対策: ルートに strict 404.html 配置 (Gemini 指摘の leak リスク)
5. llms.txt + Markdown content negotiation: 546 page × 90% トークン削減で AI agent 経由のコスト下げる
6. MADR + Diátaxis taxonomy 採用: ADR template を MADR 標準に揃え、Diátaxis 4 mode で既存 doc を分類 (混在 doc が AI 生成精度を最も下げる)

Medium-term (3–6 ヶ月、5+ 人を視野)

1. CODEOWNERS + branch protection: 単独運用でも先にパターンを敷く (chief reviewer = 自分でも entry を置く)
2. GitHub Actions の staleness cron: last_verified を daily scan、閾値超過で issue 自動起票
3. Onboarding directory (01-first-day / 02-first-week / 03-first-month): Jr 採用準備マイルストーン (2026-04) と接続
4. Spec-Driven Review Workflow: AI が last_verified 空欄で PR → owner が Cloudflare Pages preview で視覚確認 → last_verified 埋めて merge

Longer-term (12+ ヶ月、10+ 人視野)

• 物理サイト分離を再評価 (恐らく 15–20 人到達まで不要)
• 分離するなら wrangler pages deploy matrix pattern (Pages native の Git ×N projects はスキップ)
• 50+ 人到達時に Cloudflare Access pay-as-you-go ($7/user/month) を予算化
• Documentation Steward ロール (専任 or rotating) を新設

Anti-patterns (今後避けるべき)

• 「将来の分離を避けるため今分離する」(ADR-0079 がまさにこれ)
• audience タグだけのクライアントサイドフィルタ (Access policy なしは leak)
• 全 doc を "internal" で一括ロック (tribal knowledge を促進)
• .pages.dev URL の流出 (custom domain + Access を常に front に立てる)
• Diátaxis mode の 1 page 内混在
• AI 生成パイプラインの schedule 再実行で human edit を上書き
• CODEOWNERS を置くだけで "Require review from Code Owners" を branch protection に紐付けない (実効ゼロ)
• 2600 行手書き _config.json 維持 (filesystem-driven sidebar generation への移行を中期計画に)

4. コスト

5. 参考リンク

3 モデルとも以下の業界 source を高頻度で引用:

• allymatter.com From 2 to 20 Employees: The Documentation Pivot Every Startup Misses — 10–20 人 inflection point の主要 source
• archbee.com Multi-Product Documentation Strategy — 46% / 83% の情報サイロ統計
• cavaro.io How to Organize Technical Documentation for Fast-Growing Teams — quality > volume の原則
• Cloudflare Zero Trust docs — path-based Access policy 設計
• GitLab Handbook — controlled_document パターン (Claude)
• Diátaxis (diataxis.fr) — 4-mode フレームワーク (Claude)
• Morningstar Investor Bias シリーズ (注: RQ-064 で利用、本 RQ では未参照)
• MADR (adr.github.io) — Modular ADR テンプレ

各モデルの個別出典は以下に保存:

• Claude 結果 (Anthropic Managed Agents)
• Gemini 結果 (Google Deep Research)
• OpenAI 結果 (o3-deep-research)