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보다 리뷰하기 쉽다. 소리 내어 읽었을 때 약 2분 안에 끝나는 길이를 유지하고, 긴 절차는 스킬 번들로 옮기며 여기서는 진입 경로와 발동 조건만 밝힌다.

정책 스택: AGENTS.md는 허용 목록과 agents.json 사이 어디인가

위에서 아래로 전송·채널, 게이트웨이 라우팅, 워크스페이스 허용 목록, 에이전트 런타임 JSON, 선택적 스킬, 마지막으로 저장소 안내.AGENTS.md는 저장소의 사회적 계약에 가장 가깝다—기본 거부 파일 정책을 덮어쓰지 않되, 루트가 존재하는 이유와 어시스턴트가 그 안에서 기대되는 행동을 설명한다. 여러 에이전트가 한 호스트를 공유해도 같은 저장소를 읽으므로 AGENTS.md는 페르소나 중립을 유지하고 도구 축소는 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는 모델 행동에 영향을 주므로 도메인 엔지니어와 자동화 오너가 모두 PR을 검토한다. 정책을 크게 바꾸면 Git 태그를 달고 릴리스 노트에 미러링해 임대기가 알려진 문서 버전에 상관할 수 있게 한다. SSH에서만 직접 고치고 즉시 커밋하지 않는다—작업 트리와 origin/main의 드리프트는 “어시스턴트가 옛 문구를 따른다”의 흔한 원인이다. agents.json을 만지면 가능한 한 같은 diff에 AGENTS.md를 실어 정책 움직임을 한 번에 본다.

헤드리스 임대 Mac: 셸, 에디터, 심볼릭 링크

SSH 세션은 bash나 zsh에서 PATH가 GUI와 다를 수 있다. AGENTS.md에 가정하는 프로필을 적고 launchd와 동일한 래퍼로 검증한 뒤 도구 호출을 맡긴다. 모노레포의 심볼릭 링크는 허용 루트 밖으로 나간 것으로 오인시킬 수 있다—허용 목록 글의 해석 규칙과 서술을 맞춘다. 원격 에디터 자동 저장 플러그인은 임시 파일을 만들 수 있으므로 ignore 패턴을 적어 제품 코드로 오인하지 않게 한다.

의사결정 표: AGENTS.md vs agents.json vs 새 스킬

신호	AGENTS.md 쪽	agents.json 쪽	새 스킬 쪽
변경이 서술·교육 중심	예—미션, 주의, 링크	아니오—JSON에 산문을 채우지 않는다	절차가 길 때만
도구 허용/거부를 바꿈	각주로 이유를 쓰고 이후 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 가이드를 팀이 읽게 한다.