コーディングエージェントのガイドライン

リポジトリ ルートの AGENTS.md は、AI コーディングアシスタント向けの、簡潔で常に読み込まれる規約です。このページには一部のタスクに役立つ詳細が記載されていますが、すべてのセッションでプロンプトの予算を消費しないようにしています。

これらのルールは、モデルのサイズやモデルの実行場所に関係なく適用されます。コンパクトなプロンプトプロファイルは、コンテキストを積極的にロードする量を変える場合がありますが、安全性、プライバシー、認可、またはコントリビューションの要件を弱めることはありません。

このページの使い方

まず アーキテクチャとコントリビューションのマップ から始めてください。その変更パス表では、各タスクを現在のアーキテクチャ、基盤、テスト、セキュリティ、メンテナー向けドキュメントへ案内しています。以下のエージェント固有の事項についてのみ、ここに戻ってください。

信頼できる唯一の情報源の例

状態のいかなる要素も、独立して管理される2か所に存在してはなりません。設定、スキーマ、ランタイム状態、または生成された定義にすでに存在する情報は、別のフィールドにコピーするのではなく、そのソースから解決または導出してください。

構造体フィールド、チャネルまたはハンドルのフィールド、スキーマフィールド、または設定エントリを追加する前に、次のいずれかの回答を明記してください:

1. “これは、ここで作成された信頼できる唯一の情報源です。” それが何を表しているかを述べてください。
2. “信頼できる唯一の情報源は <path> です。これではそれを複製することになります。” 使用時にその場所から解決してください。

重複状態のクリーンアップをフォローアップに先送りしないでください。再起動時のみのスナップショットも依然として重複状態です。

禁止されている例:

• チャンネルハンドルは認証済みユーザーをキャッシュしますが、ライブ設定がそれらを所有します。
• enum と、それとは別に手動で管理されているバリアントのリスト。
• ランタイムがライブ構成から読み取れるフィールドを複製した構成スナップショット
• プロバイダーの認証情報を別のランタイムフィールドにコピーする。

使用可能な例:

• Arc<RwLock<Config>> に対するリゾルバのクロージャ;
• 借用された Config または型指定された config パラメータ;
• 操作中にのみ使用され、それ以降は保存されないオンデマンドビュー。
• 1つの入力から複数のサーフェスを生成するマクロまたはジェネレーター。

アーキテクチャと所有権

ZeroClaw は Rust ファーストの、トレイト駆動型エージェントランタイムです。主要な拡張トレイトは crates/zeroclaw-api/src/ にあります:

• model_provider.rs（ModelProvider）
• channel.rs（Channel）
• tool.rs (Tool)
• memory_traits.rs (Memory)
• observability_traits.rs（Observer）
• runtime_traits.rs (RuntimeAdapter)
• peripherals_traits.rs (Peripheral)

別のクレートやリポジトリのインベントリをここで管理しないでください。所有権と依存関係の方向については Crates を、現在のメンバーシップについてはルートの Cargo.toml のワークスペースメンバーを、プロバイダー、チャンネル、ツール、プラグイン、ランタイム、および設定変更パスについてはアーキテクチャマップを使用してください。

安定性とリスク

安定性ティアの定義とバージョニングポリシーは FND-001 に記載されています。コンポーネントローカルの AGENTS.md ファイルおよびプラグインレジストリマニフェストが、対象となるオーナーシップモデルです。すべてのコンポーネントに対応ファイルが揃うまでは、以下の表が現在のアサインメントに関する正式な情報源です。別の手動管理された集約ファイルにコピーしないでください。

現在の安定性の割り当て

Stable コンポーネントは破壊的変更ポリシーに従います。Beta コンポーネントは、MINOR リリースで変更履歴の注記を伴って破壊的変更を行う場合があります。Experimental コンポーネントには安定性の保証はありません。ティアは、チームによる慎重な決定を通じて昇格されることはあっても、降格されることはありません。

変更リスクの振り分けは、パスではなく影響に基づきます。正式な定義については、メンテナーラベルガイドを使用してください。risk:low は、本番、互換性、ビルド、リリース、またはガバナンスへの影響がないドキュメント、フィクスチャ、および機械的なメタデータを対象とします。risk:medium は通常の動作変更を対象とします。risk:high は、具体的な信頼、認証情報、互換性、ガバナンス、またはリリース権限に関する境界を対象とします。domain:security は risk:* とは独立しており、実効的なセキュリティ境界を識別します。

risk:high または domain:security のいずれかを付けた PR は、マージ前に詳細なレビューと、独立した Core Team メンバー 2 名による承認が必要です。不確実性は上位の区分に分類してください。検証およびロールバックの証拠は、変更行数だけでなく、実際の影響範囲に見合ったものにしてください。PR の手順については How to contribute を、検証の分類については Testing を参照してください。

スキルの検出

リポジトリが所有するコーディングアシスタントのスキルは .claude/skills/ に配置されています。利用可能な */SKILL.md ファイルを確認し、要求された操作に一致するスキルのみを読み込んでください。このページに2つ目のスキルカタログを保持しないでください。ディレクトリが現在のインベントリであり、各スキルファイルが自身のワークフローを所有します。

保護された運用ドキュメント

これらのファイルは skills や開発ツールから参照されます。参照元とリポジトリのガイダンスを更新せずに、移動または削除しないでください。

ローカリゼーションとプライバシー

ユーザー向けのテキストと英語のみのロギングに関するルールは、ルートの AGENTS.md に記載されています。Wiki と内部の開発者向けドキュメントも英語のみです。詳細な規約については、Privacy and PII discipline と Docs and translations を参照してください。

関連資料

• アーキテクチャとコントリビューションのマップ
• 貢献方法
• プライバシーと PII の規律
• テスト
• アーキテクチャの概要
• プルリクエストを置き換える
• 監査ポリシー