cladding — Unified Governance for AI-Coupled Engineering

English · 한국어

cladding

코드는 LLM이 쓴다 — cladding은 그 전과 후를 책임진다.
cladding(외장재)이라는 이름 그대로, 호스트 LLM을 감싸는 검증 층.

ironclad spec tests detectors license

Ironclad 표준의 공식 reference 구현.
호스트 LLM(Claude Code · Codex · Gemini · Cursor)이 일을 시작하기 전에 프로젝트의 의도를 넣어 주고,
일을 마친 후에 36개 검출기와 15단계 게이트로 결과를 검증한다. 같은 목표를 향한 분업이다.

호스트 LLM 전(의도 주입) · 후(검증) · 기록(피드백 루프) — cladding이 LLM을 감싸는 협력 구조

이 루프가 노리는 것은 하나 —
AI의 "다 됐습니다"를 말이 아니라 증명으로 만드는 것.

의도는 기록으로 남고 · 어긋남은 자동으로 막히고 · 완료는 검증 서명으로 증명된다.
그래서 AI가 짠 코드를 사람이 짠 코드만큼 믿고 내보낼 수 있다.

개발자인 당신에게는 — AI 코드 리뷰에 쓰는 시간이 줄고, 6개월 뒤에도 코드의 왜가 남아 있고,
배포 전 "정말 다 된 건가"를 더 이상 감으로 판단하지 않아도 된다는 뜻이다.

호스트 LLM과 어떻게 함께 일하나

cladding은 코드를 쓰지 않는다. 코드를 쓰는 건 언제나 호스트 LLM이다. cladding이 맡는 건 LLM이 잘하지 못하는 두 가지 — 시작할 때 의도를 정확히 기억시키는 일과 끝났을 때 결과를 기계적으로 검증하는 일이다.

전 — 의도를 넣는다
LLM이 올바른 컨텍스트로 시작하도록
  • 프로젝트 지도 주입 — 대화를 시작할 때마다 "기능 몇 개, 무엇이 진행 중, 마지막 검증 결과"가 자동으로 LLM에게 전달된다
  • 꼭 필요한 의도만 추출 — 지금 작업할 기능의 왜·관련 기능·검증 기준만 추려서 준다 (스펙 전체를 덤프하지 않는다)
  • 프로젝트 규칙 적용 — 팀이 정한 금지 패턴·선호 패턴이 매번 표준 지시로 들어간다
후 — 결과를 검증한다
LLM의 산출물이 스펙과 어긋나면 차단
  • 15단계 검증 관문 — 타입·린트·테스트·커버리지·아키텍처·시크릿·E2E·증거를 한 번에
  • 36가지 어긋남 검사 — 스펙↔코드↔테스트가 서로 맞는지 모든 방향에서 자동 대조
  • 구현을 못 보는 채점자 — 코드를 읽을 수 없는 별도 에이전트가 스펙만 보고 쓴 테스트로 채점
  • 실행물 직접 구동 — "테스트는 통과인데 프로그램은 안 도는" 상황을 실제 실행으로 차단
기록 — 다음 턴의 입력
검증 결과가 다시 LLM의 컨텍스트로
  • 검증 서명 — 모든 검사를 통과한 코드 상태가 "이 시점에 검증됐다"는 서명으로 저장소에 남는다
  • 감사 장부 — 모든 검증 실행·완료 시도·차단이 누가·언제·어떤 결과였는지 기록된다
  • 수리 카드 — 결정적 검사(어긋남·아키텍처·시크릿) 실패를 남긴 채 대화를 끝내려 하면 한 번 막아서고, 실패 요약을 다음 대화 시작에 자동으로 실어 보낸다

이 루프가 도는 동안 사용자는 평소처럼 자연어로 개발하면 된다 — 외울 명령이 없다.

실시간 개입(지도 주입 · 즉시 차단 · 종료 차단)은 Claude Code에서 전부 동작한다. Codex · Gemini · Cursor에서는 같은 검증을 대화 속 도구 호출과 git·CI 관문으로 수행한다.

done은 선언이 아니라 획득이다

AI 코딩의 고질병은 "다 됐습니다" 가 검증 없이 선언되는 것이다. cladding에서 feature의 status: done은 쓰는 값이 아니라 얻는 값이다.

