한 사람이 8개의 AI 에이전트를 동시에 돌려 한 달에 6,600개의 커밋을 만들어낸다. 그 비밀은 코드가 아니라 215줄의 규칙 문서에 있다.

정도현 - 로보코 수석 컨설턴트

OpenClaw(구 Clawdbot)는 GitHub 31만+ 스타를 받은 오픈소스 프로젝트로, 한 명의 개발자가 여러 AI 코딩 에이전트를 병렬로 운용해 구축한 대표적인 바이브 코딩 사례다. 이전 글1에서 OpenClaw의 9가지 모범 사례를 다뤘다면, 이번에는 그 모범 사례의 원천인 AGENTS.md 파일 자체를 해부한다.

AGENTS.md는 단순한 README가 아니다. 이 문서는 AI 에이전트가 코드베이스에서 작업할 때 따라야 할 운영 계약(operational contract) 이다. Peter Steinberger는 이를 “조직의 상처가 축적된 흔적(organizational scar tissue)“이라고 불렀다. 무언가 잘못될 때마다 에이전트가 스스로 규칙을 추가해 왔기 때문이다. 지금부터 이 215줄짜리 문서에서 읽어낼 수 있는 생산성의 원칙들을 하나씩 풀어본다.

1. 에이전트의 인지 지도를 만들어라

AGENTS.md의 첫 번째 섹션은 Project Structure & Module Organization이다. 사람이 온보딩할 때 “이 코드는 어디에 있어?“가 첫 질문이듯, AI 에이전트에게도 코드베이스의 지도가 필요하다.

