2026-05-15 OpenClaw ワークスペース AGENTS.md をリポジトリ概要として使う：ヘッドレス レンタル Apple Silicon クラウド Mac（HK / JP / KR / SG / US）

OpenClaw がモノレポ全体を読めるとき、最もレバレッジが高いのは追加の JSON ノブだけではなく、Git ルートに置かれた規律ある AGENTS.md である——人間とモデルの双方に「正常系」を説明する。香港・東京・ソウル・シンガポール・米国でレンタルした Mac mini M4 では、同一ホストが xcodebuild、署名ツリー、Swift を編集するアシスタントを同居させがちである。2026-05-15 の本稿は AGENTS.md を広い方針スタックの中に配置する：ワークスペース許可リストとモノレポ ガードレール と整合させ、マルチエージェント agents.json の役割分離 と補完し、onboard・launchd・doctor と同じ倉庫で進化させる——機械可読なツール表を Markdown に行単位で複製しない。

agents.json があるのに、なぜリポジトリ級 AGENTS.md がまだ必要か

agents.json はアイデンティティ、モデル、ツール面を符号化し、ゲートウェイが決定的に解釈すべき契約である。AGENTS.md は別の問いに答える：このリポジトリが何をビルドするか、どのディレクトリが触れてはならないか、どのテストコマンドが権威か、ロールバックをどう段階化するか、危険な編集で誰を起こすか。共有レンタル ビルダーでは、その叙述がインシデント diff で「意図」を示し、配列だけの JSON よりレビューしやすい。朗読で約二分以内に収まる長さを維持し、長手順は スキル束 へ移し、ここでは入口パスと発火条件を明示する。

方針スタック：AGENTS.md は許可リストと agents.json のどこに置くか

上から順に、トランスポートとチャンネル、ゲートウェイ ルーティング、ワークスペース許可リスト、エージェント実行時 JSON、任意のスキル、最後にリポジトリ説明。AGENTS.md はリポジトリの社会的契約に最も近い——既定拒否のファイルシステム方針を覆さないが、ルートが存在する理由とアシスタントの期待挙動を説明する。複数エージェントが同一ホストを共有しても同じリポジトリを読むため、AGENTS.md はペルソナ中立を保ち、tools の狭義化は agents.json に任せる。

層	主アーティファクト	所有者	AGENTS.md は…
ファイルシステム ガード	ワークスペース許可リスト	プラットフォーム／セキュリティ	パスで根を参照し、別ルールを書かない
ランタイム方針	agents.json	自動化オーナー	プロファイルの意図を説明し Git 内 JSON パスへリンク
手順の深さ	スキル／ランブック	サービスチーム	安定見出しで索引化し、長い shell を貼らない
人＋モデル文脈	AGENTS.md	リポジトリ メンテナ	ミッション、テスト、ロールバック、連絡先を中立に記す

OpenClaw 依存が強いリポジトリ向け AGENTS.md スケルトン

安定した見出しで人間とモデルの両方が検索しやすくする。冒頭一段落でミッションを書き、非目標を明示する——人間承認なしにしてはならない操作（本番デプロイ、キーチェーン変更、無関係レーンの DerivedData 削除など）。権威あるテスト入口（xcodebuild test の scheme、SwiftPM の選択、lint ラッパー）と非対話シェル必須の環境変数を列挙する。最後に昇格：Slack チャンネル、オンコール、レンタル機でゲートウェイ ログを採取するコマンド。

• ミッションと範囲 — プロダクト文脈、リリース cadence、サポート分支。
• ディレクトリ地図 — 生成物、秘密テンプレ、CI チェックアウトの置き場。
• 検証 — 変更が安全と言える最小コマンド集合。
• ロールバック — Git 戻し戦略とホスト側キャッシュ掃除。

トークンと分量：AGENTS.md は薄く、スキルは厚く

