FND-002: 意図的なドキュメント作成: 標準、構造、i18n戦略

v0.7.0 から · 種類: ドキュメント · 改訂: 7

正規リファレンス · チーム承認済み · 改訂 7 元の RFC に関する議論: #5576

これを読む前にチームへの注意。

ドキュメントとは、コードが完成した後に書くものではありません。それ自体が独立したプロダクトの一面であり、プロジェクトと、それに貢献する人、利用する人、それを基盤に何かを構築する人すべてとの間のインターフェースです。ドキュメントのないコードベースは、新しく関わるすべての人に、あらゆることをゼロから再発見することを強います。ドキュメントの質が悪いコードベースは、しばしばもっと悪い結果を招きます。なぜなら、人々に誤った自信を与えてしまうからです。この RFC では、私たちがアーキテクチャに適用しているのと同じ意図性をもってドキュメントを扱うことを提案します。すなわち、まずビジョン、次に構造、そして内容です。

目次

1. ドキュメンテーションの哲学
2. 正直な評価：現在の状況
3. 分類フレームワーク: 1ページ上のEAアーティファクト
4. i18nの問題
5. リポジトリとWikiの分離
6. ADR 標準
7. AGENTS.md を AI 開発レイヤーとして
8. ターゲット構造
9. 置換ドキュメント契約
10. 採用すべき標準
11. フェーズ別ロードマップ

改訂履歴

Foundation の改訂ポリシー

Foundationのリビジョンメタデータは、承認済みベースラインに取り込まれたドラフトのリビジョンを保持し、承認後の規範的な決定の変遷を記録します。マージされた変更によってアーキテクチャ、必須プロセス、リリース契約、コントリビューターの行動、または権威あるソースの所有権が変わった場合は、表示されるリビジョンを進め、時系列の行を1行追加します。後続の撤回は、両方の状態が順番にプロジェクトを規定したため、別個のリビジョンとなります。承認の対象外となったIssueのみのドラフトは算入しません。

契約を変更しない移動、書式設定、句読点、見出しの正規化、リンクの修正、パスの更新については、リビジョンを更新しない。基盤ドキュメントが運用上の詳細を別の保守対象ソースに明示的に委任している場合、その詳細に限定された変更では基盤ドキュメントのリビジョンを更新しない。

表示される2つのリビジョン値と、ローカルのリビジョン履歴における最大の行は、同じ変更で一緒に更新する必要があります。修正に伴って追加された行では、その修正に割り当てられたリビジョン日付を維持します。後から履歴を補完する場合は、変更がmasterに入った日付を使用します。

1. ドキュメンテーションの哲学

ドキュメントの問題は、最初の文を書く前に尋ねるべき質問を省略したことに起因することがほとんどです。このドキュメントはどのような種類のもので、誰を対象としているのか？

この問いに対する答えがないと、ドキュメントはすべて「プロジェクトに関するもの」という曖昧なカテゴリのわずかに異なる形状のページの山として蓄積していきます。セットアップガイドはアーキテクチャの決定事項の隣に置かれ、ユーザー向けのハウツーは内部のコーディング基準の隣に並んでいます。READMEの30言語版が、単一のセキュリティポリシー文書とスペースを争っています。誰も何も見つからず、すべてが異なるペースで古くなり、ドキュメントに触れるすべてのPRが、どのページを更新する必要があるかについての交渉になります。

修正策は、さらにドキュメントを書くことではありません。修正策は、何も書き始める前に、作成するアーティファクトのタイプを決定することです。タイプは、フォーマット、対象者、場所、ライフサイクル、そしてそれを最新に保つ責任者を決定します。タイプが確立されれば、残りのことは自然と整います。

このRFCでは、すべてのZeroClawドキュメントの分類基準として、Svyatoslav Kotusev氏による EA Artifacts on a Page フレームワーク（https://eaonapage.com）を採用します。このフレームワークはエビデンスに基づき、意図的に規範的でなく、オープンソースインフラストラクチャプロジェクトが実際に必要とするドキュメントの種類に直接対応しています。

このチームが採用している広範な開発哲学から借用した核心原則：

コードと同様に、ドキュメントも Vision → Architecture → Design → Implementation へと上向きに追跡できるものでなければなりません。書く前に、アーティファクトのタイプとその対象読者を明確にできない場合は、まだ書く準備ができていません。

2. 正直な評価：現在の状況

2.1 i18nのフットプリント

現在の実装で最も直接的に測定可能な問題は、ローカライゼーションシステムです。

i18n システムは、すべてのドキュメント PR に対してコントリビューター税を課します。現在の docs-contract.md にはこの要件が含まれています：

ドキュメントのIA、ランタイム契約の参照、または共有ドキュメント内のユーザー向け表記に変更がある場合、同じPR内でサポートされているローカライズに対してi18nのフォローアップを行ってください。

