Add OpenClaw 5-layer gatekeeping architecture blog post

Analyze OpenClaw's automated quality gates: pre-commit hooks,
pnpm check pipeline, CI smart routing with 15 parallel jobs,
PR lifecycle automation (auto-labeling, noise filtering, stale
management, evidence-based templates), and release gates with
CODEOWNERS and environment approvals.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: serithemage

content/posts/openclaw-gatekeeping-architecture.md

@@ -0,0 +1,271 @@
+---
+title: "OpenClaw의 5계층 게이트키핑: AI 에이전트 시대의 품질 관리"
+date: 2026-03-27T10:00:00+09:00
+draft: false
+toc: false
+images:
+tags:
+  - vibe-coding
+  - agentic-dev
+  - openclaw
+  - gatekeeping
+  - ci-cd
+---
+
+> 31만 스타 프로젝트에 쏟아지는 수천 건의 PR과 8개 AI 에이전트의 병렬 커밋. 이 혼돈 속에서 품질이 무너지지 않는 비결은 5계층의 자동화된 게이트키핑에 있다.
+
+{{< figure src="/posts/images/Dohyun.png" title="정도현 - 로보코 수석 컨설턴트" style=".author-image">}}
+
+---
+
+이전 글에서 OpenClaw의 [AGENTS.md가 담고 있는 생산성의 원칙](/posts/openclaw-agents-md-productivity-secrets/)을 분석했다. 그 글의 핵심은 "규칙을 쓰는 것"이었다. 하지만 규칙을 쓰는 것과 규칙을 **강제하는 것**은 완전히 다른 문제다.
+
+OpenClaw는 GitHub에서 가장 많은 스타를 받은 저장소(31만+)이자, 바이브 코딩의 대표 사례다.[^1] 이 프로젝트는 두 가지 극단적 압력을 동시에 받는다. 하나는 메인테이너 Peter Steinberger가 3~8개의 AI 에이전트를 동시에 돌리며 쏟아내는 **내부 변경**이고, 다른 하나는 전 세계 컨트리뷰터가 AI 보조로 만들어 제출하는 **수천 건의 외부 PR**이다.
+
+AGENTS.md에 "이것을 하지 마라"고 쓰는 것은 소프트 가드레일이다. AI 에이전트는 대개 따르지만, 항상 따르지는 않는다. 외부 컨트리뷰터는 그 규칙의 존재조차 모를 수 있다. 그래서 OpenClaw는 규칙 위에 **5계층의 자동화된 강제 메커니즘**을 쌓았다. 이 글은 그 메커니즘을 해부한다.
+
+---
+
+## 1계층: 커밋 전에 잡는다 — 로컬 프리커밋
+
+OpenClaw의 첫 번째 방어선은 코드가 저장소에 도달하기도 전에 작동한다. [`git-hooks/pre-commit`](https://github.com/openclaw/openclaw/tree/main/git-hooks)은 `package.json`의 `prepare` 스크립트를 통해 자동 활성화되며, 커밋할 때마다 실행된다.
+
+동작 순서가 흥미롭다:
+
+1. 스테이지된 파일을 타입별로 필터링
+2. **oxlint** `--type-aware --fix` — 린트 오류를 **자동 수정**
+3. **oxfmt** `--write` — 포매팅을 **자동 수정**
+4. 수정된 파일을 다시 스테이징
+5. `pnpm check` — 전체 품질 게이트 실행
+
+핵심 설계는 **자동 수정과 차단의 분리**다. 포맷이나 린트 오류처럼 기계적으로 고칠 수 있는 문제는 훅이 알아서 고치고 통과시킨다. 하지만 타입 오류나 아키텍처 경계 위반처럼 판단이 필요한 문제는 커밋 자체를 차단한다. 이 구분이 없으면 에이전트는 사소한 포맷 오류 때문에 멈추거나, 구조적 결함을 그냥 통과시키거나, 둘 중 하나가 된다.
+
+여기에 더해 [`.pre-commit-config.yaml`](https://github.com/openclaw/openclaw/blob/main/.pre-commit-config.yaml)은 CI의 `security-fast` 잡에서도 실행되는 17개의 보안/품질 훅을 정의한다. `detect-private-key`와 `detect-secrets`로 시크릿 유출을 차단하고, `zizmor`로 GitHub Actions 워크플로의 보안을 감사하며, `pnpm-audit-prod`로 프로덕션 의존성의 알려진 취약점을 검사한다.
+
+---
+
+## 2계층: 하나의 명령어로 10가지를 검증한다 — `pnpm check`
+
+`pnpm check`는 로컬 훅과 CI 모두에서 실행되는 **단일 품질 게이트**다. 하나의 명령어 뒤에 10개 이상의 체크가 체이닝되어 있다.
+
+```
+pnpm check =
+  check:no-conflict-markers          # 머지 충돌 마커 없음
+  check:host-env-policy:swift         # Swift 호스트 환경 보안 정책
+  check:base-config-schema            # 설정 스키마 드리프트 체크
+  check:bundled-plugin-metadata       # 플러그인 메타데이터 일관성
+  check:bundled-provider-auth-env-vars # 프로바이더 인증 환경변수 일관성
+  format:check (oxfmt)                # 포매팅 검증
+  tsgo                                # TypeScript 네이티브 타입 체킹
+  plugin-sdk:check-exports            # 플러그인 SDK 익스포트 일관성
+  lint (oxlint --type-aware)          # 타입 인식 린팅
+  + ~15개 커스텀 아키텍처 경계 린트 스크립트
+```
+
+여기서 가장 주목할 부분은 마지막 줄이다. 일반적인 린터는 "사용하지 않는 변수"나 "누락된 세미콜론" 같은 코드 수준 문제를 잡는다. 하지만 OpenClaw의 커스텀 경계 가드 스크립트는 **아키텍처 수준 위반**을 잡는다. Extension이 코어 `src/**`를 직접 임포트하거나, 플러그인 SDK의 내부 경로를 참조하거나, 패키지 루트 밖으로 상대 경로를 뻗는 것을 감지한다.
+
+이것은 [이전 글에서 분석한 AGENTS.md의 임포트 경계 규칙](/posts/openclaw-agents-md-productivity-secrets/#2-경계를-코드가-아닌-규칙으로-강제하라)이 코드로 구현된 것이다. 규칙 문서에 "하지 마라"고 쓴 것을 CI가 실제로 검증하고 차단한다. **규칙과 검증의 이중 장벽**이다.
+
+---
+
+## 3계층: 15개 병렬 잡이 모든 변경을 검사한다 — CI 워크플로
+
+OpenClaw의 [`ci.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/ci.yml)은 PR과 main 푸시에서 실행되는 메인 게이트키퍼다. ~15개의 병렬 잡으로 구성되며, Draft PR은 건너뛴다.
+
+### 스마트 라우팅: 속도와 철저함의 양립
+
+모든 변경에 모든 테스트를 돌리면 철저하지만 느리다. 관련 테스트만 돌리면 빠르지만 놓칠 수 있다. OpenClaw는 **preflight 잡**으로 이 딜레마를 해결한다.
+
+preflight 잡은 변경된 파일의 스코프를 감지해 CI 매니페스트를 생성한다. 문서만 변경했다면 문서 체크만, Swift 파일을 건드렸다면 macOS 빌드+테스트를 추가하고, 특정 Extension만 변경했다면 해당 Extension 테스트만 실행한다. 이 스마트 라우팅이 "느리지만 철저한" CI와 "빠르지만 불완전한" CI 사이의 균형을 만든다.
+
+### CI 잡 전체 구조
+
+| 카테고리 | 잡 | 체크 내용 |
+|---------|-----|---------|
+| **보안** | security-fast | private key 감지, Actions 보안 감사, 의존성 감사 |
+| **품질** | check | pnpm check 전체 + strict smoke build |
+| **아키텍처** | check-additional | 15개+ 경계 가드, 스키마 드리프트, SDK API 베이스라인 |
+| **빌드** | build-artifacts | pnpm build + UI 빌드 |
+| **테스트 (Linux)** | checks (샤딩) | vitest 유닛 테스트, 채널 테스트, Node 22 호환 |
+| **테스트 (Windows)** | checks-windows (샤딩) | 전체 테스트 스위트 |
+| **테스트 (macOS)** | macos-node (샤딩) | 전체 테스트 스위트 |
+| **Extension** | checks-fast, extension-fast | 컨트랙트 테스트, 변경 Extension 타겟 테스트 |
+| **네이티브 앱** | macos-swift, android | Swift/Kotlin 빌드+테스트+린트 |
+| **문서** | check-docs | 포매팅, 링크 감사, i18n 용어집 |
+| **스모크** | build-smoke | CLI --help/--version, 시작 메모리 체크 |
+| **릴리스** | release-check (main만) | 릴리스 콘텐츠 검증 |
+
+특히 인상적인 것은 [`check-additional`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/ci.yml) 잡의 아키텍처 경계 가드다. 플러그인→Extension 임포트 위반, Extension SDK 내부 경로 참조, `raw window.open` 사용, 게이트웨이 watch 회귀 등을 커스텀 스크립트로 감지한다. 일반적인 CI 파이프라인에서는 볼 수 없는, **바이브 코딩 환경에 특화된 가드레일**이다.
+
+---
+
+## 4계층: 수천 건의 PR을 사람 없이 분류한다 — PR 수명주기 자동화
+
+31만 스타 프로젝트에는 수천 건의 이슈와 PR이 쏟아진다. 메인테이너가 하나하나 분류하는 것은 불가능하다. OpenClaw는 세 가지 자동화 워크플로로 이 문제를 해결한다.
+
+### 자동 라벨링: 변경 파일이 곧 라벨이다
+
+[`labeler.yml`](https://github.com/openclaw/openclaw/blob/main/.github/labeler.yml) 워크플로는 PR이 열리면 변경된 파일 경로를 분석해 라벨을 자동 부여한다. 21개 채널 라벨(`channel: discord`, `channel: telegram` 등), 4개 앱 라벨(`app: ios`, `app: android` 등), 8개 영역 라벨(`gateway`, `agents`, `security` 등), 30개 이상의 Extension 라벨이 정의되어 있다.
+
+거기에 **PR 크기 라벨**(XS/S/M/L/XL)을 줄 수 기반으로 자동 부여하고, **메인테이너 라벨**을 팀 멤버십으로 판별하며, **beta-blocker 라벨**을 PR 제목에서 자동 감지한다. 이 라벨들이 다음 단계의 자동 응답 시스템을 트리거한다.
+
+### 자동 응답: 노이즈를 자동으로 걸러낸다
+
+[`auto-response.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/auto-response.yml)은 라벨 기반으로 PR과 이슈를 자동 처리한다. 이 워크플로의 규칙들은 실제 운영 경험에서 축적된 것이다.
+
+**스팸/노이즈 차단**:
+- `r: spam` 또는 `r: moltbook` 라벨 → 자동 닫기 + 잠금
+- `dirty` 라벨 또는 라벨 20개 초과 PR → "noisy PR" 메시지와 함께 닫기
+
+**커뮤니티 행동 제한**:
+- 비메인테이너의 오픈 PR이 **10개를 초과**하면 → `r: too-many-prs` 라벨 부여 후 자동 닫기
+- 이슈/PR에서 메인테이너 **3명 이상을 멘션**하면 → 스팸 핑 경고 메시지
+
+**적절한 채널 안내**:
+- `r: skill` → 스킬 관련 질문은 ClawHub으로 안내 후 닫기
+- `r: support` → 지원 요청은 Discord로 안내 후 닫기
+- `r: no-ci-pr` → CI 설정만 변경하는 PR 거절
+
+**인당 PR 10개 상한**은 특히 바이브 코딩 시대에 중요하다. AI 도구로 PR을 대량 생산하기 쉬워진 환경에서, 한 사람이 리뷰 큐를 독점하는 것을 방지한다. CONTRIBUTING.md도 이를 명시한다: *"Keep PRs focused (one thing per PR; do not mix unrelated concerns)"*[^2]
+
+### 수명 관리: 방치된 PR은 자동 정리한다
+
+[`stale.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/stale.yml)은 매일 실행되며 방치된 이슈와 PR을 정리한다. 이슈는 7일 후 stale 표시 → 5일 후 닫기, PR은 5일 후 stale → 3일 후 닫기. 닫힌 이슈는 48시간 후 잠금. `enhancement`, `maintainer`, `pinned`, `security` 라벨이 붙은 항목은 면제된다.
+
+PR의 수명이 이슈보다 짧은 것이 눈에 띈다(5+3일 vs 7+5일). 코드 변경은 시간이 지날수록 컨텍스트와 멀어지고 충돌 가능성이 커지기 때문이다.
+
+### PR 템플릿: 증거를 구조적으로 요구한다
+
+OpenClaw의 [PR 템플릿](https://github.com/openclaw/openclaw/blob/main/.github/pull_request_template.md)은 일반적인 "무엇을 했는가" 수준을 넘어서 **증거 기반 리뷰**를 강제한다.
+
+필수 섹션 중 특히 주목할 부분:
+
+- **What did NOT change (scope boundary)**: 변경하지 않은 범위를 명시적으로 선언. AI 에이전트가 만든 변경은 스코프가 넓어지기 쉬운데, 의도적 경계를 선언하게 해서 리뷰어가 스코프 크리프를 감지할 수 있게 한다.
+- **Security Impact**: 권한, 시크릿, 네트워크, 도구 실행, 데이터 접근 변경 여부를 **각각 Yes/No로 체크**. "보안에 영향이 있나요?"라는 모호한 질문 대신, 구체적 표면을 하나씩 점검하게 한다.
+- **Evidence**: 실패→성공 테스트, 트레이스/로그, 스크린샷 중 **최소 1개** 첨부 필수.
+- **Human Verification**: 검증한 시나리오, 엣지 케이스, 그리고 **검증하지 않은 것**을 명시.
+
+마지막 항목이 특히 중요하다. "무엇을 테스트했는가"만 물으면 PR 작성자는 성공한 케이스만 나열한다. "무엇을 테스트하지 않았는가"를 물으면 리뷰어가 위험 영역을 즉시 파악할 수 있다.
+
+---
+
+## 5계층: 되돌릴 수 없는 행동 앞에서 멈춘다 — 릴리스 게이트
+
+CI는 완전 자동이지만, 릴리스는 절대 자동이 아니다. OpenClaw의 릴리스 파이프라인은 **수동 트리거 + 환경 승인 + 다단계 검증**으로 구성된다.
+
+### NPM 릴리스: 19단계 시퀀스
+
+[`openclaw-npm-release.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/openclaw-npm-release.yml)은 `workflow_dispatch`로만 트리거된다. 자동 릴리스는 없다. 실행되면 다음 검증을 순서대로 거친다:
+
+1. 태그 포맷 검증
+2. `pnpm check` + `pnpm build` + `pnpm release:check`
+3. npm 버전 유일성 확인
+4. **`npm-release` 환경 승인** → `@openclaw/openclaw-release-managers` 팀원의 명시적 승인 필수
+5. main 브랜치에서만 실행 강제
+6. 이후 19단계 시퀀스: 태그 생성 → npm preflight → mac preflight (공개+비공개) → 실제 퍼블리시 → 에셋 검증 → appcast 업데이트
+
+### CODEOWNERS: 보안 표면을 물리적으로 잠근다
+
+[`CODEOWNERS`](https://github.com/openclaw/openclaw/blob/main/.github/CODEOWNERS)는 GitHub가 강제하는 하드 가드레일이다. AGENTS.md의 "보안 파일을 건드리지 마라"가 소프트 가드레일이라면, CODEOWNERS는 해당 팀의 리뷰 승인 없이는 **머지 자체가 불가능**하게 만든다.
+
+**`@openclaw/secops`** 가 보호하는 표면:
+- 보안 코드: `src/security/`, `src/secrets/`, 게이트웨이 인증/시크릿, 에이전트 샌드박스
+- 보안 인프라: dependabot, CodeQL, `SECURITY.md`
+- 보안 문서: 인증, 샌드박싱, 시크릿 관련 문서 전체
+
+**`@openclaw/openclaw-release-managers`** 가 보호하는 표면:
+- 릴리스 워크플로, 퍼블리시 스크립트, 릴리스 문서
+
+CODEOWNERS 파일 자체는 `@steipete`(창시자)만 수정할 수 있다. 게이트키퍼를 보호하는 게이트키퍼다.
+
+### AI 에이전트용 스킬 게이트
+
+릴리스와 PR 관리를 위한 AI 에이전트 스킬에도 게이트가 있다.
+
+[`$openclaw-pr-maintainer`](https://github.com/openclaw/openclaw/tree/main/.agents/skills/openclaw-pr-maintainer) 스킬은 버그 수정 PR에 대해 **증거 기준**을 강제한다. 이슈 텍스트나 AI의 추론만으로는 머지할 수 없다. 증상 증거, 검증된 근본 원인(파일/라인 수준), 관련 코드 경로 수정, 회귀 테스트가 필요하다. 일괄 닫기/재오픈이 5건을 초과하면 반드시 사용자 확인을 받아야 한다.
+
+[`$openclaw-release-maintainer`](https://github.com/openclaw/openclaw/tree/main/.agents/skills/openclaw-release-maintainer) 스킬은 버전 번호 변경과 npm publish 모두 **매 단계마다 운영자 승인**을 요구한다. 스킬이 자동화를 돕지만, 비가역적 행동은 여전히 인간이 최종 결정한다.
+
+---
+
+## 5계층이 만드는 방어 깊이
+
+이 5계층을 하나의 그림으로 보면, 코드가 프로덕션에 도달하기까지 거치는 **방어 깊이(defense in depth)** 가 드러난다.
+
+```
+[개발자/에이전트]
+       ↓
+  1계층: 프리커밋 ─── 포맷/린트 자동수정, 타입/경계 위반 차단
+       ↓
+  2계층: pnpm check ─ 10+ 체크 체이닝, 15+ 아키텍처 경계 가드
+       ↓
+  3계층: CI ────────── 15개 병렬 잡, 크로스 플랫폼, 보안 스캔
+       ↓
+  4계층: PR 자동화 ── 라벨 분류, 노이즈 필터, 증거 기반 템플릿, stale 정리
+       ↓
+  5계층: 릴리스 ───── 수동 트리거, 환경 승인, CODEOWNERS, 19단계 검증
+       ↓
+  [프로덕션]
+```
+
+각 계층은 독립적이다. 프리커밋이 실패해도 CI가 잡고, CI를 우회해도 PR 리뷰가 걸리고, PR이 통과해도 릴리스 게이트가 막는다. 하나의 계층이 뚫려도 다음 계층이 방어한다.
+
+---
+
+## 설계 원칙 7가지
+
+OpenClaw의 게이트키핑에서 추출한 설계 원칙을 정리한다.
+
+### 1. 자동 수정과 차단을 분리하라
+
+포맷/린트 오류는 자동 수정, 타입/경계 위반은 하드 차단. 에이전트의 플로를 불필요하게 끊지 않으면서도 구조적 결함은 통과시키지 않는다.
+
+### 2. 스마트 라우팅으로 속도를 유지하라
+
+모든 변경에 모든 테스트를 돌리지 않는다. 변경 스코프를 감지해 관련 잡만 실행한다. 빠른 피드백과 철저한 검증은 양립할 수 있다.
+
+### 3. 규칙 문서와 자동 검증을 겹쳐라
+
+AGENTS.md에 "하지 마라"고 쓰고, CI에서 실제로 위반을 감지한다. 소프트 가드레일과 하드 가드레일의 이중 장벽이 방어 깊이를 만든다.
+
+### 4. PR에 증거를 구조적으로 요구하라
+
+"무엇을 했는가"뿐 아니라 "무엇을 하지 않았는가", "어떤 증거가 있는가", "보안 영향이 있는가"를 구조적으로 물어라. 리뷰어가 판단해야 할 정보를 작성자가 미리 제공하게 만든다.
+
+### 5. 커뮤니티 노이즈를 자동으로 필터링하라
+
+인당 PR 10개 상한, stale 자동 닫기, 라벨 기반 자동 닫기/안내, 메인테이너 핑 스팸 감지. 메인테이너의 어텐션은 유한한 자원이다. 자동 트리아지가 그 자원을 보호한다.
+
+### 6. 비가역적 행동 앞에서는 멈춰라
+
+CI는 완전 자동이지만 릴리스는 수동 트리거 + 환경 승인. AI 에이전트 스킬도 버전 변경과 퍼블리시는 매 단계 승인. "빠르게 움직이되, 되돌릴 수 없는 행동 앞에서는 멈춘다."
+
+### 7. 게이트키퍼를 보호하는 게이트키퍼를 두라
+
+CODEOWNERS 파일은 창시자만 수정할 수 있다. 릴리스 워크플로는 릴리스 매니저 팀만 수정할 수 있다. 보안 코드는 secops 팀의 승인 없이 머지할 수 없다. 게이트키핑 시스템 자체를 보호하는 메타 계층이 있다.
+
+---
+
+## 당신의 프로젝트에 적용하려면
+
+OpenClaw의 5계층 전체를 한 번에 도입할 필요는 없다. 난이도 순으로 정리하면:
+
+| 단계 | 도입 항목 | 효과 |
+|------|---------|------|
+| **즉시** | pre-commit 훅 (lint+format 자동 수정) | 사소한 오류로 CI가 실패하는 낭비 제거 |
+| **즉시** | PR 템플릿에 증거/보안 섹션 추가 | 리뷰 품질 즉시 향상 |
+| **1주** | CI에 타입 체크 + 테스트 게이트 | 기본 품질 바닥선 확보 |
+| **1주** | CODEOWNERS로 보안 민감 파일 보호 | 보안 표면 하드 잠금 |
+| **2주** | stale 봇 + 자동 라벨링 | PR 큐 관리 자동화 |
+| **1개월** | 커스텀 아키텍처 경계 가드 스크립트 | 아키텍처 부식 방지 |
+| **1개월** | 스마트 라우팅 (변경 스코프 기반 CI 잡 선택) | CI 속도 최적화 |
+| **분기** | 릴리스 환경 승인 + 다단계 검증 | 릴리스 안전성 확보 |
+
+가장 ROI가 높은 것은 **pre-commit 훅**과 **PR 템플릿**이다. 둘 다 하루 안에 도입할 수 있고, 즉시 효과가 나타난다. 나머지는 프로젝트의 규모와 위험도에 맞춰 점진적으로 추가하면 된다.
+
+바이브 코딩 시대의 품질 관리는 "AI가 나쁜 코드를 만들지 않게 하는 것"이 아니다. AI는 때로 나쁜 코드를 만든다. 사람도 마찬가지다. 핵심은 나쁜 코드가 **프로덕션에 도달하지 못하게 하는 것**이다. OpenClaw의 5계층 게이트키핑은 그 방법을 보여준다.
+
+---
+
+[^1]: [OpenClaw: 세계 최대 바이브 코딩 프로젝트에서 배우는 9가지 모범 사례](/posts/openclaw-vibe-coding-best-practices/)
+[^2]: [OpenClaw CONTRIBUTING.md](https://github.com/openclaw/openclaw/blob/main/CONTRIBUTING.md)