한 장면 — LLM의 done 선언을 훅이 차단하고, 게이트 RED가 수리 카드로 피드백되고, GREEN일 때만 done이 획득되는 과정
① AI가 완료 표시를 직접 써넣으려 하면 → 그 자리에서 차단된다 ("완료는 검증으로 얻으세요") — Claude Code 실시간 기준, 다른 host는 게이트·CI가 같은 역할
② AI가 완료를 요청하면 → 결정적 9단계(타입·린트·어긋남·아키텍처·시크릿·테스트·커버리지·스펙 적합성·실행물 구동)를 전부 돌려 모두 통과할 때만 완료로 기록, 하나라도 실패면 자동 되돌림 — E2E·증거 단계는 CI의 전체 15단계가 맡는다
③ 통과와 동시에 검증 서명이 남는다 — "이 코드가 이 시점에 검증됐다"는 커밋 가능한 증거
④ 실패를 남긴 채 대화를 끝내려 하면 → 한 번 막아서고(같은 실패로 또 끝내면 통과시키는 대신 기록) 수리 카드를 다음 대화로 넘긴다

한계도 그대로 공개한다: 즉시 차단이 못 보는 우회 경로가 존재하며, 그 경우는 사후 검증(관문·어긋남 검사)이 잡는다. 즉시 차단이 1차 방어선, 사후 검증이 2차 방어선이고 어느 쪽도 단독 보증이 아니다.

무엇이 달라지나

같은 상황에서 일반 AI 코딩 환경과 cladding 환경의 동작 차이.

상황일반 AI 코딩cladding
코드가 spec과 어긋날 때리뷰에서 발견하면 수정편집 직후 자동 감지(알림) · 어긋난 채로는 "완료"가 통과 못 함
AI가 "다 됐다"고 할 때말을 믿는 수밖에게이트 GREEN일 때만 done 획득
세션을 실패 상태로 끝낼 때그대로 종료, 다음에 잊힘종료를 한 번 막고 수리 카드 인계
두 명이 동시에 feature 추가merge conflicthash-8 ID · 파일 분리 → 충돌 0
AI가 짠 코드를 누가 검증?작성한 AI가 자기 검증 (위험)구현을 못 보는 채점자 + 기계 관문
AI 도구를 바꿀 때도구마다 재구성1 spec → 4 host 자동 연결

How it works

Spec → Code → Tests가 한 cycle로 순환한다 — spec이 왜를 기록하고, 게이트가 검증하고, detector가 어긋남을 차단한다.

Spec → Code → Tests 순환 — 15단계 검증과 36 drift detector가 cycle을 지킨다

1. Spec — 의도의 단일 기준 (SSoT)

spec이 왜(무엇을 왜 만드는지)를 기록한다. 4-tier 단일 진실 출처 — 의도가 위, 구현물이 아래.

Tier역할수정 권한권위
A — Spec의도 (무엇을 만들까)사람이 정의봉인 · LLM 수정 금지
B — Design설계 (어떻게 만들까)사람이 자유 편집A와 일치 검증
C — Derived구현물 (코드 · 테스트) + attestation (검증 서명)LLM · 사람코드 보고 자동 재생성
D — Audit감사 기록 (무엇이 일어났나)append-only수정 불가

A가 아래 모든 tier보다 우선 — spec(A)과 코드(C)가 다르면 틀린 쪽은 코드다. 의도(A)가 흔들리면 모든 게 흔들리므로 LLM이 못 건드리게 봉인한다.

샤딩 · multi-dev 안전 — spec/features/<slug>-<hash>.yaml처럼 feature마다 별도 파일 + 8자리 hash ID (예: F-d86375d8). 두 명이 동시에 새 feature를 만들어도 다른 파일·다른 ID라 merge conflict 0. 자세히는 Hash-based feature IDs.

4-tier SSoT — A(Spec) → B(Design) → C(Derived + attestation) → D(Audit), A가 B보다 우선

2. Gate — 15단계 Iron Law

"완료"로 인정받으려면 strict 게이트(15단계 중 결정적 9단계)를 전부 통과해야 하고, E2E·증거까지 포함한 전체 15단계는 CI가 돌린다. 같은 검사 엔진을 시점별 묶음으로 건다 — commit 때 빠른 3단계(git hook 설치 시), push·완료 시점에 9단계, CI에서 15단계 전부. 깊이가 다를 뿐 검사 로직은 동일하다.