つまり、セットアップガイドのタイプミスを修正するコントリビューターは、そのドキュメントの最大6つの言語版を更新する必要があります。そうしないと、PRはレビューに通りません。これは、このプロジェクトのコントリビューターの大部分を占める学生や初期キャリアのエンジニアにとって、大きな障壁となります。

2.2 構造の問題

現在の docs/ の階層構造は、3つの根本的に異なるドキュメントタイプを同じレベルで混在させています：

• コードに隣接するドキュメント（ADR、API仕様、セキュリティポリシー、コントリビューションプロセスなど）は、コードベースと連動してバージョン管理する必要があります。
• ユーザー向け運用ドキュメントは、コードリリースとは独立して更新されるべきです（セットアップガイド、トラブルシューティング、デプロイメントの手順書など）。
• コミュニティ文書：コミュニティが維持管理し、正式なレビュープロセスを必要としないもの（翻訳、FAQ、コミュニティガイド）

これら3つはすべて docs/ にあり、それらの間に構造的な区別はありません。その結果、手動でメンテナンスする必要がある SUMMARY.md を持つ平坦な構造になり、何か変更があるたびに誰かが更新する必要があります。

2.3 ADRギャップ

このRFCが書かれた時点で、プロジェクトには旧ドキュメントツリーに2つのArchitecture Decision Recordがありました。WASMプラグイン向けのADR-003と、ツール共有状態の所有権に関するADR-004です。ADR-004は特に優れたモデルで、構造がしっかりしており、コード参照があり、具体的でした。しかし、プロジェクトは同等かそれ以上に重要なアーキテクチャ上の決定を少なくとも5つか6つ行っていましたが、それらは一度も記録されていませんでした。

• RustをTypeScriptよりも選択する理由
• トレイト駆動の拡張性モデル
• WASM プラグインシステムの設計
• バックエンド非依存のメモリーストレージ契約と SQLite のデフォルト
• セキュリティモデル（ペアリングコード、自律レベル、サンドボックスレイヤー）

これらの記録がないと、新しいコントリビューターはコード考古学を通じて理由を再発見しなければなりません。コードベースを読み取るすべてのAIコーディングアシスタントは「何を」は理解できますが、「なぜ」は理解できません。これは最も高価な形式のドキュメント化されていない技術的負債の一つです。

2.4 すでに良い点

ドキュメントを統制対象のプロダクト面として扱うdocs-contract.mdのコンセプトは、正しい着眼点です。あとは適切なルールが必要なだけです。ルートにあるAGENTS.mdは優れており、AI支援開発における適切な先例を示しています。ADR-004は、チームが高品質なアーキテクチャ記録を作成できることを実証しました。

3. 分類フレームワーク：1ページ上のEAアーティファクト

EA Artifacts on a Page フレームワークは、アーキテクチャアーティファクトの5つのファミリーを定義しています。ZeroClaw リポジトリ内のすべてのドキュメントは、これらのファミリーのいずれかに属しており、そのファミリーがドキュメントの保存場所、フォーマット、および古さの基準を決定します。

この表から特に欠けているもの: ユーザーガイド、セットアップ手順、チャンネル固有のハウツー、トラブルシューティング、FAQ。これらは 運用コンテンツ であり、EAの成果物ではありません。これらはコードと連動してバージョン管理されません。これらはGitHub Wikiに属します。

フレームワークの使用

ドキュメントを作成する前に、次の2つの質問に答えてください：

1. これはどのアーティファクトファミリーに属しますか？ これに答えられない場合、あなたは書く準備ができていません。
2. コードとバージョン管理する必要がありますか？ はいの場合、リポジトリに配置します。いいえの場合、Wiki に配置します。

2つ目の質問に対する有用なテスト：この文書は、異なるバージョンのコードベースに対して読まれた場合に誤りや誤解を招くものになるでしょうか？ はいの場合、その文書はリポジトリにあり、コードとバージョン管理されます。いいえの場合、その文書はWikiに置かれます。

4. i18nの問題

4.1 削除の論拠

リポジトリから英語以外のコンテンツをすべて削除する根拠は、4つの柱に支えられています。

1. ユーザーはオンデマンドの翻訳手段を持っている。 ZeroClaw の主なユーザーは AI アシスタントを実行している人々です。そのような人は誰でも、実行しているエージェントを通じて、ブラウザを通じて、あるいは数十もの無料翻訳サービスのいずれかを通じて、即座に高品質な機械翻訳を利用できます。リポジトリに翻訳を同梱することの実用的な利点はわずかです。

2. 翻訳は古くなっている可能性が高いです。 マシン翻訳されたコンテンツは一度生成されただけで、英語のソースと同期されていません。AI支援開発において、古いドキュメントはドキュメントがないよりも悪いです。なぜなら、言語モデルは古い情報から誤った結論を自信を持って導き出すからです。

