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

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

TL;DR（結論先出し）

• bizlp の現状（ソロ＋まもなく Jr.1名、docs/_internal/ 30本超、AIエージェント常用、GAS＋監査要件）に対しては、arc42 への完全統合ではなく「docs/_internal/ を維持しつつ Diátaxis 4分類ベースのサブディレクトリに再編成 ＋ YAML frontmatter による機械可読メタデータ ＋ AGENTS.md/CLAUDE.md からのナビゲーション」という折衷案を強く推奨する。理由は、arc42 が「対外的に説明可能なアーキテクチャ文書」を目的とし、ワークフロー・調査記録・プロンプトテンプレートのような「チーム内側のプロセス記録」とは目的・更新頻度・読者層が異なるため。

• 業界標準は「Diátaxis（4分類）」「arc42（アーキ12章）」「ADR（決定記録）」「runbooks/playbooks（運用手順）」がそれぞれ独立した責務として確立しており、これらは併存させるのが現代のベストプラクティス。AGENTS.md（OpenAI が 2025年8月にリリースし、2025年12月9日に Linux Foundation 配下の Agentic AI Foundation に移管。Linux Foundation 公式プレスリリースによれば「adopted by more than 60,000 open source projects and agent frameworks including Amp, Codex, Cursor, Devin, Factory, Gemini CLI, GitHub Copilot, Jules and VS Code among others」）の登場で、AIエージェントへのナビゲーションも標準化されつつある。

• 小規模チーム（〜3名）では「フラットに始め、痛みが出てから階層化」が鉄則。ファイル数が 30 を超えた bizlp は構造化投資の ROI ラインを既に超えており、いま投資する価値はあるが、Big Framework Trap を避けるため「サブディレクトリは最初は4〜5個まで、frontmatter で分類を補強」に留めるべき。

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

命名規則・frontmatter 設計の業界標準

YAML frontmatter（Jekyll/Hugo/MkDocs 共通）:

---
title: ...
type: tutorial|how-to|reference|explanation|adr|runbook|prompt|research
status: draft|active|archived|superseded
tags: []
---

が最大公約数。GitHub Docs では versions: を必須化し src/frame/lib/frontmatter.ts で schema 検証している。

• frontmatter は「LLM にとっての型シグネチャ」として機能する（understandingdata.com の "Frontmatter as Document Schema"）。AIエージェントは frontmatter を読んで関連ドキュメントだけをロードする「Progressive Disclosure」が可能になる。Claude Code の SKILL.md もこのパターンで、name:, description: 等の frontmatter から関連スキルだけを動的にロードする（Anthropic 公式仕様）。

• ファイル名規則: ADR は NNNN-kebab-case-title.md（npryce/adr-tools の事実上の標準、デフォルトディレクトリは doc/adr）、RQ 系は RQ-NNN-title.md、runbook は動詞ベース（restart-api-service.md）。

調査記録（RQ等）のアーカイブ戦略の業界標準

• active/archive 分離: _archive/ サブディレクトリへ移動する方式が最も一般的。
• 四半期レビュー: GitLab Handbook（オンボーディング時に必ず1つ Handbook を改善する慣習）、メルカリ Continuous Disclosure。多数の社内ハンドブックが採用。
• ステータス frontmatter: status: superseded で論理的アーカイブ（物理移動不要）。IETF RFC が古くから採用（Obsoletes: / Updates: ヘッダ）。
• immutable + supersede パターン: Microsoft Azure Well-Architected Framework が ADR に対して明示的に推奨：「Don't go back and edit accepted records. If a decision changes, write a new record that supersedes the original and link the two together. This approach preserves the history of your thinking and makes it clear when and why the direction shifted.」

2. Q2: AIエージェント向けドキュメントの特殊性

2-1. プロンプトディレクトリの配置：prompts/ vs docs/prompts/

docs/ の外（プロジェクトルート直下の prompts/）に置くパターン：

• 採用例: abilzerian/LLM-Prompt-Library（Jinja2 テンプレートを prompts/ と templates/ に分離）、LangChain Hub（コード側で hub.pull("name:hash") で参照）
• 根拠: プロンプトは「実行時に読み込まれるコード資産」であり、ドキュメントではない。LangSmith Cookbook の公式ノートブックは「For stable production deployments, specify a prompt's commit hash instead of defaulting to the 'latest'. This is done by appending the 'version' tag to the prompt ID.」と明示。これは GAS V8 ＋ LangGraph TS on Cloudflare Workers の bizlp スタックにも適合する。
• デメリット: 人間が読むためのテンプレートと混在しやすい。