15단계 Iron Law 게이트 — 정적(6) · 테스트·적합성(4) · E2E(3) · 증거(2), GREEN이면 attestation 서명
Stage무엇을 검사하나
1.1 Type · 1.2 Lint타입 오류 · 코드 스타일
1.3 Drift36 detector의 spec ↔ 코드 어긋남
1.4 Commit · 1.5 Arch · 1.6 Secret작업트리 clean · architecture invariant · API 키 노출
2.1 Unit · 2.2 Coverage단위 테스트 통과 · coverage 하락 차단
2.3 Spec conformance · 2.4 Deliverable smoke구현을 못 본 채점자의 테스트 통과 · 선언된 실행물이 실제로 도는지 ("테스트는 통과인데 결과물은 안 도는" 빈 초록 차단)
3.1 Smoke · 3.2 Perf · 3.3 Visuale2e 핵심 동작 · 성능 예산 · UI 시각 회귀
4.1 Audit · 4.2 UAT모든 AC(수용 기준)에 증거 1건 이상 · 모든 done feature에 증거 1건 이상

3. Detector — 36개 어긋남 검출기

spec · code · test 사이 모든 방향의 어긋남을 자동 검출한다. 전체 카탈로그: detector catalog.

방향무엇을 잡나수대표 detector
spec ↔ codespec에 있는데 코드에 없거나, 코드가 spec을 벗어남10MISSING_IMPLEMENTATION, AC_DRIFT, DELIVERABLE_INTEGRITY
code ↔ test코드는 있는데 테스트 없음 · 커버리지 하락 · 시크릿6MISSING_TESTS, COVERAGE_DROP, HARDCODED_SECRET
spec ↔ testspec의 AC가 테스트로 검증 안 됨 · 상태 거짓5UNTESTED_AC, STATUS_DRIFT, SPEC_CONFORMANCE
spec 위생spec 자체의 무결성 (ID 충돌 · 순환 의존)8ID_COLLISION, SLUG_CONFLICT, DEPENDENCY_CYCLE
환경 무결성빌드 환경 · 메타 파일3HARNESS_INTEGRITY, META_INTEGRITY
검증 신선도검증 서명 이후 코드가 바뀌었는지1STALE_ATTESTATION (0.6.0 신규)
거버넌스 · 문서정책 위반 · 문서 표류3ABSENCE_OF_GOVERNANCE, PROJECT_CONTEXT_DRIFT

4. Cycle — 한 feature의 생애주기

정의 → 동기화 → 구현 → 획득. 모든 검사를 통과해야 "완료"를 얻는다.

한 feature의 생애주기 — 정의 → 동기화 → 구현 → 획득, 검사를 모두 통과하면 완료 획득 / 실패면 자동 되돌림

Multi-Agent — 만드는 자와 검증하는 자의 분리

만드는 에이전트와 검증하는 에이전트가 분리돼 있어 어떤 에이전트도 자기 작업을 스스로 승인하지 못한다. 0.6.0의 blind-author는 한 발 더 나간다 — 테스트를 쓰는 에이전트에게 구현을 읽을 도구 자체가 없다(Read/Grep 미부여). "구현 안 보고 썼다"가 약속이 아니라 구조적 사실이 된다. 이 분리는 규제·감사(EU AI Act · SOX) 기준에 그대로 매핑된다.

페르소나 권한 분리 — orchestrator가 분배, planner/developer/reviewer가 작업, blind-author는 구현을 못 보는 테스트 작성자, observability가 관찰

Ecosystem

기존 세 카테고리의 결합부에 cladding이 있다.

Ecosystem Venn — SDD · 실행기 · Multi-agent 거버넌스 세 카테고리의 결합부에 cladding

인접 도구와의 차이

cladding의 차별점은 결합 — 위 카테고리의 핵심을 하나의 검증 루프로 묶는 것.

Install

두 단계 — 인프라 설치 → 프로젝트 spec 생성.

1단계 — 인프라 설치 (npm)

