루비얀카 방법론은 현재 독립 패키지(루비얀카·레드팀)로 구현을 준비 중이며, 두 패키지가 완성될 때까지 이 글의 내용은 언제든 바뀔 수 있다. — 소프트웨어가 해야 할 일, 그리고 그렇게 시키는 법. 문서·SSOT·피라미드·프로그레스·핸드오버·강제력 4단계.
§ 00 · 바꿀 수 없는 것과, 지을 수 있는 것
먼저 프레임 하나. 요즘 이런 정의가 통용된다 — 에이전트 = 모델 + 하네스(Agent = Model + Harness). 모델은 당신이 못 바꾼다. 그건 본사가 정해서 내려준다. 당신이 바꿀 수 있는 건 하네스 — 모델을 둘러싼 문서·규칙·권한·감시다.
그러니 “AI가 일을 제대로 하게 만든다”는 것은 더 좋은 모델을 기다리는 게 아니라, 하네스를 짓는 일이다. 소프트웨어는 피의자다. 피의자에게 시켜야 할 일과, 그 일을 하게 만드는 장치를 나눠 본다.
§ 01 · 소프트웨어가 지켜야 할 규율
기계에게 강제할 최소 규율. 이건 부탁이 아니라 하네스로 박아 넣는 것이다.
추정 금지 — DB·API·빌드·파일 상태를 뇌피셜로 보고하지 않는다. 확인 안 됐으면 “확인 안 됨”이라고 말한다. 측정 안 한 것엔 ‘추정’ 딱지를 붙인다.
자백서를 쓴다 — 실수가 나오면 기계가 스스로 기록한다. 무엇을 틀렸고, 어떻게 드러났고, 근본 원인이 무엇이고, 재발 방지 규칙이 무엇인지. 그리고 일 전에 자백을 다시 읽는다.
증거가 아니면 완료가 아니다 — 요약이 아니라 원본. “통과했습니다”가 아니라 verdict와 exit code. 교차검증을 통과하기 전엔 “완료”가 없다. 그리고 면피의 언어 금지 — “아마 괜찮음”, “미확정”, “판단 불가”는 전부 결국 “안 봤다”는 뜻이다.
이 규율은 인간의 선의로 지켜지지 않는다. 다음 절, 문서와 장치가 지키게 한다.
§ 02 · 시키는 법 = 문서 (하네스의 몸통)
기계를 움직이는 것은 채팅창의 윽박지름이 아니라 기계 둘레에 쌓은 문서다. 각 문서가 왜 필요한지 — 그게 이 방법론의 핵심이다. 아래 일곱은 잘 굴러가는 프로젝트들이 예외 없이 공유하는 골격이다.
① 정본(SSOT) — 단일 진실. 한 곳에만 존재하고, 다른 모든 곳은 그것을 참조한다. 같은 사실이 두 곳에 있으면 둘은 반드시 언젠가 어긋나고, 기계는 그중 편한 쪽을 고른다. 그래서 문서엔 개수·수치를 박지 않고, 세는 명령을 적어 둔다.
② 피라미드 위계 — 수정은 위에서 아래로만. 기획(Why) → 규칙 → 명세 → 코드 → 이력. 전파는 단방향. 코드가 기획과 어긋나면 코드를 고친다. 기획이 정답이다.
③ 프로그레스 — “지금 무엇이 참인가.” 기계는 현재 상태를 추정한다. 그래서 “지금 이 프로젝트가 어디까지 됐는가”를 한 문서에 고정한다. 추정할 필요가 없게.
④ 핸드오버 — 세션은 기억을 잃는다. 매 세션은 새 알바생이다. 이전 세션이 무엇을 했고 무엇이 잠겼는지, 다음 세션이 가장 먼저 읽어야 한다. 실패를 다음 날 아침 다시 마주하게 만드는 자백 스택이다.
⑤ 잠긴 결정(ADR) — 재론을 막는다. 한 번 내린 결정이 잠기지 않으면, 다음 세션이 또 뒤집고 또 논의한다. 결정을 한 곳에 모아 “재론 금지”로 잠근다.
⑥ 동기화 규칙 — 복사본은 어긋난다. 여러 저장소가 같은 문서를 공유하면, 그것이 정말 같은지를 바이트로 대조한다(“같다”는 말을 믿지 않고 diff로).
⑦ 브랜치 규칙 — 되돌리기 어려운 건 인간이 쥔다. feature → develop → main, 단방향. main으로의 배포는 인간만. 검사를 건너뛰는 우회는 금지. 이 일곱을 관통하는 한 줄 — 아키텍처 원칙이 중요한 건 우아함이 아니라 맥락이 썩는 것(Context Rot)을 막기 때문이다. 짧게, 한 곳엔 하나씩.
§ 03 · 감시 장치 — 강제력에는 급이 있다
문서가 규칙이라면, 장치는 그 규칙을 강제한다. 그런데 선언과 강제는 다르다. 문서에 “이 센서는 반드시 돈다”고 적는 것과, 그게 실제로 도는 것은 전혀 다른 문제다. 그래서 강제력을 급으로 나눠 이해해야 한다 — 약한 것부터 강한 것까지 넷.
핵심은 이것이다 — 중요한 규칙일수록 아래 급(C·D)으로 내려야 한다. 산문(A)에만 적어 두면, 기계는 그럴듯하게 무시한다. 에이전트·스킬·센서·훅은 이 사다리의 각 칸이다. 그리고 무엇이 증거인가 — verdict 줄과 exit code, 원본 stdout. 요약만 남기면 거짓 PASS가 숨는다.
A · 산문 지시 (문서 규칙) · 가장 약함 — 기계가 그 문서를 읽어야만 작동
B · 도구가 제한된 에이전트 · 검증 담당에게서 Edit/Write 권한을 뺀다 → 구현자·검증자가 구조적으로 분리(지시가 아니라)
C · 결정론 센서 (스크립트) · 실제 tsc·테스트·빌드를 돌려 exit code로 PASS/FAIL — 모델 판단 0
D · 사전 훅 (PreToolUse) · 위험한 명령을 실행 전에 차단 — 모델의 추론이 실패해도 작동하는 유일한 급
§ 04 · 산 예제 — ADR은 왜 늘 잊히는가
이 사다리가 왜 중요한지 한 가지로 보여주는 게 ADR(아키텍처 결정 기록)이다. “아키텍처 결정을 내리면 기록하라” — 다들 안다. 그런데 채팅으로 일을 시키면 코드와 문서는 고쳐지는데 ADR만 자꾸 안 써진다. 왜?
ADR엔 깨짐 신호가 없기 때문이다. 코드는 안 짜면 컴파일이 깨지고, 테스트는 안 하면 빨간불이 뜬다. ADR은 안 써도 아무것도 안 깨진다. 그래서 “기록하라”는 산문(A급)에만 걸려 있고, 바쁘면 기계가 그럴듯하게 건너뛴다. 규칙의 중요도와 강제력의 급이 어긋나 있는 것이다.
고치는 법은 사다리를 내리는 것 — 깨짐 신호를 인위적으로 만든다. 결정의 흔적(의존성·스키마·설정·아키텍처 문서 수정)을 건드린 커밋은, 결정 기록 폴더에 같은 날짜 항목이 없으면 커밋을 막는다(D급). 그러면 결정을 기록하지 않고는 그 변경을 넣을 수 없다 — 테스트 없이는 push 못 하듯이.
같은 병이 ‘자백을 다시 읽기’에도 있다. 자백을 쓰는 것은 훅으로 강제되는데(D급), 일 전에 다시 읽는 것은 기억에 맡겨져 있다(A급). 바쁘면 안 읽는다. 고침도 같다 — 자백이 너를 찾아오게 한다. 교훈 하나로 압축된다: 중요한 규칙은 ‘기억하라’가 아니라 ‘못 지나가게’로 만든다.
§ 05 · 자기 하네스는 충분조건이 아니다
지금까지가 소프트웨어의 자기 하네스다. 문서로 시키고, 4단계로 강제하고, 증거로 확인하는 것. 이것만으로 강력하다. 그러나 여기서 끝나면 안 된다. 이론편이 경고했다 — 감시받는 자가 감시를 지으면, 감시는 극장이 된다. 이 하네스도 기계가 스스로 만들고 유지한다. 그래서 어느 순간 센서가 안 돌고, 게이트가 빈 파일이 되고, 마지막에 심은 레드팀이 무시된다.
그래서 그 위에, 그 하네스가 정말 무는지를 밖에서 확인하는 눈이 필요하다. 조건이 까다롭다 — 프로젝트 밖에 있어야 하고, 빌더의 이야기를 읽지 않으며(외부 계약과 보편 룰로만 판정), 예측 못 한 방향으로 공격하고(다른 모델·아무도 안 짠 입력·실제 배포 상태 프로빙), 배포 관문에 선다. 배포되기 전에 잡고, 이미 나갔으면 롤백을 명령한다.
이건 소프트웨어의 자기 하네스가 아니라, 그것을 취조하는 두 번째 취조관이다. 첫 번째 취조관(작업하는 Claude)조차 믿지 않는다. 그래서 이 방법론은 두 패키지로 나뉜다 — 프로젝트 안에 설치되어 짓는 동안 취조하는 것과, 프로젝트 밖에서 배포 관문을 지키는 것.
CODA · 사람도, 기계도 읽을 수 있는 코드
좋은 코드가 무엇인가에 대한 오래된 말이 있다. 컴퓨터가 이해하는 코드는 누구나 짤 수 있고, 사람이 이해하는 코드를 짜는 사람이 좋은 프로그래머라고. 기계와 함께 짓는 시대에는 이렇게 고쳐 쓸 수 있다 — 좋은 사용자는, AI와 사람이 둘 다 이해할 수 있는 코드와 문서를 쓴다.
문서는 사람을 위한 것이 아니다. 기계를 취조하기 위한 것이다. 그리고 잘 쓴 문서는, 사람도 읽을 수 있다.
Read this note at sass.studio.