3. コントリビューター税は現実的で測定可能です。 docs-contract.md のパリティ要件により、ドキュメントのPRは最大6つの言語版にまたがって変更を行う必要があります。これにより、ドキュメントへの貢献のコストが高くなり、ドキュメントを健全に保つために不可欠な小さなインクリメンタルな改善（タイプミス修正、手順の明確化、古い参照の更新など）が抑制されます。

4. ローカライゼーションはコミュニティの取り組みであり、コアプロジェクトの作業ではありません。 日本語のドキュメントを維持するのに最も適した立場にあるのは、日本語を話すコントリビューターです。ローカライズされたコンテンツをメインリポジトリに配置し、同等性の要件を課すことは、恩恵を受けるコミュニティではなく、コアメンテナーに負担を強いることになります。GitHub Wiki はこれを正しく逆転させています。コミュニティメンバーは、PR を開くことなく、自言語のページを編集・維持できます。

4.2 残るもの

i18nのアプローチの「構造」を維持することが重要です。ZeroClawを複数の言語で利用可能にするという考え方は正しいです。ただし、「場所」と「所有権モデル」が間違っています。

4.3 置換戦略

1. 削除してください。リポジトリのルートにあるすべての README.*.md ファイルから、README.md を除く。

2. docs/i18n/ を完全に削除する

3. docs/ ディレクトリから英語以外のハブファイル（例：docs/README.zh-CN.md）をすべて削除してください。

4. Add a Languages section to the main README.md:

   翻訳: コミュニティによって維持されている翻訳は、GitHub Wiki で利用可能です。翻訳の追加や既存の翻訳の改善を行う場合は、Wiki を直接編集してください。すべての言語からの貢献を歓迎します。

5. GitHub Wiki に Translations ページを作成し、利用可能な言語の一覧、その進捗状況、およびそれらを管理している貢献者を含む表を追加してください。

6. オプション: 設定されたLLMプロバイダーを使用して任意のドキュメントページをオンデマンドで翻訳する zeroclaw docs --translate CLI機能を追加します。これは、製品の目的全体がAIアシスタンスである製品にとって自然にマッチします

4.4 AGENTS.md の影響

docs-contract.md から i18n のフォローアップ要件を削除し、以下の内容に置き換えてください：ドキュメントの PR は英語のみでレビューされます。翻訳はコミュニティによって Wiki で維持管理され、PR のレビュー対象ではありません。

5. リポジトリとWikiの分離

5.1 判断基準

コードの変更によって正しくなくなる文書はリポジトリに存在し、正しくなくなる文書はWikiに存在します。

これはファジールールではありません。これを文字通りに適用してください。

ADR は、特定の時点での特定のアーキテクチャの決定がなぜ行われたかを記録します。コードが変更されても、ADR は決定された内容と時期を正確に記述し続けます。コードはそこから進化しているかもしれませんが、記録自体は正確です。→ リポジトリ。

Telegramチャンネルの設定方法を説明するセットアップガイドには、ユーザーがソフトウェアの現行バージョンに対して行う手順が記載されます。設定形式が変われば、そのガイドは誤ったものになります。→ これはリポジトリに置くべきもののように思えますが、そうではありません。 セットアップガイドはコードのコミットに紐づけるのではなく、独自のタイムラインで更新されるべきです。正しいモデルは次のとおりです。APIリファレンス（設定の構造体に直接対応するもの）はリポジトリに置き、そのAPIの使い方をユーザーに案内するセットアップガイドはWikiに置いて、手順が変わったときに誰でも更新できるようにします。

5.2 実践における分割

リポジトリ内 (docs/book/src/) に保持:

GitHub Wiki への移行（提案済み；未実行）：

削除 (i18n 削除):

5.3 Wikiの構造

Home
│
├── Getting Started
│     ├── Installation
│     ├── Quick Start (TL;DR)
│     ├── Migrating from OpenClaw
│     └── Onboarding Walkthrough
│
├── Configuration
│     ├── Providers
│     ├── Channels
│     ├── Memory
│     ├── Security & Pairing
│     └── Tunnels
│
├── Channels
│     ├── Telegram
│     ├── Discord
│     ├── Slack
│     ├── WhatsApp
│     └── ... (one page per channel)
│
├── Operations
│     ├── Troubleshooting
│     ├── Deployment
│     ├── Network Setup
│     └── Performance Tuning
│
├── Hardware
│     ├── Getting Started with Peripherals
│     ├── ESP32 Setup
│     ├── STM32 Nucleo Setup
│     └── Arduino Setup
│
└── Community
      ├── FAQ
      ├── Translations
      └── How to Contribute

6. ADRの標準

6.1 フォーマット