docs/ 内（docs/_internal/agents/ 等）に置くパターン：

• 採用例: AI 教材リポジトリ、エージェント向け explainer、agent_docs パターン（HumanLayer 推奨：「Use a docs/ or agent_docs/ directory for supplementary context that the AI can pull in when needed」）
• 根拠: 「Claude/Cursor が読む参照資料であり、コードではない」場合に適切。
• デメリット: ビルド時にコードから参照しづらい。

推奨: bizlp では「実行時に LangGraph が読み込むプロンプト = src/prompts/」「人間/エージェントが参考にするテンプレート・ガイド = docs/_internal/agents/prompts/」を分離。前者はコードと同等のテスト・バージョニング対象、後者は frontmatter 付きドキュメント。

2-2. AIエージェント向けドキュメント構造の設計原則

Anthropic 公式（code.claude.com/docs/en/best-practices）の指針：

"CLAUDE.md is a special file that Claude reads at the start of every conversation. Include Bash commands, code style, and workflow rules. This gives Claude persistent context it can't infer from code alone." "There's no required format for CLAUDE.md files, but keep it short and human-readable." "Keep it concise. For each line, ask: 'Would removing this cause Claude to make mistakes?' If not, cut it. Bloated CLAUDE.md files cause Claude to ignore your actual instructions!" "The over-specified CLAUDE.md. If your CLAUDE.md is too long, Claude ignores half of it because important rules get lost in the noise. Fix: Ruthlessly prune."

Anthropic 公式が明示する「✅ Include」項目：Bash コマンド（Claude が推測できないもの）、デフォルトと異なるコードスタイル規則、テスト指示、ブランチ命名・PR 規約、プロジェクト固有のアーキテクチャ決定、開発環境の癖、よくある gotcha。「❌ Exclude」項目：コードを読めば分かること、標準的な言語規約、頻繁に変わる情報、ファイルごとの詳細説明、「クリーンなコードを書け」のような自明な指示。

AGENTS.md 仕様（Linux Foundation 配下 Agentic AI Foundation 管理）：

"AGENTS.md is a simple, open format for guiding coding agents, used by over 60k open-source projects. Think of AGENTS.md as a README for agents: a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project." "Are there required fields? No. AGENTS.md is just standard Markdown."

モノレポ規約：「最も近い AGENTS.md が優先（agents.md 公式サイト：『at time of writing the main OpenAI repo has 88 AGENTS.md files』）」。リリース・移管経緯：OpenAI が 2025年8月にリリースし、Linux Foundation の 2025年12月9日付プレスリリースで Agentic AI Foundation 配下に移管された。

3層アーキテクチャパターン（HumanLayer / groff.dev / DeployHQ ガイドが独立に推奨）：

1. Tier 1 - ルート CLAUDE.md / AGENTS.md（〜60行）: プロジェクト一地図、必須コマンド、最重要規約のみ。
2. Tier 2 - docs/_internal/agents/ や .claude/skills/: タスク別ガイド（building、testing、deployment）。エージェントが必要時のみ読む。
3. Tier 3 - docs/_internal/research/、docs/_internal/runbooks/ などの参照資料: agent が指示で pull する。

HumanLayer Blog "Writing a good CLAUDE.md" の検証データ：

"general consensus is that < 300 lines is best, and shorter is even better. At HumanLayer, our root CLAUDE.md file is less than sixty lines." "Frontier thinking LLMs can follow ~ 150-200 instructions with reasonable consistency. Smaller models can attend to fewer instructions than larger models, and non-thinking models can attend to fewer instructions than thinking models." "As instruction count increases, instruction-following quality decreases uniformly."

つまり「指示数を増やすと、特定の指示だけが無視されるのではなく、全体の遵守率が一律に下がる」。

2-3. プロンプトのバージョン管理・ライフサイクル（PromptOps）

実証済みの慣例：

