アーキテクチャとコントリビューションマップ
タイプミスより大きな変更を行う際に、アーキテクチャ、基盤、コントリビューター、メンテナーのどのドキュメントが該当するか分からない場合は、このページを参照してください。
このページはあくまで地図にすぎません。リンクされたファイルが信頼できる情報源です。
ここから始める
- Read the repo-root
AGENTS.mdfirst. It contains the compact, always-loaded safety and contribution contract. - PR の手順、検証で求められること、レビュープロセスについては、コントリビューション方法を参照してください。
- 以下の表を使用して、変更に一致するアーキテクチャとファウンデーションのドキュメントを選択してください。
- AI コーディングタスクで、信頼できる唯一の情報源となる詳細な例、リスクおよび安定性ポリシー、スキル検出、または保護された運用ドキュメントが必要な場合は、コーディングエージェントのガイドラインを参照してください。
- 変更がサブシステム、設定、セキュリティ、ワークフロー、ガバナンス、またはリリースの境界をまたぐ場合は、実装前に RFCプロセス を確認してください。
共通の変更パス
| 変更 | 最初にお読みください | なぜ |
|---|---|---|
| 新しいプロバイダー | アーキテクチャの概要、Crates、カスタムプロバイダー、プロバイダーの設定 | プロバイダーは、provider trait の背後にあるエッジアダプターであり、構成とファクトリの配線を備えています。 |
| プロバイダープロファイルの選択、モデルルート、セッションオーバーライド、実行時のモデル切り替え、リトライ、フォールバック、またはプロバイダーの帰属 | プロバイダーのルーティング ライフサイクル、ルーティング、プロバイダー設定 | ルート選択、試行ポリシー、プロファイル構築、要求と提供結果の対応付けは、それぞれを担当するレイヤーに保持します。 |
| プロバイダー ストリームの解析、終了、またはターン単位の再生 | プロバイダールーティングのライフサイクル, ストリーミング, テスト | ワイヤー完了はアダプターで保持し、呼び出し全体のリプレイはランタイムで保持します。不変のイベント出力が可視になった後は、決してリプレイしないでください。 |
| 新しいチャンネル | アーキテクチャ概要、クレート、チャネルランタイムのライフサイクル、チャネル概要、crates/zeroclaw-channels/ 内の既存の実装 | チャネルはユーザー可視の信頼境界です。インバウンド、アウトバウンド、ペアリング、認可、ディスパッチ、および返信ライフサイクルの動作を検証してください。 |
| チャネルディスパッチ、Webhook イングレス、返信インテント、ストリーミング下書き、リスナーのライフサイクル、またはチャネルのリロード動作 | チャネルランタイムのライフサイクル、リクエストのライフサイクル、Gateway HTTP API、プラグインプロトコル、テスト | チャネルのライフサイクル変更には、ワンオフのアダプターやゲートウェイのミニオーケストレーターではなく、単一のディスパッチとターンパスが必要です。 |
| 新しい組み込みツールまたはツールポリシー | ツールの概要、組み込みツール一覧、ツール実行のライフサイクル、ADR-004: ツール共有状態の所有権、プラグインプロトコル、セキュリティの概要、ツールレシート | ツールはエージェントのアクションを実行します。まず、その機能がコアに属するかどうかを確認し、次に登録、承認、ディスパッチ、監査、レシート、ローカライゼーション、属性、共有状態の所有権を検証します。 |
| ランタイム、エージェントループ、状態、プロバイダーのトークンストリーミング、またはツールループの動作 | リクエストのライフサイクル、ランタイムの状態と永続化、ツール実行のライフサイクル、Crates、FND-001、テスト | ランタイムの変更は複数のユーザーパスに影響を与えることが多く、境界レベルのテストが必要です。プロバイダーのトークンストリーミングはランタイム所有のままです。チャネルのドラフトや入力インジケーターのストリーミングは、チャネルライフサイクルの行に従います。ツールループの変更では、承認、ディスパッチ、レシート、オブザーバーイベント、履歴、キャンセルのいずれに影響するかを明示する必要があります。 |
| Cron、SOP、委任、サブエージェント、goal-mode、待機、キャンセル、または再起動リカバリの動作 | バックグラウンド作業のライフサイクル、委譲とサブエージェント、テスト | バックグラウンド実行は単一のライフサイクルではありません。現在のオーナーとステータスの公開面を明示し、永続的なレコードと再起動後に再開可能な作業を区別し、変更後の境界でキャンセルと復旧を検証してください。 |
| メモリ、セッション履歴、プロンプトコンテキスト、ツール結果、ファイル/メディアのペイロード、またはコンテキストのトリミング | メモリとペイロードのライフサイクル、ランタイムの状態と永続化、履歴管理、ランタイム内部、テスト | ペイロードの変更には、明確な所有者、スコープ、耐久性、プライバシー、および切り捨ての境界が必要です。 |
| ロギング、可観測性、ランタイムトレースの永続化、ログのページネーション、保持、またはスキーマ移行 | ロギングアーキテクチャ、ログと可観測性、ランタイム状態と永続化、ゲートウェイ HTTP API、セキュリティ概要、テスト | 1つの正規イベントが、ライブ配信と永続化された JSONL にそれぞれ独立して提供されます。オプションの型付き Observer プロジェクションは、バインドされている場合にのみ実行されます。プロジェクションのフィールド、アクティブファイルのカーソルの存続期間、書き換えと保持の動作、移行の互換性、および変更先でのプライバシーを検証します。 |
| ゲートウェイ、Web API、またはダッシュボードの動作 | Gateway HTTP API, Web ダッシュボードの構築, リクエストライフサイクル, セキュリティ概要, レビュアープレイブック | Gateway の変更は、認証、パブリック露出、生成された API コントラクト、ダッシュボードコンシューマー、およびレビューリスクに影響を与える可能性があります。Webhook のディスパッチまたは返信動作には、チャネル ライフサイクルの行を使用してください。 |
| コマンド、ターミナル、デーモン、ブラウザ、チャンネル、プロバイダー、ツール、バックグラウンドジョブ、またはインストールパスに関するユーザーが確認できる動作または検証の証拠 | ユーザー境界の証明、テスト、および変更対象の領域に関するアーキテクチャまたは機能のドキュメント | 各動作に関する主張を、ユーザーがそれを観測する境界に到達する最小限の信頼できる根拠に対応付けます。手動または環境固有の証拠は、自動テストのカバレッジに明示的に特定されたギャップがある場合にのみ追加します。 |
| 設定スキーマ、環境変数、デフォルト、またはリロード動作 | 設定のライフサイクル、環境変数、ランタイム状態と永続化、プロバイダー設定、FND-001、RFCプロセス | 設定変更はアップグレードパス、リロード動作、ソース・オブ・トゥルースの境界に影響し、マイグレーションまたは RFC の議論が必要になる場合があります。 |
| 生成された参照、mdBook プリプロセッサー、ドキュメントのスニペット、またはドキュメントのデプロイ | 設定への参照が変更された場合の生成ドキュメントパイプライン、ドキュメントのローカルビルド、設定ライフサイクル | 正規のソース、マテリアライザー、追跡対象またはビルド専用の出力、コンシューマー、ドリフトチェックを指定してください。 |
| Fluent/gettext カタログ、ロケールレジストリ、翻訳フォールバック、またはカタログリリースピン | ローカリゼーションカタログのライフサイクル、ドキュメントと翻訳、生成ドキュメントパイプライン | リポジトリに存在するカタログは、ランタイムやサイトビルドがそれを使用している証拠にはなりません。ローダー、マテリアライザー、またはピンパスを確認してください。 |
| CI、リリース、GitHub Actions、または許可されたアクション | CI & Actions、FND-004、PR workflow | インフラストラクチャの変更は、実行またはリリースできるコードに影響を与える場合、高リスクとなります。 |
| ドキュメント構成、コントリビューターガイダンス、またはナレッジの体系化 | FND-002、ドキュメントと翻訳、このページ | ドキュメントの変更は、検索コストを削減し、意思決定の経緯を保持するべきです。 |
| ガバナンス、ラベル、ボードワークフロー、またはコントリビューションプロセス | FND-003、RFCプロセス、ラベル、レビュアープレイブック | プロセスの変更はメンテナーとコントリビューターに影響するため、永続的かつ明示的に保つこと。 |
| AI支援によるコントリビューション、置き換え、またはレビューの文化 | FND-005、PRの差し替え、PRレビュープロトコル | AIを活用した作業は歓迎しますが、正確性、帰属表示、レビュー対応については人間のスポンサーが責任を負います。 |
| 本番コードの健全性、エラー処理、またはデッドコードのクリーンアップ | FND-006、Testing、リポジトリルートの AGENTS.md | エラー処理の徹底、未使用コードの排除、本番環境への対応準備は、スタイルの好みではなくレビューの合否基準です。 |
1画面ですべての基礎ドキュメントを表示
| Foundation | 変更が要求している場合に読み取る… |
|---|---|
| FND-001: 意図的なアーキテクチャ | これはマイクロカーネル/ランタイムの方向性に合致していますか？どのレイヤーが所有すべきですか？ |
| FND-002: ドキュメント標準 | 知識はどこに置くべきか？ドキュメントをどのように見つけやすく、長持ちさせるべきか？ |
| FND-003: ガバナンス | 誰が決定するのか？どのラベル、プロジェクトボード、または RFC プロセスが状態を管理すべきか？ |
| FND-004: エンジニアリングインフラストラクチャ | CI、リリース自動化、または GitHub Actions はどのように動作すべきですか? |
| FND-005: コントリビューション文化 | コントリビューター、メンテナー、そしてAI支援による作業は、どのようにコミュニケーションを取り、レビューを行うべきですか？ |
| FND-006: 実践における妥協なきアプローチ | 本番コード、エラー、デッドコード、リリース準備状況には、どの品質基準が適用されますか？ |
コーディングエージェントのエントリポイント
コーディングエージェントは、人間と同じ公開ドキュメントに加えて、リポジトリローカルのエージェントコントラクトを使用する必要があります。
- リポジトリルートの
AGENTS.mdに従ってください。.claude/skills/*/SKILL.mdを確認し、該当するリポジトリ内のスキルがある場合はそれを使用してください。スキルファイルが信頼できる情報源です。 - 基盤ドキュメントは意思決定のコンテキストとして扱います。レビューで分割、RFC、より強力な検証、または別のオーナーが求められる理由を説明するものです。
- プライベートなワークフローの仕組みは、公開されるPR本文、Issueコメント、レビューに含めないでください。公開テキストでは、具体的な動作、ソースパス、コマンド、検証の証拠、リンクされたIssue、ユーザーに見えるリスクを挙げるべきです。
- 生成されたドラフトやスキルで作成されたドラフトが、ソースコード、現在の
AGENTS.md、または批准された基盤ドキュメントと矛盾する場合は、投稿または実装する前に作業を停止して整合させてください。
RFCとPRのチェックポイント
このマップは RFC プロセス や PR テンプレートを置き換えるものではありません。適切なドキュメントを見つけやすくするためのものです。RFC プロセス には正規の「これは RFC 向きか？」の表が掲載されているため、ここで言い換えたリストから推測するのではなく、そちらを確認してください。RFC #6808 のポリシースライスが昇格された後は、FND-003、Labels、PR workflow、Reviewer playbook に従ってください。
- 変更があいまいで、明確にRFCの形になっていない場合は、実装前にメンテナーに確認するか、PRの範囲を絞り込んでください。
- PR を作成する前に、PR テンプレート（
.github/pull_request_template.md）の質問に回答してください。回答が明確でない場合は、まず設計ノートまたは RFC を作成してください。