すべてのアーキテクチャ決定記録は、機械可読性のために YAML フロントマターで拡張された Nygard format を使用します。ADR-004 はこの RFC によって特定されたモデルでした。このセクションはその形状を正式化します。

各ADRには3つのセクションと5つのフロントmatterフィールドがあります：

---
id: ADR-NNN
title: 決定を記述した短い命令文
date: YYYY-MM-DD
status: proposed | accepted | deprecated | superseded-by-ADR-NNN
relates-to:
  - ADR-XXX (任意、関連する決定のリスト)
  - crates/zeroclaw-api (任意、影響を受けるコードパス)
---

# ADR-NNN: タイトル

## 背景

どのような状況、制約、または問題が決定を必要としたのか？
どのような要因が働いていたか？どのような選択肢が検討されたか？

## 決定

何が決定されたか？能動態で記述する。
「～とする」ではなく「～と決定された」ではない。

## 結果

この決定の結果は何か？
肯定的な結果と否定的な結果の両方を列挙する。すべての決定にはトレードオフがある。
これによって生じる後続の決定やアクションを記載する。

## 参照

関連するコードファイル、イシュー、外部リソースへのリンク。

6.2 ADR ライフサイクルルール

• ADRは一度承認されると不変です。 決定が変更された場合、古いADRは superseded-by-ADR-NNN とマークされ、新しい決定とその理由を説明する新しいADRが作成されます。
• ADRは連番で番号が付けられ、再番号付けされることはありません。 番号の間に隙間があっても問題ありません（拒否されたADRが撤回された場合、その隙間が残ります）。
• ADRs は docs/book/src/architecture/decisions/ にあります。 これらは ADR-NNN-short-slug.md という名前です。
• 重要なアーキテクチャの変更にはADRが必要です。「重要」とは、新しいコントリビューターにとって驚くべき決定、将来の選択肢を制約する決定、または明らかなトレードオフを伴う決定を意味します。

6.3 基盤となる ADR セット

以下の基盤的な決定およびロードマップ上のターゲットには、長期的なADRが存在します。ADR-001からADR-005は、既存のアーキテクチャの遡及的な記録です。ADR-006およびADR-007は、FND-001に基づく実装ゲート付きターゲットを記述しており、対応する境界がリリースされるまでproposedのままにしておく必要があります。

遡及ADRには注釈を付ける必要があります：

これは、正式なADRプロセス以前に決定された事項の遡及的な記録です。日付は、この記録が作成された日ではなく、決定が行われた日を示します。

元の決定日が不明な場合は、ADRレコードが追加された日付を使用し、その旨をノートに記載してください。遡及的なADRがすでに後の決定によって置き換えられている場合は、履歴上のADRを保持し、置き換えるADRを別に記述してください。

6.4 なぜこれがAI支援開発において重要なのか

AI コーディングアシスタントがリポジトリを読み込む際、現在のコードのみが可視化されます。却下された選択肢、検討されたトレードオフ、あるいは特定の構造が他の代替案に対して選ばれた理由までは把握できません。ADR が存在しない場合、AI は自身では知ることのできないアーキテクチャ上の制約に違反する変更を提案する可能性があります。一方、ADR を用いることで、その判断根拠が明示され、機械可読な形式で表現されます。フロントマターにより ADR はクエリ可能となり、AI ツールは zeroclaw-api に関連するすべての ADR を検索し、そのクレートを編集する前にコンテキストとして読み込むことができます。

7. AI開発レイヤーとしてのAGENTS.md

7.1 パターン

ルートの AGENTS.md は、AI支援開発のための、プロジェクトのコンパクトで常に読み込まれる契約です。プロジェクト全体の安全性、プライバシー、認可、コントリビューション、検証ポリシーを管轄します。アーキテクチャとコントリビューションマップは、自明でないタスクを関連するソースへ誘導し、コーディングエージェントガイドラインは、例、現在の安定性割り当て、スキル検出、保護された運用ドキュメントなどの任意の詳細を保持します。この階層化された契約は、すべての詳細をすべてのセッションに読み込むことなく、具体的で明確な方針を持ち続けます。

ワークスペースがクレートに分割されていく中で（マイクロカーネルアーキテクチャのRFCに従って）、各クレートはそれぞれ独自のAGENTS.mdを持つべきです。これは、アーキテクチャ上の境界をAI支援レイヤーで強制可能にする仕組みであり、クレートの依存関係を通じたコンパイル時だけでなく、コードが書かれる前の推論レイヤーにおいても適用されます。

7.2 各クレート AGENTS.md の内容

短く保ってください。60行を超える AGENTS.md は読まれません。各ファイルは5つの質問に答えます：

# <crate-name>

## What this crate is
One or two sentences. What problem does this crate solve?

## What this crate is allowed to depend on
List the crates this crate may import. Be explicit.
If a dependency is not listed here, do not add it without an ADR.

