2026-05-15 OpenClaw espace de travail AGENTS.md comme brief de dépôt sur Mac cloud Apple Silicon loué sans tête (HK / JP / KR / SG / US)

Lorsque OpenClaw peut lire tout un monorepo, le document à plus fort levier n’est pas seulement un autre réglage JSON : c’est un AGENTS.md discipliné à la racine Git, lisible par humains et modèles, qui décrit le « nominal ». Sur des Mac mini M4 loués à Hong Kong, Tokyo, Séoul, Singapour et aux États-Unis, le même hôte exécute souvent xcodebuild, des arbres de signature et un assistant qui modifie du Swift. Ce guide du 2026-05-15 place AGENTS.md dans la pile complète : il s’aligne sur les listes autorisées et garde-fous monorepo, complète la séparation multi-agents dans agents.json et évolue avec onboard, launchd et doctor—sans dupliquer ligne par ligne les tables d’outils machines.

Pourquoi un AGENTS.md au niveau dépôt malgré agents.json

agents.json encode identités, modèles et surfaces d’outils ; c’est le contrat que la passerelle doit parser de façon déterministe. AGENTS.md répond à d’autres questions : quel produit ce dépôt construit, quels répertoires sont sensibles, quelle commande de test fait foi, comment segmenter un rollback, qui alerter quand l’automatisation propose des edits risqués. Sur des builders loués partagés, cette narration rend l’intention visible dans un diff d’incident, au-delà des tableaux JSON. Gardez le texte lisible en moins de deux minutes à voix haute ; déplacez les longues procédures vers des compétences et listez ici chemins d’entrée et conditions de déclenchement.

Pile de politique : où se situe AGENTS.md par rapport aux listes et à agents.json

Du haut vers le bas : transport et canaux, routage passerelle, listes autorisées d’espace de travail, JSON d’exécution d’agent, compétences optionnelles, puis instructions de dépôt. AGENTS.md est proche du contrat social du dépôt—il ne remplace pas le refus par défaut du système de fichiers mais explique pourquoi les racines existent et le comportement attendu des assistants. Avec plusieurs agents sur un hôte, chaque profil lit le même dépôt : AGENTS.md reste neutre sur la persona tandis qu’agents.json restreint les outils.

Couche	Artefact principal	Propriétaire	AGENTS.md doit…
Garde système de fichiers	Listes autorisées	Plateforme / sécurité	Référencer les racines par chemin sans règles concurrentes
Politique d’exécution	agents.json	Responsables automatisation	Expliquer l’intention des profils et lier les chemins JSON dans Git
Profondeur procédurale	Compétences / runbooks	Équipes service	Indexer par titres stables sans coller de longs scripts shell
Contexte humain + modèle	AGENTS.md	Maintainers du dépôt	Énoncer mission, tests, rollback et contacts sur un ton neutre

Squelette recommandé d’AGENTS.md pour dépôts très OpenClaw

Utilisez des titres stables pour l’ancrage recherche humain et modèle. Ouvrez par la mission, puis listez explicitement les non-objectifs—actions nécessitant une validation humaine (déploiements prod, mutations du trousseau, suppression de DerivedData hors périmètre). Documentez les points d’entrée de test (xcodebuild test, choix SwiftPM, enveloppes lint) et les variables d’environnement indispensables aux shells non interactifs. Terminez par l’escalade : canal Slack, astreinte, commande pour capturer les logs passerelle sur la machine louée.

• Mission et périmètre — contexte produit, cadence de release, branches supportées.
• Carte des répertoires — artefacts générés, modèles de secrets, emplacement des checkouts CI.
• Vérification — jeu minimal de commandes prouvant la sûreté.
• Rollback — stratégie Git et caches hôte à purger.

Budget de jetons : AGENTS.md mince, compétences épaisses

De gros blobs Markdown rivalisent avec les extraits de code récupérés par les outils fichiers. Privilégiez paragraphes courts, tables de liens et ancres stables. Déplacez les chaînages longs (tagging release, notarize + stapling, rollout multi-région) vers des compétences chargées à la demande par la passerelle. Lorsque vous référencez une compétence, indiquez le chemin relatif et le déclencheur (« après CI verte sur main »). Revoyez la taille chaque trimestre ; au-delà d’environ deux pages imprimées, segmentez par contexte borné (app iOS vs services backend) avec un fichier index en tête.