OpenClaw의 AGENTS.md는 이 지도를 놀랍도록 구체적으로 그린다.

  • 소스 코드 위치: CLI 배선은 src/cli, 명령어는 src/commands, 웹 프로바이더는 src/provider-web.ts, 인프라는 src/infra, 미디어 파이프라인은 src/media
  • 테스트 위치: *.test.ts로 소스와 같은 디렉토리에 배치
  • 빌드 산출물: dist/
  • 문서: docs/
  • 플러그인: extensions/* (워크스페이스 패키지)

여기서 주목할 점은 “플러그인"과 “extensions"의 용어 분리다. 문서, UI, 변경 로그에서는 “plugin"을 쓰고, 내부 디렉토리 경로에서는 extensions/*를 유지한다. 불필요한 전체 이름 변경(rename churn)을 피하면서도 외부 커뮤니케이션의 일관성을 확보하는 실용적 선택이다.

교훈: 에이전트가 코드를 수정하기 전에 “어디를 건드려야 하는지"를 정확히 알게 하라. 구조가 명확할수록 에이전트의 첫 시도 성공률이 올라간다.

2. 경계를 코드가 아닌 규칙으로 강제하라

OpenClaw AGENTS.md의 Coding Style & Naming Conventions 섹션에서 가장 인상적인 부분은 임포트 경계(import boundary) 규칙이다. 이 규칙들은 단순한 코딩 스타일이 아니라, 아키텍처를 보호하는 가드레일이다.

세 가지 핵심 규칙이 있다:

첫째, 확장(extension)은 공개 표면만 참조한다. Extension 프로덕션 코드는 openclaw/plugin-sdk/*와 로컬 api.ts/runtime-api.ts 배럴만을 공개 표면으로 취급해야 한다. 코어 src/**나 다른 extension의 src/**를 직접 임포트하는 것은 금지다.

둘째, 자기 자신을 외부 경로로 임포트하지 않는다. Extension 패키지 내부에서 openclaw/plugin-sdk/<extension>으로 자기 자신을 임포트하면 안 된다. 내부 라우팅은 ./api.ts 같은 로컬 배럴을 통해야 하며, SDK 경로는 외부 계약으로만 유지한다.

셋째, 패키지 루트 밖으로 상대 경로를 쓰지 않는다. extensions/<id>/** 안에서 해당 패키지 루트 바깥으로 빠지는 상대 임포트를 금지한다.

이 세 규칙이 왜 중요한가? AI 에이전트는 “빠르게 동작하는 코드"를 만드는 데 탁월하지만, 아키텍처 경계를 인식하지 못한다. ../../../src/internal/로 직접 뻗는 임포트가 당장은 컴파일되지만, 모듈 경계를 무너뜨리고 나중에 리팩터링을 불가능하게 만든다. AGENTS.md는 에이전트가 이런 지름길을 택하지 못하도록 명시적으로 차단한다.

교훈: AI 에이전트는 아키텍처를 이해하지 못한다. 경계를 설명이 아닌 규칙으로 선언하라. “이렇게 하면 좋겠다"가 아니라 “이것은 금지다"여야 한다.

3. 빌드 게이트를 절대 규칙으로 만들어라

AGENTS.md의 Build, Test, and Development Commands 섹션은 에이전트가 코드를 변경한 후 무엇을 해야 하는지를 매우 명확하게 정의한다. 핵심은 하드 게이트(hard gate) 와 소프트 게이트 의 구분이다.

하드 게이트(절대 규칙):

  • 빌드 산출물, 패키징, 모듈 경계, 퍼블리시 표면에 영향을 줄 수 있는 변경은 반드시 pnpm build를 실행하고 통과해야 main에 푸시할 수 있다
  • 포맷, 린트, 타입, 빌드, 필수 테스트 체크가 실패하는 상태로 커밋하거나 푸시하지 않는다

소프트 게이트(맥락적 판단):

  • 좁은 범위의 변경에는 해당 동작을 직접 검증하는 좁은 범위의 테스트를 선호한다
  • main에 푸시할 때의 기본 기준은 pnpm check와 pnpm test

특히 눈에 띄는 것은 기존 실패와의 구분 이다. 변경과 무관한 실패가 이미 origin/main에 존재한다면, 그 사실을 명시하고 자신이 실행한 범위 테스트를 보고하라고 한다. 하지만 “관련 없는 실패니까 무시해도 된다"는 식의 면죄부를 주지는 않는다. 이 미묘한 균형이 중요하다.

또 하나 인상적인 규칙이 있다. 의존성이 누락된 경우(예: vitest not found) 패키지 매니저 설치를 한 번 실행한 뒤 명령을 재시도하되, 재시도도 실패하면 명령어와 첫 번째 오류 메시지를 보고하라는 것이다. 에이전트에게 자가 복구 능력을 주되, 무한 루프에 빠지지 않게 한 번으로 제한한다.

교훈: “테스트를 돌려라"는 모호하다. 어떤 테스트를, 언제, 어떤 기준으로 돌려야 하는지를 명시하라. 하드 게이트와 소프트 게이트를 구분하면 에이전트가 불필요한 작업을 줄이면서도 핵심 품질은 놓치지 않는다.

4. 멀티 에이전트 안전 규칙이 핵심이다

OpenClaw의 가장 독특한 생산성 비밀은 Collaboration / Safety Notes 섹션의 멀티 에이전트 안전(multi-agent safety) 규칙이다. Steinberger는 3~8개의 에이전트를 동시에 같은 저장소에서 실행한다. 이것이 가능한 이유는 에이전트 간 충돌을 방지하는 명확한 규칙 때문이다.

다섯 가지 핵심 규칙이 이를 지탱한다:

  1. git stash 금지: 명시적으로 요청받지 않는 한 git stash를 생성, 적용, 삭제하지 않는다. git pull --rebase --autostash도 포함된다. 다른 에이전트의 진행 중인 작업을 건드리지 않기 위해서다.
  2. 브랜치 전환 금지: 명시적으로 요청받지 않는 한 브랜치를 바꾸지 않는다.
  3. 워크트리 조작 금지: git worktree를 생성, 삭제, 수정하지 않는다.
  4. 커밋 범위 제한: “push"는 git pull --rebase로 최신 변경을 통합할 수 있지만 다른 에이전트의 작업을 버리면 안 된다. “commit"은 자기 변경만, “commit all"은 그룹별 청크로 커밋한다.
  5. 미인식 파일 무시: 인식하지 못하는 파일이 보여도 계속 진행한다. 자기 변경에만 집중하고 그것만 커밋한다.

이 규칙들이 없다면 어떻게 될까? 에이전트 A가 작업 중인 파일을 에이전트 B가 stash하거나, 에이전트 C가 브랜치를 전환해 D의 컨텍스트를 날려버릴 수 있다. 이 다섯 줄의 규칙이 8개 에이전트의 병렬 작업을 가능하게 만드는 핵심 인프라다.

마지막 규칙도 실용적이다. “보고서는 자기 변경에 집중하고, 진짜로 막히지 않는 한 가드레일 면책 조항을 붙이지 말라. 여러 에이전트가 같은 파일을 건드린 경우 안전하면 계속 진행하고, 관련이 있을 때만 ‘다른 파일이 존재한다’고 짧게 언급하라.” 이것은 에이전트가 방어적으로 동작하는 것을 방지한다.

교훈: 멀티 에이전트 환경의 생산성은 “더 많은 에이전트"가 아니라 “충돌 없는 에이전트"에서 나온다. git 상태를 공유 자원으로 보고, 경쟁 조건(race condition)을 규칙으로 차단하라.

5. 코딩 스타일을 취향이 아닌 안전장치로 정의하라

AGENTS.md의 Coding Style & Naming Conventions 섹션은 일반적인 스타일 가이드와 성격이 다르다. “탭 vs 스페이스” 같은 취향이 아니라, 에이전트가 만들어내는 구조적 결함을 차단하는 안전장치다.

몇 가지 핵심 규칙을 보자:

@ts-nocheck 절대 금지, no-explicit-any 비활성화 금지. AI 에이전트는 타입 오류를 만나면 근본 원인을 고치는 대신 @ts-nocheck나 any로 회피하려는 경향이 있다. 이 규칙은 그 지름길을 명시적으로 차단한다.

동적 임포트 가드레일. 같은 모듈에 대해 await import("x")와 정적 import ... from "x"를 동시에 사용하지 않는다. 게으른 로딩이 필요하면 전용 *.runtime.ts 경계를 만들어야 한다. 리팩터링 후에는 pnpm build를 실행해 [INEFFECTIVE_DYNAMIC_IMPORT] 경고를 확인해야 한다.

프로토타입 뮤테이션 금지. applyPrototypeMixins나 Object.defineProperty로 프로토타입을 변경하는 패턴은 금지하고, 명시적 상속/합성을 사용하게 한다. TypeScript가 타입 체크를 할 수 있게 유지하기 위해서다.

파일 크기 가이드라인. 약 700줄 이하를 목표로 하되, 하드 제한이 아니라 가이드라인으로 둔다. 명확성이나 테스트 용이성이 개선될 때 분리하라고 한다.

이 규칙들의 공통점은 AI 에이전트의 특성을 정확히 이해하고 있다는 것이다. 에이전트는 당장 동작하는 코드를 만드는 데 최적화되어 있기 때문에, 장기적 유지보수성을 희생하는 패턴을 선택하기 쉽다. AGENTS.md는 그 경향을 정확히 짚어서 차단한다.

교훈: AI 에이전트를 위한 코딩 스타일은 “이렇게 쓰면 예쁘다"가 아니라 “이것은 시간 폭탄이니 하지 마라"여야 한다. 에이전트가 만들어내는 전형적 결함을 파악하고, 그것을 규칙으로 막아라.

6. 스킬 시스템으로 반복 작업을 캡슐화하라

AGENTS.md의 Release / Advisory Workflows 섹션은 세 가지 전문 스킬(skill)을 참조한다:

  • $openclaw-release-maintainer: 릴리스 이름 지정, 버전 조율, 릴리스 인증, 변경 로그 기반 릴리스 노트 워크플로
  • $openclaw-pr-maintainer: PR 분류, 리뷰, 클로즈, 검색, 랜딩 워크플로
  • $openclaw-ghsa-maintainer: GHSA(GitHub Security Advisory) 점검, 패치/퍼블리시 플로, 프라이빗 포크 확인

스킬은 .agents/skills/ 디렉토리에 독립 파일로 존재하며, AGENTS.md에서는 경로만 참조한다. 이 분리가 중요하다. AGENTS.md는 “무엇을 해야 하는지"의 원칙을, 스킬은 “구체적으로 어떻게 하는지"의 절차를 담당한다.

특히 릴리스와 퍼블리시는 “스킬을 사용하더라도 명시적 승인이 필요한 작업"으로 명시되어 있다. 자동화의 범위와 인간 승인의 경계를 명확히 그은 것이다.

교훈: 반복되는 복잡한 워크플로는 AGENTS.md 본문에 장황하게 쓰지 말고 별도 스킬로 분리하라. AGENTS.md는 원칙과 참조만 담고, 절차적 세부사항은 스킬에 위임하라.

7. 보안과 릴리스의 마지막 방어선

AGENTS.md의 Security & Configuration Tips와 Testing Guidelines 섹션은 보안과 릴리스에 관한 절대 규칙을 담고 있다.

  • 실제 전화번호, 영상, 라이브 설정값을 커밋하거나 퍼블리시하지 않는다
  • CODEOWNERS 규칙이 적용된 파일은 소유자가 명시적으로 요청하지 않는 한 수정하지 않는다
  • 베이스라인, 인벤토리, 스냅샷, 예상 실패 파일을 체크 통과를 위해 수정하지 않는다
  • 버전 번호는 운영자의 명시적 동의 없이 변경하지 않는다
  • npm publish/release 단계를 실행하기 전에 항상 허가를 받는다
  • 5개 이상의 PR을 일괄 닫을 때는 사용자에게 정확한 수와 범위를 확인받는다

이 규칙들의 공통점은 비가역적 행동에 대한 인간 승인 의무화다. 에이전트가 아무리 빠르게 움직여도, 돌이킬 수 없는 행동 앞에서는 반드시 멈추게 한다. 생산성과 안전성은 상충하지 않는다. 올바른 지점에서만 브레이크를 밟으면 나머지 구간에서는 더 빠르게 달릴 수 있다.

교훈: “에이전트가 하면 안 되는 것"의 목록은 “해야 하는 것"의 목록만큼 중요하다. 특히 비가역적 행동(릴리스, 삭제, 일괄 변경)은 명시적 승인을 절대 규칙으로 만들어라.

종합: AGENTS.md의 설계 원칙

OpenClaw의 AGENTS.md를 관통하는 설계 원칙을 정리하면 다음과 같다.

원칙 적용
인지 지도 제공 프로젝트 구조, 용어 규칙, 파일 위치를 선언적으로 명시
경계의 명시적 선언 임포트 경계, 패키지 경계를 “금지” 형태로 정의
계층적 게이트 하드 게이트(절대)와 소프트 게이트(맥락적)를 분리
병렬 안전 git 상태를 공유 자원으로 보고 경쟁 조건을 규칙으로 차단
결함 패턴 차단 AI가 만들어내는 전형적 지름길을 선제적으로 금지
워크플로 캡슐화 반복 절차는 스킬로 분리하고 AGENTS.md에서 참조만
비가역 행동의 승인 의무화 릴리스, 삭제, 일괄 변경은 반드시 인간 확인

이 원칙들은 OpenClaw에만 해당하는 것이 아니다. AI 에이전트를 활용하는 모든 프로젝트에 적용 가능한 보편적 설계 패턴이다.

당신의 AGENTS.md를 시작하려면

지금 당장 215줄짜리 문서를 만들 필요는 없다. OpenClaw의 AGENTS.md도 처음부터 이렇게 크지 않았다. 무언가 잘못될 때마다 한 줄씩 추가되어 온 것이다. 다음 네 가지부터 시작하면 된다.

  1. 프로젝트 구조: 소스, 테스트, 빌드 산출물, 문서의 위치
  2. 빌드/테스트 명령어: 정확한 명령어와 통과 기준
  3. 금지 목록: 에이전트가 절대 하면 안 되는 행동 (파일 수정 제한, 위험한 패턴, 비가역적 명령)
  4. 커밋 규칙: 커밋 메시지 형식, 스코프 제한, 푸시 전 체크

이 네 가지만 있어도 에이전트의 첫 번째 실수를 절반으로 줄일 수 있다. 나머지는 OpenClaw처럼 실패에서 배우며 한 줄씩 추가하면 된다.

  1. OpenClaw: 세계 최대 바이브 코딩 프로젝트에서 배우는 9가지 모범 사례 ↩︎