巨大な Markdown はファイルツールが取り込むコード断片とコンテキストを奪い合う。短い段落、リンク表、安定アンカーを優先する。リリースタグ付け、notarize と stapling、多リージョン展開など長い連鎖はスキルへ移し、ゲートウェイがオンデマンドで読み込む。スキルを参照するときは相対パスとトリガー（例：「main の CI がすべて緑のあと」）を書く。四半期ごとに分量を見直し、印刷でおよそ二枚を超えたら境界付きコンテキスト（iOS アプリ vs バックエンド）で分割し、頂点に索引ファイルを残す。

Git レビュー、タグ付け、ホスト展開の規律

AGENTS.md はモデル挙動に影響するため、ドメインエンジニアと自動化オーナーの双方がプルリクエストをレビューする。方針を大きく変えるなら Git でタグを打ち、展開ノートにミラーしてレンタル機が既知バージョンへ相関できるようにする。SSH で直接編集して即コミットしない——作業ツリーと origin/main の漂移は「アシスタントが古い文に従う」典型原因である。agents.json を触るなら可能な限り同一 diff に AGENTS.md を載せ、方針の動きを一度に見る。

ヘッドレス レンタル Mac：シェル、エディタ、シンボリックリンク

SSH セッションは bash や zsh で PATH が GUI と異なることが多い。AGENTS.md に仮定するプロファイルを書き、launchd と同じラッパーで検証してからツール呼び出しを任せる。モノレポのシンボリックリンクは許可ルート外に出たと誤認させる——許可リスト記事の解決規則と叙述を揃える。リモートエディタの自動保存プラグインは一時ファイルを生むことがあるので ignore パターンを書き、それを製品コードと見なさないようにする。

意思決定マトリクス：AGENTS.md を直すか、agents.json か、新スキルか

シグナル	AGENTS.md 寄り	agents.json 寄り	新スキル寄り
変更が叙述・教育中心	はい——ミッション、注意、リンク	いいえ——JSON に散文を詰めない	手順が長いときのみ
ツール allow/deny を変える	脚注で理由を書き、その後 JSON	はい——機械強制	補助テキストをスキルに置いてもよい
多段 shell オーケストレーション	短文からスキル パスへリンク	稀——JSON は宣言的のまま	はい——AGENTS.md の可読性維持
緊急ホットフィックス	インシデント後に文書更新	先にフィーチャフラグやルータ切替	ポストモーテムのアンカーをここへ

レンタル ビルダーへ AGENTS.md を導入する 9 ステップ

1. 2026-05-11 のワークスペース記事で許可ルートを確認し、prose を書く前に不一致を解消する。
2. フィーチャブランチで AGENTS.md を起草し、iOS・バックエンド・セキュリティ関係者に回す。
3. 各 agents.json プロファイルが読む節へマッピングし、本文から重複ツール表を削除する。
4. 十二ステップ超の手順はスキルへ抽出し、安定した相対パスでリンクする。
5. 本番と同じ Node メジャーでローカル検証（onboard 記事参照）。
6. main へマージし、追跡用に policy/agents-md-YYYYMMDD タグを打つ。
7. レンタル機で pull し、ハッシュが Git と一致するか確認する。
8. JSON または環境変数が変わったときだけゲートウェイ再起動；それ以外はビルドが示すファイル再読込に従う。
9. 前後のメトリクスを採る：拒否ツール試行、平均セッション長、人間上書き率。

FAQ

質問	実務回答（2026-05-15）
AGENTS.md に API キーを書くべきか	いいえ——金庫名や環境変数キーのみ。値は密封ファイルやキーチェーンへ。
多言語 AGENTS.md を維持できるか	方針が厳密に同期するなら可。そうでなければ canonical 言語を一つ選び、他はリンク翻訳に留める。
どのくらいの頻度で見直すか	少なくとも四半期ごと、および大きな Xcode か OpenClaw アップグレードのたび。SLO ダッシュボードの伴侣として扱う。

なぜ Mac mini M4 レンタルが AGENTS.md 反復に向くか

高速 NVMe とユニファイド メモリにより、複数のエージェント状態木、並列 Git チェックアウト、「Markdown＋スキル」の大きな束を同時に載せるコストが低く、本番トラフィックに触れる前にステージング リースで文書リハーサルがしやすい。地域とサイズは 料金 で比較し、ツール範囲を広げる前に SSH と任意 VNC ガイド をチームで読む。