• コミットハッシュ参照: LangSmith/LangChain Hub の正式パターン。hub.pull("user/prompt:3b929440") のようにバージョン指定。production では latest ではなく hash を固定参照。
• 環境タグ: LangSmith は staging / production を予約タグとして提供。promotion フロー経由でのみ移動可（freeform tag picker では設定不可）。
• CI 統合: Braintrust の GitHub Action は「プロンプト変更があれば eval を自動実行、ベースライン比較、PR にコメント、閾値割れで merge ブロック」。Braintrust 自社レポートでは「30% reduction in prompt-related production incidents」。
• PromptOps プラットフォーム: LangSmith、Braintrust、Humanloop、PromptLayer、Maxim AI、Lilypad（Mirascope）、W&B Prompts、PromptHub。bizlp はソロ＋Jr.1名なので、まずは Git ＋ frontmatter（prompt_version: 1.2, model: gpt-4o-mini, last_eval_score: 0.87）で十分。LangSmith 公式価格ページによれば Developer プランは「1 free seat with access to LangSmith (5k base traces/month included)」で、評価ツールが必要になった段階で無料枠から始められる（Plus プランは $39/月で 10k traces）。

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

案A: 「Diátaxisを_internal/内に持ち込むハイブリッド」（最推奨）

docs/
├── arc42/                          # ADR-0039 で確立済み、対外/長期説明用
│   ├── 01-introduction-and-goals.md
│   ├── ...
│   ├── 09-architecture-decisions/
│   │   ├── 0001-...md             # ADR本体（npryce/adr-tools 互換）
│   │   ├── 0039-arc42-feature-folder.md
│   │   └── 0040-internal-docs-organization.md  # ← RQ-045の成果物
│   └── 12-glossary.md
│
├── _internal/                      # チーム内側、運用・調査・AI向け
│   ├── README.md                   # _internal/ の地図（CLAUDE.md からリンク）
│   ├── how-to/                     # 手順書（Diátaxis: how-to guides）
│   │   ├── setup-clasp.md
│   │   ├── deploy-cloudflare-worker.md
│   │   └── decision-pipeline.md
│   ├── runbooks/                   # 障害対応・定型運用（SRE標準）
│   │   ├── gas-quota-exceeded.md
│   │   ├── itgc-audit-export.md
│   │   └── failure-patterns.md
│   ├── research/                   # 探索・RQ系（一時的）
│   │   ├── active/
│   │   │   └── RQ-045-internal-docs.md
│   │   ├── _archive/              # 完了/superseded
│   │   │   ├── RQ-001-...md
│   │   │   └── RQ-044-...md
│   │   └── INDEX.md
│   ├── agents/                    # AIエージェント向け参考資料
│   │   ├── prompts/               # 人間が読むテンプレートの説明
│   │   ├── workflows/             # Claude/Cursor 用ワークフロー
│   │   └── skills/                # SKILL.md 群
│   ├── business/                  # ビジネス資料（提案書、要件メモ等）
│   └── tracking/                  # 進捗・KPI・週報
│
└── public/                        # 外部向け（将来クライアント・ユーザー閲覧）
    ├── tutorials/
    ├── how-to/
    ├── reference/
    └── explanation/

# プロジェクトルート
AGENTS.md                          # Tier 1: 60行以下、エージェントへの地図
CLAUDE.md → AGENTS.md             # symlink（HumanLayer等が推奨する移行パス）
src/prompts/                       # コードから実行時に読まれるプロンプト
.claude/skills/                    # Anthropic公式: 動的ロードされるスキル

• 採用根拠: arc42 は「読者：将来の自分・新規参画者・監査人」のための長期・低更新頻度コンテンツ。_internal/ は「読者：いま動いている自分・Jr.・AIエージェント」の短期・高更新頻度コンテンツ。両者を混ぜると arc42 の章番号構造が頻繁な追加で崩れる。Diátaxis の4分類（tutorials/how-to/reference/explanation）を _internal/ のサブディレクトリとして借用することで「どこに書くか」の意思決定コストを下げる。
• 移行コスト: 中（30本のリネーム・frontmatter 追加・INDEX 生成。半日〜1日）。
• AIエージェント適性: ◎。AGENTS.md からの3層ナビゲーション、frontmatter で type/status/audience を明示。

案B: 「arc42 完全統合・_internal/ 廃止」

