교차 검증 도구 3개월: 사상, 프롬프트-only 구현, 프로필 자산화

TL;DR
AI가 코드를 짜는 시대에 도구가 측정 못 하는 의미적 판단(설계 의도, 톤, 보안 가정)이 병목이 됩니다.
의사결정·설계·문서·구현 4축 체크리스트를 프롬프트-only 플러그인으로 만들고 3개월 돌렸습니다.
도구를 만든 것보다 쓰면서 쌓인 프로필이 자산이었습니다.

1. 왜 교차 검증인가

AI 코딩 도구를 도입한 지 수개월. 체감하는 변화는 단순하지 않았습니다. 코드 생성 속도는 빨라졌지만 설계 단계에서 더 많은 질문을 던지게 됐습니다. 그러면서 “이 설계가 맞는지” 검증하는 시간이 코드 작성 시간 절감분보다 더 늘어났습니다.

손해는 아니었습니다. 그 시간이 들어가는 자리에 사고 시뮬레이션이 들어왔고, 후속 수정이 줄고, 의사결정 근거가 대화에 남기 시작했습니다. 다만 매번 같은 종류의 요청을 반복하고 있다는 걸 알게 됐습니다.

반복 요청	예시
비판적 사고	“이 설계의 약점은 무엇인가?”
자가 검증	“이 구현이 정책 문서와 일치하는가?”
문서 가독성	“A4 PDF로 출력했을 때 읽기 편한가?”
의사결정 근거	“왜 이 방식을 선택했는지 기록되어 있는가?”

도메인은 달라도 검증의 관점은 같았습니다. “이건 도구화할 수 있다”는 판단이 들었습니다.

“교차”의 의미

내 작업이 진짜 맞는지 다른 시선으로 다시 확인하는 것. 핵심은 같은 대상을 개발자의 눈과 AI의 눈으로 교차시켜 보는 것입니다. AI 에게 판단을 맡기는 것이 아니라, AI 를 또 하나의 시선으로 사용하여 개발자가 소통하며 최종 확인을 하는 구조입니다.

4축

축	검증 질문
의사결정	왜 이 선택인가? 대안과 트레이드오프는?
설계	엣지 케이스는? 정책과 일치하는가?
문서	가독성·톤·정보 유실
구현	코드가 설계를 정확히 반영하는가?

축을 나눈 것은 검증 관점을 정리한 것이지 도구를 분리하겠다는 의미가 아닙니다. 하나의 에이전트가 4축으로 한 번에 봅니다.

기존 자가검증 도구와의 차이

이미 Ralph(자기참조 루프), BMAD(역할별 에이전트), Claude Agent Teams(병렬·적대적 검증) 같은 자동화가 있습니다. 공통점은 개발자 개입을 최소화하는 방향. AI 끼리 검증·논박하고 개발자는 결과만 봅니다.

교차 검증은 정반대입니다.

기준	자동화형	개발자 호출형 (교차 검증)
검증 범위	도구가 측정 가능한 신호 (테스트·빌드·린트)	의미적 판단 (설계 의도, 톤, 가독성)
편향 통제	같은 모델 계열 → 같은 맹점 공유	개발자가 중간에 개입하여 방향 교정
학습 효과	없음 (AI 만 반복)	개발자가 검증 과정을 같이 봄
최적화 대상	속도·처리량	판단 품질·이해도

자동화된 자가검증은 “맞는지 틀린지”를 판별합니다. 개발자 호출형 교차 검증은 “왜 맞고 왜 틀린지”를 개발자가 함께 이해하는 과정입니다.

2. 프롬프트-only 플러그인으로 구현

claude-cross-verify 에는 실행 가능한 코드가 한 줄도 없습니다. 전체 구현이 마크다운 프롬프트입니다.

claude-cross-verify-plugin/
├── agents/
│   └── cross-verifier.md     # 에이전트 정의 (70줄)
└── skills/
    ├── verify/SKILL.md        # 4축 검증 지침 (259줄)
    └── setup/SKILL.md         # 프로젝트 설정 초기화

장점	단점
구조가 단순, 마크다운만 수정하면 동작 변경	출력 품질을 프로그래밍적으로 강제할 수 없음
설치·배포 즉시	동일 입력에 대한 일관성 확인 어려움
플러그인 구조 자체가 설계 문서 역할	테스트 자동화 불가

이 선택은 한계인 동시에 교차 검증의 본질과 맞닿아 있습니다. 자동화가 아니라 개발자가 AI 와 소통하며 확인하는 행위라서, 코드로 강제하면 그 본질이 깨집니다.

프로젝트 맞춤 설정

.claude/cross-verify.json 으로 프로젝트별 컨벤션, 설계문서, 중점 축을 지정합니다.

{
  "conventions": "docs/CONVENTIONS.md",
  "focusAxes": ["설계", "구현"],
  "customChecks": {
    "설계": ["UseCase는 WHAT만 표현하는가"],
    "구현": ["Repository CUD는 단일 도메인 원칙을 준수하는가"]
  }
}

범용 4축 검증도 가능하지만, 설정이 있으면 검증이 프로젝트의 아키텍처를 기준선으로 삼습니다.

3. 자체 검증과 실전이 보여준 한계

