🛠️ AGENTS.md 빌드 시스템¶
2026-05-17 v1 박제. 4개 워크스페이스
AGENTS.md를 partial + local에서 자동 합성하는 시스템.
한눈에 보기¶
~/.openclaw/shared/AGENTS.partial.*.md (5개)
+
~/.openclaw/workspace*/AGENTS.local.md (4개)
↓
~/.openclaw/scripts/build-agents-md.sh
↓
~/.openclaw/workspace*/AGENTS.md (4개, 자동 생성)
핵심 룰: 생성된 AGENTS.md는 직접 편집 ❌. 자동 헤더가 박힘:
1. 입력 — 5-Partial + Local¶
공통 partial (~/.openclaw/shared/)¶
| 파일 | 언어 | 다루는 것 |
|---|---|---|
AGENTS.partial.header.md |
자동 치환 변수 | agentId, 부서명, workspace 경로, 시간대 |
AGENTS.partial.principles.md |
한국어 | 추론·도가·비판·시크릿·호칭·파일명 |
AGENTS.partial.workflow.md |
영문 | Default Loop, Retrieval 룰, Action 분기표, 악마의 대변인 |
AGENTS.partial.routing.md |
한국어 | 에이전트 구조, 통신 도구, 응답 라우팅, 권한 위계 |
AGENTS.partial.safety.md |
한국어 | 외부 발송·데이터 변경·재무·고객·정본 불변 룰 (Don't+Do) |
부서별 local (~/.openclaw/workspace*/AGENTS.local.md)¶
| 워크스페이스 | 다루는 것 |
|---|---|
workspace/AGENTS.local.md (main) |
헌법 거버넌스, main 전용 룰, 큰 결정 트리거 |
workspace-content-marketing/AGENTS.local.md |
플레이스·견적·배포 룰 |
workspace-global-selling/AGENTS.local.md |
아마존·인플루언서·인증 룰 |
workspace-finance-ops/AGENTS.local.md |
정산·세금계산서·팝빌·쿠팡리워드 룰 |
2. 빌드 스크립트¶
위치: ~/.openclaw/scripts/build-agents-md.sh (167줄, bash)
사용법¶
# 빌드 실행 (4개 AGENTS.md 갱신)
~/.openclaw/scripts/build-agents-md.sh
# Drift 검사 (현재 AGENTS.md가 partial + local 기준과 일치하는지)
~/.openclaw/scripts/build-agents-md.sh --check
출력¶
빌드 성공 시 표준 출력에 4개 워크스페이스 + 크기 표시:
✅ workspace/AGENTS.md (10,643 chars)
✅ workspace-content-marketing/AGENTS.md (10,141 chars)
✅ workspace-global-selling/AGENTS.md (10,387 chars)
✅ workspace-finance-ops/AGENTS.md (10,168 chars)
--check 모드에서 drift 발견 시 비-0 종료 코드.
3. 언제 빌드해야 하나¶
| 변경 위치 | 영향 | 빌드 필요 |
|---|---|---|
shared/AGENTS.partial.*.md 수정 |
4개 워크스페이스 전체 | ✅ 필수 |
workspace/AGENTS.local.md 수정 |
main 워크스페이스만 | ✅ 필수 |
workspace-*/AGENTS.local.md 수정 |
해당 부서만 | ✅ 필수 |
MEMORY.md·SOUL.md·docs 수정 |
AGENTS.md와 무관 | ❌ 불필요 |
변경 → 빌드 사이클¶
4. 크기 한도¶
OpenClaw bootstrapMaxChars = 12,000 chars hard limit.
| 워크스페이스 | 현재 chars | 한도 대비 |
|---|---|---|
| main | 10,643 | 89% ⚠️ |
| content-marketing | 10,141 | 85% |
| global-selling | 10,387 | 87% |
| finance-ops | 10,168 | 85% |
전부 한도 내. 다이어트 룰 적용 시점이 가까워지는 중.
다이어트 룰¶
- 신규 룰 추가 시 → 기존 룰 삭제·축약·reference 이동 중 하나 강제
- 1회성 문제는
memory/logs/에 기록 (AGENTS 승격 ❌) - 승격 조건: 반복성 + 안정성 + 공통성 3조건 충족
5. 스킬 (수동 호출)¶
⚠️ 스킬은 자동 발동 ❌. 사용자 또는 AI 캐리가 수동으로 호출.
- 스킬 정의:
~/.openclaw/workspace/skills/agents-md-build/SKILL.md - 적용 범위: main 에이전트 전용 (부서 워크스페이스에서는 발동 ❌)
- 호출 트리거: partial 또는 local 변경 직후 AI 캐리 판단
안전망¶
빌드 1번 빠뜨려도 사고 ❌:
- 정본은 partial + local (이미 새 룰 박혀있음)
- 다음 세션 시작 시
--check로 drift 감지 가능 - AGENTS.md만 옛 버전 → 다음 빌드에서 즉시 sync
6. 트러블슈팅¶
| 증상 | 원인 | 처치 |
|---|---|---|
--check drift 발견 |
partial 변경 후 빌드 누락 | build-agents-md.sh 실행 |
| AGENTS.md가 12,000 초과 | partial이 너무 길어짐 | 다이어트 룰 적용 |
| 부서 local 변경이 main에 안 박힘 | 정상 (부서 격리) | 의도된 동작 |
| 자동 헤더 충돌 | AGENTS.md 직접 편집 | local 또는 partial에 옮기고 재빌드 |
7. 관련 문서¶
- 표준 v1:
memory/governance/agents-md-standard-v1.md - 빌드 스크립트:
~/.openclaw/scripts/build-agents-md.sh - 스킬:
~/.openclaw/workspace/skills/agents-md-build/SKILL.md - 거버넌스 개요: governance/index.md