## Extension points
Where can new implementations be added? What trait do they implement?
Link to the relevant traits.

## What does NOT belong here
Explicit anti-patterns. What would be a mistake to add to this crate?

## Related ADRs
- ADR-NNN: Short title

7.3 例

crates/zeroclaw-api 用（抽出後）:

# zeroclaw-api

## What this crate is
Trait definitions and shared data types for the ZeroClaw plugin and kernel
interfaces. This is the contract layer. Everything else depends on it.

## What this crate is allowed to depend on
- serde, serde_json (serialization)
- async-trait (async trait support)
- anyhow (error types)
- tokio (async runtime types, minimal)
Nothing else. No HTTP clients. No database drivers. No external services.

## Extension points
All traits in this crate are extension points:
- `Provider` (src/providers/traits.rs) — LLM provider implementations
- `Channel` (src/channels/traits.rs) — messaging platform integrations
- `Tool` (src/tools/traits.rs) — agent tool implementations
- `Memory` (src/memory/traits.rs) — persistence backends
- `Observer` (src/observability/traits.rs) — observability backends
- `RuntimeAdapter` (src/runtime/traits.rs) — execution environments
- `Peripheral` (src/peripherals/traits.rs) — hardware integrations

## What does NOT belong here
- Any concrete implementation of any trait
- Any dependency on a specific messaging platform, LLM provider, or database
- Any network I/O or filesystem access
- Any binary or executable target

## Related ADRs
- ADR-002: Trait-driven extensibility

crates/zeroclaw-kernel 用（抽出後）：

# zeroclaw-kernel

## What this crate is
The orchestration engine. Runs the agent loop, manages the service registry,
exposes the local IPC API. The kernel knows nothing about specific channels,
providers, or tools — only their abstract interfaces.

## What this crate is allowed to depend on
- zeroclaw-api (traits only)
- zeroclaw-tool-call-parser (parsing, no agent state)
- Standard async/runtime crates (tokio, anyhow, tracing)
- Config and storage crates (toml, serde, rusqlite for core memory)
NOT: any specific channel, provider, or tool implementation crate.

## Extension points
- `Registry::register_channel()` — add a channel at startup
- `Registry::register_tool()` — add a tool at startup
- `Registry::set_provider()` — set the active provider at startup
Implementations are registered by the binary crate, not by the kernel.

## What does NOT belong here
- Any import of TelegramChannel, DiscordChannel, or any named channel
- Any import of AnthropicProvider, OpenAIProvider, or any named provider
- Any tool implementation beyond the 10-12 designated core tools
- The gateway HTTP server or any web serving code

## Related ADRs
- ADR-002: Trait-driven extensibility
- ADR-006: Optional channels migrate to runtime plugins
- ADR-007: Gateway extraction into a separate optional binary

7.4 AGENTS.md の階層

ルート の AGENTS.md は、プロジェクト全体に適用されるコンパクトなポリシーを設定します。アーキテクチャおよびコントリビューションマップは、タスクを保守されているアーキテクチャ、基盤、テスト、セキュリティ、メンテナーの各ソースへ振り分けます。コーディングエージェントガイドラインは、プロジェクト全体にわたる詳細な例やレジストリを提供しており、必要に応じて役立ちますが、常時読み込まれるブートストラップの一部ではありません。

クレートレベルの AGENTS.md ファイルは、それぞれの対象範囲に合わせてそのポリシーを限定します。AI ツールが crates/zeroclaw-api/ 内のファイルを読み取る場合は、ルートの契約を読み、タスクのアーキテクチャマップに従い、存在する場合は crates/zeroclaw-api/AGENTS.md を読み取る必要があります。クレートのポリシーはより具体的であり、その対象範囲内では優先されますが、プロジェクト全体に適用される安全性、プライバシー、または認可の要件を弱めることはできません。

8. ターゲット構造

mdBook への移行後、リポジトリのコード隣接ドキュメントのソースレイアウトは次のとおりです:

docs/book/src/
│
├── README.md                    ← mdBook introduction
├── SUMMARY.md                   ← Canonical mdBook TOC
│
├── architecture/
│   ├── overview.md              ← Current system landscape
│   ├── decisions/               ← ADRs (immutable once accepted)
│   │   ├── ADR-001-rust-first.md
│   │   ├── ADR-002-trait-driven-extensibility.md
│   │   ├── ADR-003-wasm-plugin-model.md
│   │   ├── ADR-004-tool-shared-state-ownership.md
│   │   ├── ADR-005-pluggable-memory-backends.md
│   │   ├── ADR-006-runtime-channel-plugins.md
│   │   ├── ADR-007-gateway-extraction.md
│   │   └── ADR-009-wit-wasmtime-plugin-execution.md
│   └── diagrams/
│       ├── component-map.md     ← Mermaid: crate topology
│       └── data-flow.md         ← Mermaid: message lifecycle
│
├── contributing/
│   ├── index.md
│   ├── architecture-map.md
│   ├── rfcs.md
│   ├── testing.md
│   └── pr-review-protocol.md
│
├── reference/
│   ├── index.md
│   ├── cli.md
│   ├── config.md
│   └── providers.md
│
├── security/
│   ├── overview.md
│   ├── model.md
│   ├── sandboxing.md
│   └── tool-receipts.md
│
├── hardware/
│   ├── index.md
│   ├── subsystem.md
│   ├── adding-boards-and-tools.md
│   └── hardware-peripherals-design.md
│
└── foundations/
    ├── fnd-001-intentional-architecture.md
    ├── fnd-002-documentation-standards.md
    ├── fnd-003-governance.md
    ├── fnd-004-engineering-infrastructure.md
    ├── fnd-005-contribution-culture.md
    └── fnd-006-zero-compromise-in-practice.md

現在の構造から削除:

docs/i18n/                       ← 169 files, 2.2 MB — removed entirely
docs/maintainers/                ← project snapshots and i18n coverage maps
                                   moved to Wiki (operational, not code-adjacent)
docs/setup-guides/               ← moved to Wiki
docs/ops/                        ← moved to Wiki
README.ar.md (and 30 others)     ← removed from repo root
docs/README.ar.md (and 30 others)← removed

リポジトリのルートがクリーンになります：

README.md
AGENTS.md
CHANGELOG.md
CLAUDE.md
CODE_OF_CONDUCT.md
CONTRIBUTING.md
SECURITY.md
LICENSE-APACHE
LICENSE-MIT
NOTICE
Cargo.toml
Cargo.lock
... (build and config files)

言語のバリエーションはありません。重複するREADMEもありません。ユーザーガイドはWikiに、技術リファレンスはdocs/ディレクトリにリンクする、1つの権威ある英語のREADMEがあります。

9. 置換ドキュメント契約

従来の docs/contributing/docs-contract.md は、この RFC で廃止された i18n パリティ要件とディレクトリ構造を定義していました。このファイルは削除され、このセクションがその代替となります。

この置き換えは3つの事項を統括します。成果物の分類、リポジトリ/wikiの分割、そしてADRガバナンスです。i18nについては何も触れていません。ロケールの整合性は現在、Maintainers → Docs & Translationsページで扱われています。

置換ドキュメント契約:

# Documentation Contract

## Document Classification

Every document in `docs/` belongs to one artifact family:

- **Considerations** — principles and standards that guide decisions
- **Landscapes** — descriptions of the current system state
- **Outlines** — proposals and roadmaps for future work
- **Designs** — ADRs, API specs, and detailed technical decisions
- **Standards** — specific rules for how we build and operate

If you cannot name the family before writing, do not write yet.

## The Repo / Wiki Rule

A document lives in the repository if it would become wrong when the
code changes. It lives on the Wiki if it would not.

Reference documentation (config reference, CLI reference) lives in the
repository because it maps directly to code structures.

User guides, setup instructions, and operational how-tos live on the Wiki
because they update on their own timeline.

## ADR Governance

See `docs/book/src/architecture/decisions/` for the ADR format and lifecycle rules.

Major architectural changes require an ADR before implementation begins,
not after.

## Language

All documents in this repository are written in English.
Community-maintained translations live on the GitHub Wiki.
Documentation PRs are reviewed in English only.

## Freshness

Documents should be updated in the same PR as the code change that makes
them stale. A PR that changes a configuration format must update the
config reference. A PR that adds a new command must update the CLI reference.

RFC issues and roadmap trackers are exempt - they describe intent and
may precede implementation by multiple releases.

10. 採用すべき基準

これらのドキュメント固有の基準は、アーキテクチャRFCで提案されたより広範な基準を補完するものです。

Diátaxis フレームワーク（ドキュメント構造）

概要: Diátaxis（https://diataxis.fr）は、技術文書を4つのタイプ（チュートリアル、ハウツーガイド、リファレンス、説明）に分類する体系的なフレームワークです。これは、Pythonドキュメント、Djangoドキュメントなど、多くのドキュメントの基盤となっているフレームワークです。EA Artifactsアプローチとの互換性が非常に高く、両者は異なる問いに答えます（Diátaxis: 文書の内容をどのように構成するか、EA Artifacts: これはどのタイプの文書で、どこに配置されるか）。

適用方法: ウィキ上のユーザー向けドキュメントはDiátaxis構造に従う必要があります。リポジトリ内のコードに隣接するドキュメントはEA Artifactsに従います。これら2つのフレームワークは異なるレベルで機能し、競合しません。

機械可読性のためのMarkdownフロントマター

docs/ 内のすべてのドキュメントには YAML フロントマターを含める必要があります。これにより、AI ツール、CI チェック、将来のツールでクエリ可能になります。