도구를 만들고 플러그인 레포 자체에 /verify 를 돌렸습니다. 가장 큰 발견은 아키텍처 인식 부재였습니다. 플러그인이 코드를 검증할 때, 그 코드가 시스템 안에서 어디에 위치하는지를 모른 채 검증을 시작합니다. 지도 없이 건물을 검사하는 것과 같습니다.

이 시점에서 두 가지가 드러났습니다.

1. 플러그인에는 문서 철학만 있고 코드 철학이 없습니다
2. 코드 철학을 검증하려면 실제 코드 레포에서 돌려봐야 합니다

실제 피처 브랜치(48파일, +1,061/-163줄, 헥사고날 아키텍처)에 적용한 결과, .claude/cross-verify.json 의 커스텀 체크가 코드 철학 공백을 채웠습니다. 완전하지는 않습니다. 아키텍처 인식이 수동 설정에 의존한다는 한계는 여전히 남아 있습니다.

도구가 잡은 사례 셋

• 타임존 일관성: LocalDate.now() + ZoneId.systemDefault() 사용. 멀티 노드 환경에서 서버 타임존이 UTC 가 아니면 “당일” 경계가 달라져 데이터 누락/중복 가능. 정적 분석·단위 테스트로는 드러나지 않는, 런타임 환경 의존적 이슈.
• 페이지네이션 비대칭: 당일 실시간 데이터가 첫 페이지에만 병합되어 totalElements 가 페이지마다 달라지는 구조적 한계. 코드 자체에는 버그가 없어 기존 테스트를 통과하지만 API 소비자에게 혼란을 줄 수 있는 지점.
• 트랜잭션 경계: DELETE+INSERT 에 @Transactional 이 없으나, 멱등성 + 백필 복구가 트랜잭션의 역할을 대체하는 설계임을 확인. 문제가 아닌 의도적 설계였음을 검증으로 확인한 사례.

세 번째 사례가 교차 검증의 가치를 잘 보여줍니다. 자동화 도구라면 “@Transactional 누락”으로 경고를 띄웠을 겁니다. 교차 검증은 “왜 없는지”를 개발자와 함께 확인하고 의도적 설계임을 기록으로 남겼습니다.

4. 3개월 운영: 프롬프트 노하우가 프로필로 쌓이다

습관으로 자리 잡은 검증

시점	검증 습관
도입 초기	큰 작업 끝나면 1회
1개월 차	설계 변경 시마다
3개월 차	커밋 전 검증이 자연스러운 절차

습관이 된 이유는 단순합니다. 놓칠 뻔한 것을 실제로 잡아줬기 때문입니다. 개발자는 집중하고 있는 문제에 시야가 좁아지는데, 교차 검증이 4축을 강제로 훑기 때문에 지금 집중하지 않는 축의 문제를 환기시켜 줬습니다.

반복 프롬프트를 프로필로 모으다

검증을 반복하면서 매번 비슷한 맥락을 프롬프트로 전달하고 있다는 걸 알게 됐습니다.

• “UseCase 는 WHAT 만 표현하는지 확인해줘”
• “Repository CUD 는 단일 도메인 원칙 준수하는지 봐줘”
• “헥사고날 아키텍처 위배 여부 체크해줘”

이 반복이 프로필 시스템의 동기가 됐습니다. 위의 cross-verify.json 설정 파일 하나로 3개월간 반복 입력하던 프롬프트가 모였습니다.

단계	형태	특징
1단계	매번 프롬프트 직접 입력	경험은 머릿속에만
2단계	반복 패턴을 프로필로 정리	경험이 설정 파일로 외부화
3단계	프로필이 프로젝트 컨벤션과 연결	팀의 규칙이 검증 도구에 반영

1단계에서 2단계로의 전환이 핵심이었습니다. 머릿속에만 있던 검증 관점이 파일로 나오는 순간 공유 가능하고 버전 관리 가능한 자산이 됩니다.

5. 한계와 트레이드오프

한계	영향
동일 입력에 대한 일관성 확인 어려움	같은 코드를 검증해도 매번 다른 관점이 나올 수 있음
출력 품질의 프로그래밍적 강제 불가	검증 깊이가 모델 컨디션에 의존
거짓 양성 가능	문제가 아닌 것을 문제로 지적할 수 있음

가장 경계한 것은 검증 통과 = 완벽 이라는 착각입니다. 교차 검증은 “또 다른 시선”이지 최종 판정이 아닙니다. A 등급을 받았다고 안심하면 도구가 오히려 해가 됩니다. 실제로 검증에서 잡지 못한 이슈가 코드 리뷰에서 나온 적도 있습니다.

회고: 만든 것보다 쓰면서 쌓인 게 자산이다

3개월 전에는 “검증을 자동화하자”고 시작했습니다. 지금은 “검증하면서 쌓이는 경험을 어떻게 관리할 것인가”를 고민합니다.

도구는 사용하면서 진화합니다. 프로필이 그 진화의 형식이고, 검증 사례가 그 진화의 내용입니다. 만드는 것보다 꾸준히 관리하는 게 더 어렵고 더 중요했습니다.

도구가 도구 자신을 검증해서 맹점을 발견한 적도 있습니다. 4축 어디에도 보안 관점이 없었다는 발견이 그것이고, 그건 별도 글 에서 다룹니다. OWASP Top 10 을 도구 영역과 판단 영역으로 분류하고 기존 축에 어떻게 통합했는지의 의사결정 기록입니다.

---

이 글은 Claude와 함께 작업했습니다.