Revue Git, étiquetage et discipline de déploiement hôte

Parce qu’AGENTS.md influence le comportement modèle, exigez une revue PR conjointe d’un ingénieur domaine et d’un propriétaire automatisation. Étiquetez Git lorsque la politique narrative change matériellement ; reflétez ces tags dans les notes de déploiement pour corréler les anomalies à une version connue du document. Évitez d’éditer AGENTS.md uniquement via SSH sans commit immédiat—la dérive entre arbre de travail et origin/main est une cause fréquente d’« assistant qui suit l’ancien texte ». Associez les changements agents.json au même diff quand c’est possible.

Réalités Mac loué sans tête : shells, éditeurs et liens symboliques

Les sessions SSH utilisent souvent bash ou zsh avec un PATH différent de l’interface graphique. Documentez le profil supposé dans AGENTS.md et vérifiez-le avec les mêmes scripts enveloppe que launchd avant de confier des appels d’outils. Les liens symboliques monorepo peuvent faire croire à une sortie hors racines autorisées ; alignez la prose sur les règles de résolution des articles de liste autorisée. Les plugins d’auto-sauvegarde d’éditeurs distants créent des fichiers temporaires—listez les motifs ignorés pour éviter qu’ils soient pris pour du code produit.

Matrice : modifier AGENTS.md, agents.json ou une nouvelle compétence

Signal	Privilégier AGENTS.md	Privilégier agents.json	Privilégier nouvelle compétence
Changement narratif ou pédagogique	Oui—mission, mises en garde, liens	Non—évitez la prose dans le JSON	Seulement si la procédure est longue
Changement des listes allow/deny d’outils	Note de motivation puis JSON	Oui—application machine	Texte d’aide possible dans la compétence
Chorégraphie shell multi-étapes	Lien court vers le chemin compétence	Rare—gardez le JSON déclaratif	Oui—préserve la lisibilité d’AGENTS.md
Correctif d’urgence	Mettre à jour après l’incident	D’abord drapeaux de fonctionnalité ou routage	Ancres de post-mortem ici

Neuf étapes pour introduire AGENTS.md sur un builder loué

1. Vérifiez les racines autorisées avec l’article espace de travail du 2026-05-11 avant d’écrire la prose.
2. Rédigez AGENTS.md sur une branche fonctionnelle ; faites circuler auprès iOS, backend et sécurité.
3. Mappez chaque profil agents.json vers les sections à lire ; retirez les tables d’outils dupliquées du corps.
4. Extrayez toute procédure de plus de douze étapes vers une compétence avec lien relatif stable.
5. Exécutez les vérifications locales avec la même majeure Node que la prod (voir article onboard).
6. Fusionnez vers main ; étiquettez policy/agents-md-AAAAMMJJ pour la traçabilité.
7. Sur l’hôte loué, tirez Git et vérifiez l’égalité des hachages.
8. Redémarrez les passerelles seulement si JSON ou variables d’environnement changent ; sinon suivez la sémantique de relecture fichier de votre build.
9. Capturez des métriques avant/après : tentatives d’outil refusées, durée moyenne de session, taux de substitution humaine.

FAQ

Question	Réponse pratique (2026-05-15)
Faut-il y mettre des clés API ?	Non—référencez coffre ou noms de variables ; stockez les valeurs dans des fichiers scellés ou le trousseau.
Plusieurs langues pour AGENTS.md ?	Seulement si chaque variante reste synchronisée sur la politique ; sinon une langue canonique et des liens traduits.
Fréquence de revue ?	Au minimum trimestriellement et après toute montée majeure Xcode ou OpenClaw ; traitez-le comme compagnon des tableaux de SLO.

Pourquoi la location de Mac mini M4 simplifie les itérations sur AGENTS.md

Le NVMe rapide et la mémoire unifiée permettent de garder plusieurs arbres d’état d’agent, des checkouts Git parallèles et de gros paquets Markdown+compétences simultanément—idéal pour répéter les changements documentaires sur une location de préproduction avant le trafic prod. Comparez les régions sur la page tarifs et faites lire les guides SSH et VNC optionnels avant d’élargir les outils.