역할 분리 파이프라인과 규칙의 코드화

AI를 붙이면 코드가 빨리 나오지만, 같은 모델이 만들고 같은 모델이 검사하면 같은 방향으로 틀립니다. 그래서 누가·무엇을·어떤 순서로 하는지를 먼저 고정했습니다. 회사 코드베이스의 리팩토링 가이드에서 시작해 개인 프로젝트의 10단계 파이프라인, 그리고 재사용 스킬 저장소로 이어진 기록입니다.

사례

1. 01-1

   구현과 검증을 다른 회사의 AI로 나눈다

   문제

   구현한 AI에게 리뷰를 맡기면 자기 코드를 자기 기준으로 통과시킵니다. 오류가 상관돼 있어 검증이 검증이 아니었습니다.

   설계

   사람(만들 것 말하기·요구사항 확정·직접 눌러보기·판단) / 구현 AI(질문·요구사항 초안·구현) / 검증 AI(인수 테스트 케이스·diff만 보고 리뷰)의 10단계. 검증 AI는 구현과 다른 벤더를 쓰고, 구현 코드가 아니라 요구사항 문서에서 테스트 케이스를 뽑습니다.

   결과

   각(Gak)에서 화면 3개를 이 순서로 완주 — 인수 테스트 109건(입력 30·타임라인 42·진단 37), 백엔드 자동 테스트 289개. 검증 AI가 요구사항에서 뽑은 케이스가 구현 AI의 해석과 어긋난 지점이 BLOCKER로 먼저 드러났습니다.

2. 01-2

   절차는 문서가 아니라 게이트로 지킨다

   문제

   '요구사항 승인 후 구현'이라고 적어두면 급할 때 건너뜁니다. 미정 항목이 남은 채 구현이 시작되면 검증 AI의 테스트 케이스와 구현이 서로 다른 것을 만듭니다.

   설계

   게이트 0 — 요구사항 승인 전에는 테스트 케이스도 구현도 시작하지 않는다. 게이트 A — BLOCKER 등급 미정이 0이어야 구현한다. 게이트 B — 타입·린트·테스트·빌드가 통과해야 리뷰를 요청한다. 검증 AI 쪽에도 대칭 조건('미승인 초안이면 거부')을 둡니다.

   결과

   처음엔 게이트 2개였고, 질문 단계를 검증 AI에서 구현 AI로 옮기는 재편 때 게이트 0이 추가됐습니다. 각(Gak) 미승인 화면 2개는 BLOCKER 15건이 남아 구현 단계에 들어가지 않은 상태로 기록돼 있습니다.

3. 01-3

   규칙은 프로젝트에서 태어나 스킬로 옮긴다

   문제

   파이프라인 규칙을 프로젝트 지시 문서에 두면, 두 번째 프로젝트에서 복사하는 순간 첫 프로젝트의 어휘가 따라 들어오고 두 사본이 갈라집니다.

   설계

   두 번째 프로젝트에서 같은 규칙을 쓰게 되면 도메인 어휘를 전부 제거해 스킬로 추출합니다. 어휘를 빼면 성립하지 않는 문장은 규칙이 아니라 그 프로젝트의 사정입니다. 옮긴 스킬은 세션 기록에서 호출 횟수를 세고, 직전 요청 문장을 함께 출력해 과발동·미발동을 사람이 판정합니다.

   결과

   스킬 12개 — 처음 추출한 6개(역할 분리 파이프라인·구현 전 설계 판단·느린 네트워크 대응·레퍼런스 라이브러리·기준 브랜치 최신화·대상 브랜치 충돌 해결)에 환경 차이 진단·프로젝트 흐름·인프라 최소선·보안 최소선·마케팅 성장·스킬 생성이 더해졌습니다. 처음 6개를 세션 30개 기준으로 셌을 때 발동 — 설계 3·라이브러리 7·충돌 해결 6·최신화 1·파이프라인 0. 파이프라인 발동 0은 '안 쓰임'이 아니라 프로젝트 문서에 사본이 남아 있다는 신호였고, 이 판정은 횟수가 아니라 직전 요청을 읽어야 나왔습니다.

4. 01-4

   회사 코드베이스 — 가이드와 AI 규칙을 한 몸으로

   문제

   4년 된 어드민의 계층 분리 리팩토링을 여러 사람이 병행하면 각자의 '계층'이 조금씩 다릅니다. AI를 붙이면 눈앞의 파일을 기준으로 패턴을 추론하니 편차가 더 빨리 늘었습니다.

   설계

   리팩토링 가이드 문서를 저장소에 제정하고, AI 협업 규칙(CLAUDE.md)이 그 가이드를 참조하게 연결했습니다. 사람이 읽는 문서와 AI가 읽는 문서를 따로 두지 않습니다. 팀 MR 워크플로(기준 브랜치 최신화, develop 대상 충돌 해결)도 같은 방식으로 스킬에 담았습니다.

   결과

   가이드를 명시 참조한 MR 9건, Clean Architecture 언급 MR 33건, 리팩토링 MR 132건(2025.09~2026.08). 주문 도메인 최대 파일 1,224 → 499줄, 회귀를 유닛 테스트 82개로 봉인, 리팩토링 중 잠복 결함 3건 발굴.

남은 규칙

1. 01구현과 검증은 다른 회사의 AI가 한다 — 오류의 비상관성.
2. 02검증 AI에는 구현 코드가 아니라 요구사항과 diff만 준다.
3. 03승인 전에는 테스트 케이스도 구현도 시작하지 않는다. 기계 검사가 실패한 코드는 리뷰를 요청하지 않는다.
4. 04같은 규칙을 두 번째 프로젝트에서 쓰게 되면 어휘를 제거해 스킬로 뺀다. 옮긴 스킬은 발동을 센다.
5. 05사람이 읽는 가이드와 AI가 읽는 규칙은 한 파일을 참조한다.