npm install -g cladding   # cladding CLI 설치
cd <project>                # 프로젝트로 이동
clad setup                  # AI 도구 자동 연결 (Claude / Codex / Gemini / Cursor)

clad setup 한 번이면 설치된 AI 도구들을 자동 감지해 전부 연결한다 — 도구별 설정을 따로 할 필요가 없다.

clad setup이 연결하는 위치 (4개 host · 5개 연결 지점)
호스트 (감지 시)wire 위치자동 활성화
Claude Code (~/.claude/)~/.claude/plugins/claddingclaude plugin marketplace add + install
Codex CLI skills (~/.agents/)~/.agents/skills/cladding-*(Codex 재시작 시 자동)
Codex CLI MCP 서버 (~/.codex/)~/.codex/config.toml의 [mcp_servers.cladding](TOML entry 자체)
Gemini CLI (~/.gemini/)~/.gemini/extensions/claddinggemini extensions link
Cursor (~/.cursor/)~/.cursor/mcp.json의 mcpServers.cladding(JSON entry 자체)

clad setup은 claude / gemini binary가 PATH에 있을 때 각 host의 활성화 명령을 자동 호출. 업그레이드 후나 새 AI 도구 설치 후 다시 실행해도 안전하다.

검증 수준(정직 고지): Claude Code는 실사용 캠페인으로 전 기능 검증됨(실시간 개입 포함). Codex · Gemini CLI는 배선 자동화 + 기본 동작 확인. Cursor는 연결은 자동이지만 실사용 검증이 아직이다 — 검증되는 대로 갱신.

MCP 서버에 대하여. 4 host 모두 cladding을 MCP 서버로 wire한다 — wire 위치만 다르다. MCP는 사용자가 직접 호출하는 것이 아니다 — /mcp 슬래시도, 수동 연결 단계도 없다. 각 host의 AI가 자연어 요청에 응답해 cladding의 기능을 알아서 호출하며, 사용자는 /cladding:init 한 번과 일반 대화만 입력한다.

2단계 — Init (프로젝트 spec 생성)

프로젝트 디렉토리에서, AI 도구 안에서 한 번 호출:

[AI 도구 안] /cladding:init "B2B 결제 SaaS"

프로젝트의 spec.yaml과 관련 문서가 만들어진다 — 프로젝트당 한 번.

강제력을 높이려면: clad init --with-hook(pre-commit + pre-push git hook 설치) · clad init --with-ci(CI 게이트 스캐폴드 — 진짜 강제는 CI에서).

세 가지 init 시나리오

시작 상황명령무엇이 일어나는가
아이디어만 있을 때/cladding:init "B2B 결제 SaaS 만들거야"LLM이 도메인 분석 → spec · 문서 · 정책 자동 생성 + 후속 질문 2–3개
기획 문서가 있을 때/cladding:init docs/plan.md파일 경로 인식 → 내용을 자동 로드해 intent로 사용
기존 프로젝트 도입/cladding:init "이 프로젝트에 cladding 적용해줘"기존 코드 자동 스캔 → 관찰한 패턴 + intent 결합

init 한 번이면 끝

한 번 init하면 그걸로 끝 — 그 뒤론 평소처럼 개발하면 된다. cladding이 배경에서 전·후 루프를 돌리니, 따로 외울 명령은 없다.

업그레이드

npm update -g cladding     # 1. 새 버전 설치
cd <your project>          # 2. 프로젝트마다 한 번씩
clad update                # 3. 새 버전에 맞게 정리

당신이 쓴 코드·spec.yaml·문서는 그대로 두니 안전하고, 새 버전이 더 깐깐해 짚을 게 있으면 알려만 준다 (막거나 고치지 않음).

Status

version
v0.6.0
2026-06
준수 등급
L4
tests
1384/1384
all pass
gate
15 단계
36 detectors
features
171
170 done · 자기 스펙

134 test files · coverage는 COVERAGE_DROP detector가 하락 차단 · 설치는 npm 단일 경로(npm install -g cladding)

Ironclad 1.0까지의 길 — 1.0은 독립적인 두 개의 구현이 L4 검증 셋을 통과해야 잠긴다 (GOVERNANCE § 1). cladding이 첫 번째.

Docs

License

MIT. LICENSE · 관련: Ironclad (구현 대상 표준) · harness-boot (seed).