docs/
├── 01-introduction-and-goals.md
├── ...
├── 08-concepts.md
├── 09-architecture-decisions/
│   └── 0001-...md ... 0040-...md
├── 10-quality-requirements.md
├── 11-risks-and-technical-debt.md
└── 12-glossary.md
└── operations/                    # arc42 拡張（bizlp では itgc/ 配下）
    ├── itgc/
    │   ├── runbooks/
    │   ├── audit-trail/
    │   └── failure-patterns.md
    ├── workflows/
    ├── research-notes/
    │   └── RQ-NNN-...md
    └── agent-instructions/

• 採用根拠: arc42 一本に統一して「ドキュメントは1つの構造に従う」を徹底。LinkedIn 記事 "Effective architecture documentation with arc42 and C4"（torsten mosis）等は arc42 ＋ C4 で「すべての文書を arc42 章へマッピング」を推奨。
• 移行コスト: 高（30本それぞれの arc42 章への割り当て判断が必要。Jr. 参加前にやり切る必要がある）。
• AIエージェント適性: ○。章番号でルーティングできるが、ワークフロー・プロンプト・ビジネス資料を arc42 の12章のどれに入れるか恣意的になる。
• 問題点: arc42 founders は arc42.org/documentation 公式ページで「the manageable effort it takes to create and maintain arc42-based architecture documentation. We call it 'painless documentation', using the arc42 template does not require additional effort: You only describe things that your stakeholders really have to know about your architecture」と明言しており、ワークフロー・調査ノート・プロンプトは想定外。operations/ 肥大化のリスクが高い。

案C: 「フラット + frontmatter 主導」

docs/
├── adr/                           # ADRのみ独立
├── arc42/                         # arc42 章のみ独立
├── _internal/                     # 全部ここに、サブディレクトリなし
│   ├── 2026-04-deploy-runbook.md  # 日付プレフィックス
│   ├── 2026-05-RQ-045-docs-org.md
│   ├── failure-patterns.md
│   ├── workflow-decision-pipeline.md
│   └── ... (30+本)
└── AGENTS.md

各ファイルの frontmatter：

---
title: ...
type: runbook|research|workflow|prompt|business|tracking
status: active|archived|superseded
audience: [solo, jr, agent, auditor]
related:
  - ADR-0039
  - RQ-044
last_review: 2026-05-15
---

• 採用根拠: 「Premature structurization is the root of all evil」。サブディレクトリは grep/RAG/AIエージェントには無関係。frontmatter があれば検索・ナビゲーションは frontmatter-as-schema で十分。Hugo/Jekyll/MkDocs の taxonomies 機能で自動分類ページが生成可能。
• 移行コスト: 低（frontmatter 追加のみ）。
• AIエージェント適性: ◎。frontmatter は Progressive Disclosure に直接マッピングできる。
• 問題点: Jr. エンジニアが参加した直後、サブディレクトリのナビゲーション支援なしで30本超を一気に把握するのは難しい。「ファイル名で目的が分からない」フラストレーションが出やすい。frontmatter を読むツール（タクソノミーページ生成）の整備が必要で、これ自体が小投資。

4. Q3 への明確な結論：arc42 統合 vs _internal/ 維持

結論：_internal/ を維持する（案A）

理由（bizlp 固有のコンテキストに即して）：

1. 目的・読者の不一致: arc42 は「アーキテクチャをステークホルダーに説明する」ためのテンプレート。arc42 founders 自身が arc42.org で「You only describe things that your stakeholders really have to know about your architecture」と述べている通り、スコープを意図的に絞っている。bizlp の _internal/ は「ワークフロー、調査記録、ツール設定、ビジネス資料、AIプロンプト」を含み、これは arc42 のスコープ外。

2. 更新頻度の不一致: arc42 の章（特に5-7章）は「設計が固まると数ヶ月変わらない」性質。_internal/runbooks/ や _internal/research/ は週次〜日次で追加・更新される。同じ階層に混ぜると arc42 の安定感が損なわれ、監査時に「どれが正史か」が曖昧になる（bizlp は法人会計自動化で ITGC 統制対象）。

3. 監査・統制要件: 法人会計自動化の ITGC 要件下では、「決定の最終版（ADR）」「監査トレイル（runbook 実行記録）」「探索段階の試行錯誤（RQ）」を物理的に分離しておく方が、監査人への説明コストが下がる。arc42 統合案だと「探索ノートが arc42 章として混入」のリスクがある。

