AI가 코드를 작성할 때의 문제점
Claude와 같은 AI가 코드 작업을 할 때, 몇 가지 문제가 반복됐다.
설계 없이 바로 구현에 들어가면 아키텍처 문제나 엣지 케이스를 놓치기 쉽고, 설계 결함은 구현 중간에 발견될수록 수정 비용이 기하급수적으로 늘어났다.
기분 탓인지 모르겠지만, 한 AI만 가지고 진행하면 blind spot이 남는다는 것도 문제였다. 거기다 복잡한 설계 결정과 단순한 코드 작성을 전부 고성능 모델로 처리하면 비용이 너무 높았다.
이 문제를 해결하기 위해 pin-plate 프로젝트에서 두 가지 커스텀 Claude Code 스킬을 개발했다: tiki-taka와 opus-sonnet.
일단 이 게시글에선 tiki-taka에 대한 설명만 할 예정이다.
Tiki-taka: 설계 리뷰 자동화
왜 만들었나
복잡한 기능을 개발할 때, AI가 혼자 설계·구현하면 아키텍처 문제를 놓치는 경우가 많았다. 코드를 다 짜고 나서 발견하면 또 토큰 소모를 해서 수정해야하고 작성된 코드가 병목이 될 수도 있다고 생각했다. 설계 단계에서 미리 잡자는 게 목적이다.
특히 이런 상황에서 효과적이다:
- 변경해야 할 파일이 6개 이상인 작업
- 새로운 기능 추가 (기존 코드 탐사가 필요한 경우)
- 아키텍처 변경 (여러 계층에 영향이 가는 경우)
- 복잡한 상태 관리 (여러 스토어·쿼리가 얽혀 있는 경우)
동작 방식
tiki-taka는 설계 → 리뷰 → 구현 3단계로 진행된다.
실행되면 .claude/plans/tiki-taka 폴더 안에 ${날짜}-${설계건} 폴더가 생성된다. Phase 1에서 plan.md가 만들어지고, 이를 기반으로 Phase 2로 진입하여 Codex가 계획서를 검토한다.
검토 결과는 codex-1.md로 저장되고, 이를 바탕으로 Claude가 다시 검증·반박하고 claude-1.md로 저장된다. 양측 모두 LGTM이 나오면 바로 구현으로 들어간다.
Phase 1: 설계 초안
Claude가 계획서를 작성한다. 변경·생성할 파일 목록, 각 파일의 작업 범위(인터페이스, 타입, 함수 시그니처), 예상되는 엣지 케이스와 에러 처리, 성능·보안 고려사항을 담는다.
Phase 2: 티키타카 리뷰 루프
Codex는 계획서를 객관적으로 검토하고, pin-plate 프로젝트 컨벤션(Server Components, 훅 순서, 네이밍 등) 준수 여부, 누락된 엣지 케이스와 타입 안전성 문제를 짚는다. 그리고 LGTM 또는 NEEDS_CHANGES로 결론 낸다.
Claude는 Codex의 의견을 분석해서, 타당한 지적이면 계획서를 수정하고, 불필요하거나 틀린 지적이면 근거를 들어 반박한다. 마찬가지로 LGTM 또는 NEEDS_CHANGES로 응답한다.
양측 모두 LGTM이 나올 때까지 반복한다. 최대 3라운드. (Pro 요금제를 쓰고 Codex는 무료라, 최대한 적게 돌게 제한을 뒀다. 요금제 높은걸 쓰면 10번정도 돌게 해도 될 것 같다.)
Phase 3: 구현
양측 합의가 끝나면, 검증된 설계를 기반으로 코드를 작성한다.
적용 기준
단, 모든 작업에 다 돌리진 않는다. 아래에 해당하면 tiki-taka를 쓰지 않는다:
- 변경 파일 5개 이하로 완결되는 작업
- 버그 수정 (원인 파악 완료, 범위 한정된 경우)
- 단순 스타일 변경 (CSS, 디자인 토큰, Vanilla Extract)
- 문서 수정 (README, 주석, 마크다운)
- 명백히 단순한 작업 (변수명 변경, 한 줄 수정 등)
처음엔 제약 없이 돌렸는데, 간단한 작업에서도 Codex가 리뷰하는 상황이 생겼다. 불필요한 토큰이 낭비되고, 1분이면 될 작업이 10분으로 늘어났다. 그래서 위 조건을 기준으로 제약을 걸었다.
뭐가 좋은가
코드를 짜기 전에 문제를 잡으니까 리팩터링 비용이 줄어들고, Claude와 Codex 두 관점이 교차하면서 한쪽이 놓칠 수 있는 사각지대가 줄어든다. 설계가 미리 정해진 상태에서 구현하면, "뭘 만들지"를 고민하지 않고 "어떻게 만들지"에만 집중할 수 있다는 것도 좋았다.
물론 내가 정답은 아니다. 일단 나는 1인 개발로 기획, 디자인, 개발을 하고 있기 때문에 여러 AI와 함께 검증을 하는게 안정적으로 프로젝트를 관리할 수 있다고 판단했다.
계속 사용하다보면 더 좋은 방법이 나타나지 않을까 생각 든다.