---
型: adr | 提案 | 参照 | 貢献 | セキュリティ | ハードウェア
ステータス: ドラフト | 提案 | 承認 | 非推奨 | 代替
最終レビュー日: YYYY-MM-DD
関連する:
  - ADR-NNN
  - crates/zeroclaw-api
---

CI チェックでは、docs/ 内のすべてのドキュメントが有効なフロントマターを持っていることを検証する必要があります。これにより、ドキュメントがタイプとステータスを最初に宣言せずに作成されることを防ぎ、ツールレベルで分類規律を強制します。

CommonMark + GitHub Flavored Markdown

すべてのドキュメントは、CommonMark（標準化されたMarkdown仕様）とGitHub Flavored Markdownの拡張機能（テーブル、タスクリスト、フェンシングされたコードブロック、Mermaidダイアグラム）を使用しています。カスタム拡張機能、MDX、ReStructuredTextは使用しません。アーキテクチャ図には画像ファイルよりもMermaidダイアグラムが推奨されます。これは、コードとバージョン管理がきれいに同期するためです。

Prose Linting 用の Vale

概要: Vale (https://vale.sh) は文章用のリンターです。設定可能なルールを使って、文章のスタイル、一貫性、読みやすさをチェックします。たとえば次のようなことを強制できます。常に「the user」ではなく「you」を使う、命令形のセクションでは受動態を避ける、用語を統一する（「extension」や「module」ではなく「plugin」を使う）。

なぜ重要か: 現在のドキュメントは、トーン、用語、スタイルが一貫していません。一部のページでは「プラグイン」、一部では「モジュール」、一部では「拡張機能」と表記されています。Vale はこれらのルールを自動化し、Clippy がコード品質を強制するのと同じように、CI 時にそれらを強制します。

11. フェーズ別ロードマップ

ドキュメントの移行は、アーキテクチャの移行と同じく、Strangler Fig パターンに従います。これは、段階的に行い、常に動作する状態を維持し、大規模な書き換えを避けるアプローチです。

フェーズ 1 · v0.7.0: 「Clean the Root」

納品物:

• リポジトリのルートからすべての README.*.md ファイルを削除します（README.md のみを残します）。
• docs/i18n/ を完全に削除
• docs/ から英語以外のハブファイルをすべて削除する
• README.md に Wiki リンク付きの Languages セクションを追加
• GitHub Wiki を作成し、構造的な骨格（ホーム + 上位レベルのページ、コンテンツのスタブ）を設定します。
• docs-contract.md から i18n パリティ要件を削除する
• 既存の docs/ ファイルにYAMLのフロントマターを追加する
• docs/book/src/architecture/decisions/ を作成し、ADR-001 と ADR-002 を追加し、ADR-003 と ADR-004 を復元し、ADR-003 を置き換える WIT/wasmtime の記録として ADR-009 を追加する

成功指標:

• リポジトリのルートには、READMEファイルが1つだけ含まれています。
• docs/i18n/ は存在しません
• すべての docs/ ファイルには有効な YAML フロントマターが含まれています（CI で強制）。
• GitHub Wikiが公開され、READMEから公開リンクされています

フェーズ2 · v0.7.0〜v0.8.0:「不足しているADRを記述する」

納品物:

• 現在のメモリーストレージ契約を遡及的に記録する ADR-005 を作成する
• 実装ゲート付きの FND-001 ターゲットに対する提案版 ADR-006 および ADR-007 レコードを作成する
• Vale の設定（.vale.ini およびスタイルルール）と CI チェックを追加
• Section 9 で指定されたバージョンに docs-contract.md を完全に置き換えます
• docs/setup-guides/ のコンテンツを GitHub Wiki に移行する
• docs/ops/ のコンテンツを GitHub Wiki に移行する
• SUMMARY.md を更新して、新しい構造（リポジトリ固有のコンテンツ）を反映してください。
• （抽出を見越して）crates/zeroclaw-api のルートレベル AGENTS.md を作成する

成功指標:

• ADR-001からADR-007は、それぞれ適切なステータス（accepted、proposed、またはsuperseded）で存在します
• ADR-009 は ADR-003 を置き換える WIT/wasmtime の決定を記録する
• Vale CI チェックがすべてのドキュメントでパスしました
• Wikiには、移行されたすべてのセクションの完全なコンテンツがあります。
• docs/ 内にリンク切れはありません

フェーズ3 · v0.8.0〜v0.9.0：「AIレイヤー」

納品物:

• ワークスペースの分解（アーキテクチャ RFC のフェーズに従って）に応じて、各新規クレートごとに AGENTS.md を作成します。
• docs/book/src/architecture/diagrams/component-map.md（Mermaid、対象クレートのトポロジーを反映）を作成する
• docs/book/src/architecture/diagrams/data-flow.md を作成する（Mermaid、メッセージのライフサイクル）
• docs/book/src/developing/plugin-sdk.md にプラグイン SDK のドキュメントを作成してください
• WITインターフェースのドキュメントを、wit/ ディレクトリ内のファイル（WITから生成されたもの＋手書きの説明）と併記してください。
• カーネルのIPC APIが安定化するにつれて、OpenAPI仕様のドキュメントを更新してください。

成功指標:

• ワークスペース内のすべてのクレートには AGENTS.md があります。
• アーキテクチャ図は Mermaid で記述してください（docs/ ディレクトリにはバイナリ画像ファイルを含めないでください）。
• プラグインSDKのドキュメントは、外部の貢献者が動作するツールプラグインを作成するのに十分な内容です。

フェーズ4 · v1.0.0:「安定したプラットフォーム」

納品物:

• 対応するコードがリリースされたら、ADR-006 と ADR-007 を accepted にマークする
• v1 のカーネル IPC API ドキュメントに安定性保証を付与
• Plugin Registry ガバナンス文書を作成する（誰がレジストリを管理するか、プラグインをどのようにレビューするか、侵害されたプラグインをどのように取り消すか）
• プラグインSDKをスタンドアロンのドキュメントサイトとして公開する（docs/book/src/developing/plugin-sdk.md から）
• Wikiの翻訳コーディネーターの役割を確立する（翻訳ページを管理し、ボランティア翻訳者を調整するコミュニティメンバー）

成功指標:

• すべての基礎的なADRが承認されました
• プラグインSDKは完成し、READMEから外部リンクされています。
• Wikiには、少なくとも2つの言語でコミュニティが積極的に維持している翻訳があります。
• ドキュメントCI（フロントmatterチェック + Vale）は、すべてのPRでパスします。

付録 A: 用語集

ADR（アーキテクチャ決定記録）: 重要なアーキテクチャ上の決定を記録した不変のレコードです。決定を促した背景、決定された内容、そしてその結果を記録します。ADR は一度承認されると変更されません。置き換えられた決定は、新しい ADR として記録されます。

Diátaxis: 技術ドキュメントの構造を体系化するためのフレームワークで、コンテンツをチュートリアル（学習）、ハウツーガイド（目的指向）、リファレンス（情報）、説明（理解）に分類します。https://diataxis.fr を参照してください。

EA Artifacts on a Page: Svyatoslav Kotusev によって開発された、エンタープライズアーキテクチャドキュメントの分類フレームワーク。アーティファクトを Considerations、Landscapes、Outlines、Designs、Standards の5つのファミリーに分類します。https://eaonapage.com を参照してください。

Frontmatter: Markdown ファイルの先頭にある YAML メタデータで、--- で区切られます。ドキュメントを機械可読にし、ツールや CI チェック、AI アシスタントからクエリ可能にします。

Nygard形式: Michael Nygardによって導入されたADR形式。3つのセクション（Context、Decision、Consequences）で、不要な形式張った手続きなしに本質的な論拠を捉えます。

ストラングラーフィグパターン: 古い構造の周りに新しい構造を段階的に構築し、一度にすべてではなく部分ごとに置き換えていく移行戦略。移行期間中、システムは機能し続けます。

Vale: 技術ドキュメント向けの文章リンター。Clippy が Rust コードの品質を強制するのと同じように、CI 時にスタイル、一貫性、読みやすさのルールを強制します。https://vale.sh を参照してください。

付録B: 参考文献

• Diátaxis ドキュメンテーションフレームワーク：技術ドキュメントをタイプ別に構造化するための決定版リファレンス。
• 1ページのEA成果物 (v2.2): セクション3で使用される分類フレームワーク。
• “Docs for Developers”: Jared Bhatti 他著: 大規模なドキュメントシステムを保守してきたエンジニアによって書かれた、技術ドキュメントの実践ガイド。
• Vale documentation: セクション10で提案されている文章リンターのセットアップガイドと設定リファレンス。
• Michael Nygard による ADR の解説: Section 6 で使用されている ADR 形式を紹介した元の記事です。
• GitHub Wikis ドキュメント: セクション 5 で提案されている GitHub Wiki の設定と管理に関するリファレンス。

この提案は、ZeroClawのドキュメントシステム（v0.6.8）の直接分析に基づいて作成されました。引用されている指標（169のi18nファイル、2.2 MB、31言語のREADMEバリアント）は直接測定に基づいています。推奨事項は、オープンソースインフラストラクチャプロジェクトの技術文書における確立されたプラクティスを反映しており、ZeroClawの特定の制約と目標に合わせて適応されています。

フィードバック、修正、および反提案を歓迎します。優れたドキュメントはコミュニティの取り組みであり、最も良い構造はチームが実際に維持できるものです。