4. AIエージェント運用との親和性: HumanLayer/groff.dev/Anthropic 公式の3層パターン（CLAUDE.md →docs/agent-guides/ →参照資料）は「短く頻繁にロードされるファイル」と「必要時のみロードされる詳細」を明確に分離することを推奨。_internal/ をエージェント向けエントリポイントの中継地点にする方が、arc42 の章群にエージェント向け指示を散在させるより効率的。

5. Jr. オンボーディングの最適化: 新規参画者には「外側 → 内側」の2層モデル（公開可能な arc42 / 内側の _internal/）が直感的。一階層下にメンタルモデルを揃えられる。

反対意見（arc42 統合派）への返答：

• 「ドキュメント構造は1つに統一すべき」→ 業界の現代ベストプラクティスは併存である。Diátaxis 自身が「arc42 や C4 と独立に存在し、組み合わせて使える」設計。Sequin（自社ブログで「We loaded up a Claude project with all the pages in the Diátaxis website repo」と明言）、Canonical、Cloudflare ともに複数フレームワークの併用を実践している。
• 「_internal/ プレフィックスは Hugo/Jekyll の慣習で公開ビルドから除外されるが、bizlp は静的サイト未構築」→ そのとおりで、現時点では命名上の「内向きシグナル」に過ぎない。ただし将来 MkDocs/Astro 等で公開する場合、_ プレフィックスが除外フィルタとして機能する利点は大きい。
• 「ファイル数が30本程度なら統合してもよいのでは」→ 6ヶ月後の予測値で判断すべき。Jr. 参加後、ワークフロー・RQ・runbook は合計100本超に到達する可能性が高い。

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

5-1. 構造化投資の ROI ライン

• 経験則: 「ファイル数 20-30 / 開発者数 2 / 在籍期間6ヶ月超」が一つの転換点。GitLab Handbook は 2015年に最初のコミット、2019年4月時点で「about 605,000 words ... spread across 550 unique web pages, with the average page containing around 1,100 words」。GitLab は「オンボーディング時に必ず1箇所改善する」をルール化して漸進的に成長させた（Handbook 自体に明文化）。
• メルカリ Confluence → Notion 移行プロジェクト（2025-2026）の教訓（メルカリエンジニアリングブログ）：「完璧なインポートは幻想。移行後の手作業を前提とせよ」「金融事業（メルペイ・メルコイン）はコンプライアンス要件で別ルート化」「最終的に Confluence は閉架図書扱い」。移行コストは常に過小評価されるので、構造化は「いま小さく入れて、痛みベースで拡張」が安全。
• bizlp の現状値: ファイル 30 本、開発者 1→2、すでに ROI ライン到達済み。

5-2. 将来拡張可能なフラット構造の具体例

docs/_internal/
├── README.md          # 地図
├── how-to/            # 動詞ベースのファイル名
├── runbooks/
├── research/
└── agents/

# 各ファイル必須 frontmatter:
---
type: how-to
status: active
audience: [solo, jr]
---

最初は4-5サブディレクトリのみ。サブディレクトリは「実例が3本以上たまってから新設」のルール（YAGNI の応用）。Hugo の taxonomy や grep で frontmatter 検索する習慣を導入すれば、サブディレクトリ未満の粒度はメタデータで吸収できる。

5-3. Big Framework Trap を避ける判断基準

1. 「ドキュメント構造を変えるのに30分以上議論するな」（Anthropic 公式の "ruthlessly prune" 原則の応用）。
2. 「同じ場所に5本以上たまるまでサブディレクトリを作らない」（Diátaxis の「empirical refactor」哲学：diataxis.fr の "There is a very simple workflow for Diátaxis ... Decide one thing you could do right now, however small, that would improve it. Do that thing. And then repeat."）。
3. 「frontmatter は3フィールドから始める」（type, status, last_review）。schema を最初に作りこまない（GitHub Docs のような厳格 schema は規模 20 人超で初めて意味を持つ）。
4. 「AIエージェントへの指示は AGENTS.md/CLAUDE.md に最小限のみ」（Anthropic 公式："each line, ask: 'Would removing this cause Claude to make mistakes?'"）。
5. /init で自動生成されたファイルをそのまま採用しない（DeployHQ ガイド："Auto-generated config files tend to be generic and bloated. Write yours by hand — every line should earn its place by solving a real problem you've encountered"）。

6. ADR 起草に向けた推奨事項まとめ（bizlp プロジェクト向け）

推奨1: docs/_internal/ を維持し、Diátaxis 由来の4-5サブディレクトリ（how-to/, runbooks/, research/, agents/, 任意で business/）を新設する

• 根拠: (a) arc42 founders 自身が arc42 のスコープを意図的に絞っており、ワークフロー・調査記録・プロンプトは対象外（公式 arc42.org/documentation の "painless documentation" 説明）。(b) Diátaxis（Canonical/Cloudflare 採用）は「目的別に文書を分離する」ことで認知負荷を下げる効果が実証済み（diataxis.fr 公式の "As a lens, Diátaxis is unforgiving. The more thoroughly the structure is adopted, the more mercilessly it exposes gaps, missteps and conflations"）。(c) bizlp の ITGC 監査要件下では「正史 vs 探索ノート」の物理分離が説明コストを下げる。
• 反対意見への返答: 「サブディレクトリ過多」と批判される可能性 → 4-5個は OpenDevise の標準プロジェクト構造提案や Scoutflo SRE Playbooks の階層数（AWS Playbooks/01-Compute、02-Database...の8カテゴリ）とも整合し、過剰ではない。

推奨2: すべての _internal/*.md に最小限の YAML frontmatter（type, status, audience, last_review, related）を必須化する

• 根拠: (a) frontmatter は「LLM にとっての型シグネチャ」として機能し、AIエージェントの Progressive Disclosure を可能にする（understandingdata.com "Frontmatter as Document Schema": "The agent reads metadata to determine which documents are relevant, then loads full instructions only for the activated skill"）。(b) Hugo/Jekyll/MkDocs/Astro いずれでも互換。将来の静的サイト化に備えられる。(c) GitHub Docs は src/frame/lib/frontmatter.ts で schema 検証し、規模拡大時のリファクタコストを抑えている。
• 反対意見への返答: 「frontmatter は冗長」→ 3-5フィールドのみで、grep でも検索可能。Jr. 参加時のオンボーディング負担はテンプレートファイル1本で吸収できる。

推奨3: プロジェクトルートに AGENTS.md（〜60行）を置き、CLAUDE.md をsymlink にする。タスク別の詳細は docs/_internal/agents/ に分離する3層構造を採る

• 根拠: (a) AGENTS.md は OpenAI が 2025年8月にリリースし、2025年12月9日に Linux Foundation 配下 Agentic AI Foundation の管理する標準となった。Linux Foundation プレスリリースによれば Cursor、Codex、Aider、Windsurf、Devin、Jules、Factory、Gemini CLI、GitHub Copilot、VS Code、Amp など主要ツールが対応（60,000以上の OSS で採用）。Claude Code は CLAUDE.md ネイティブだがシンボリックリンクでフォールバック可能。(b) Anthropic 公式が「keep it short and human-readable」「ruthlessly prune」と明示。(c) HumanLayer の検証では「general consensus is that < 300 lines is best, and shorter is even better. At HumanLayer, our root CLAUDE.md file is less than sixty lines」と60行水準を提示し、「Frontier thinking LLMs can follow ~ 150-200 instructions with reasonable consistency」と数値化している。
• 反対意見への返答: 「AGENTS.md と CLAUDE.md を両方維持すべき」→ 60行レベルでは差別化する内容がほぼないため symlink で十分。Claude Code 固有の指示が生じた時点で CLAUDE.md を実ファイル化すればよい（HumanLayer / DeployHQ ガイドの一致した推奨）。

推奨4: プロンプトは「実行コード = src/prompts/」と「人間/エージェント向けテンプレート説明 = docs/_internal/agents/prompts/」を分離する。バージョン管理は Git のコミットハッシュで十分（PromptOps プラットフォーム導入は当面見送り）

• 根拠: (a) LangSmith Cookbook の公式パターン「production では hash 固定参照」("specify a prompt's commit hash instead of defaulting to the 'latest'") は Git の HEAD/タグで同等のことができる。(b) ソロ＋Jr.1名の規模で Braintrust/Humanloop/PromptLayer 等を導入するのは TCO に対して過剰投資。(c) frontmatter に model:, prompt_version:, last_eval_score: を入れれば必要十分な追跡が可能。
• 反対意見への返答: 「Eval が回らない」→ LangSmith 公式価格ページで Developer プランで「1 free seat with access to LangSmith (5k base traces/month included)」が無料で利用可能。langsmith クライアントを LangGraph TS から呼ぶだけで導入できる。本格的な PromptOps プラットフォームへの移行は「プロンプト本数が20を超えた時点」または「無料枠の 5k traces を消化し始めた時点」をトリガに再評価する。

推奨5: _internal/research/ には active/ と _archive/ を分離し、各RQには status frontmatter を必須にする。四半期レビューで status の見直しを行う

• 根拠: (a) IETF RFC が60年運用している Obsoletes: / Updates: パターンの応用（RFC 2026 で正式化）。(b) Microsoft Azure Well-Architected Framework は ADR について「Don't go back and edit accepted records. If a decision changes, write a new record that supersedes the original and link the two together」と明示。(c) メルカリ Confluence → Notion 移行ブログで「Confluence 内のドキュメントは閉架図書のように取り扱う形を目指している」と述べているように、アーカイブを捨てない方針が現代の主流。
• 反対意見への返答: 「アーカイブが肥大する」→ frontmatter status: archived で論理アーカイブ、grep/ripgrep で status: active のみ即座にフィルタ可能。Hugo タクソノミーや MkDocs プラグインで自動的に active のみ INDEX 表示できる。

7. Caveats（注意事項）

• AIツール市場の変動: AGENTS.md 仕様は OpenAI が 2025年8月にリリースし、2025年12月9日に Linux Foundation の Agentic AI Foundation に移管されたばかりで、対応ツールは現在も拡大中。Claude Code が AGENTS.md をネイティブ採用する可能性もあり、半年〜1年ごとに再評価すべき。
• LangGraph TS / Cloudflare Workers のプロンプト管理機能: 本調査ではフレームワーク固有のプロンプト管理パターンには深入りしていない。LangChain Hub の TS SDK が成熟していない場合、src/prompts/*.ts でテンプレート文字列をエクスポートする素朴な実装で十分な可能性が高い。
• Jr. オンボーディング負荷: 本推奨は「frontmatter を読み書きする習慣」を新人に課すため、最初の1〜2週間は学習コストがある。テンプレートと pre-commit で frontmatter 必須化を機械的に強制することで吸収すること。
• arc42 ＋ ADR 統合事例の小ささ: 本調査で arc42 と ADR の両方を明示的に組み合わせている OSS は bitsmuggler/arc42-c4-software-architecture-documentation-example（190★）、arner/arc42-template、juangcarmona/starwars-deathstar-arc42-documentation 等で、大規模プロダクション事例は限定的。これは「両方を組み合わせる価値はあるが、業界全体ではまだ少数派」という意味であり、bizlp が先進例になる可能性がある。
• Diátaxis 採用事例の偏り: Canonical（Ubuntu/Juju/Charmed Kubeflow）、Cloudflare、Sequin など Diátaxis 採用事例は「外部公開のユーザードキュメント」が中心で、_internal/ のような内向きコンテンツへの適用は本調査の見立てによる外挿である。「内向きにも有効」は理論的整合性から導かれた仮説であり、6ヶ月後にレビュー（ADR-0040 の Postmortem）すべき。
• 国内事例の限定: 日本国内事例として確認できたのはメルカリ（Confluence → Notion 移行、Engineering Ladder、Devin Enterprise 運用）、LayerX（LLM 活用、Claude Code Agent Skills 採用言及）が中心。CADDi の具体的なドキュメント組織化方針は公開情報が限定的。「日本企業の _internal/ 慣習」の網羅性は不十分。
• PromptOps ツールの市場成熟度: LangSmith/Braintrust/Humanloop/PromptLayer 等は 2024-2026 年に急速に進化しており、推奨4の「導入見送り」判断は 2026 年中盤時点の TCO 評価に基づく。プロンプトが業務クリティカルになった段階、または bizlp チームが5名超に成長した段階で再評価が必要。