범용 AI 개발 프레임워크 대신 프로젝트 전용 파이프라인을 만든 이유

AI 코딩 에이전트가 코드를 바로 쓰기 전에 계획하고, 테스트하고, 리뷰하게 만드는 프레임워크들을 찾아봤다. Superpowers의 TDD·리뷰 흐름과 Ouroboros의 질문 중심 스펙 정리는 내가 겪던 문제를 정확히 겨냥하고 있었다.

처음에는 이 중 하나를 실무 흐름에 그대로 넣으려 했다. 방향은 배울 만했지만, 실제 작업에는 프로젝트에 맞춰 직접 만든 작은 절차가 더 잘 맞았다.

범용 프레임워크가 해결하려는 문제

에이전트에게 기능을 요청하면 요구사항을 충분히 확인하지 않은 채 구현부터 시작하기 쉽다. 테스트는 마지막에 붙고, 리뷰 없이 완료를 선언하기도 한다.

프레임워크	접근
Superpowers	계획, TDD, 구현, 리뷰를 워크플로우로 강제
Ouroboros	질문을 반복해 구현 전에 스펙을 명확히 함

공통점은 코드 작성 전에 생각할 시간을 구조로 만든다는 것이다. 이 방향 자체에는 동의했다.

문제는 “테스트를 먼저 써라” 다음이었다. 오래 운영한 시스템에서는 무엇을 테스트해야 하는지가 프로젝트 맥락에 묶여 있었다.

범용 프레임워크는 “검증하라”고 말할 수 있지만, 어느 파일에서 무엇을 찾아 어떤 환경에서 확인할지는 알지 못한다. 새 프로젝트에서는 일반적인 흐름만으로도 충분할 수 있다. 레거시와 여러 소비자가 얽힌 프로젝트에서는 그 다음 한 단계가 더 중요했다.

범용 지침
"쿼리를 변경했으면 테스트한다"

프로젝트에 맞춘 절차
1. 변경된 SQL과 파라미터 매핑을 확인한다.
2. 호출 경로를 역추적한다.
3. 영향을 받는 API를 찾는다.
4. 실행계획과 대표 케이스를 검증한다.
5. 응답 호환성을 확인한다.

내게 필요했던 것은 원칙을 더 늘리는 일이 아니라, 이미 알고 있는 프로젝트의 확인 사항을 빠뜨리지 않는 절차였다.

파이프라인은 사용 중인 기술과 코드 구조를 알고 있었다. “통합 테스트를 써라”에서 멈추지 않고, 어떤 경계를 실제 객체로 둘지와 어떤 외부 의존성만 대체할지까지 정할 수 있었다.

반복되는 실수를 만날 때마다 작은 스킬을 추가했다.

매퍼 파라미터를 또 놓침     → 쿼리 검토 절차 추가
PR에서 영향도 설명이 빠짐   → PR 생성 단계에 영향도 추가
실행 결과를 확인하기 어려움 → 동적 검증 단계 추가

외부 프레임워크의 설정 구조를 우회할 필요가 없었다. 내가 겪은 문제를 내가 읽을 수 있는 파일에 바로 반영했다.

단계를 켜고 끌 때 “프레임워크가 요구하니까”가 아니라 실제 실패 경험을 근거로 판단할 수 있었다. 이 이해도는 예상 밖의 상황에서 특히 중요했다.

범용 프레임워크는 좋은 설계 사례이자 빠른 출발점이었다. 새 프로젝트에 바로 적용하거나, 내 파이프라인에 없는 아이디어를 찾을 때 유용했다.

다만 레퍼런스와 완성품은 달랐다. Superpowers에서 테스트와 리뷰를 분리하는 아이디어를 가져오더라도, 실제 테스트 기준은 프로젝트의 코드와 운영 방식에 맞춰 다시 써야 했다.

범용 프레임워크 = 문제를 바라보는 공통 골격
특화 파이프라인 = 내가 반복해서 놓친 맥락을 담은 실행 절차

직접 만든다고 모든 단계를 한 파일에 넣지는 않았다. 요구사항 정리, 문맥 수집, 구현, 검증, 리뷰를 작은 스킬로 나누고 전체 흐름에서는 순서만 연결했다. 필요한 단계만 부를 수 있어 작은 변경에 무거운 절차를 모두 적용하지 않아도 됐다.

범용 프레임워크는 출발점으로 삼고, 실제 실행 절차는 내가 반복해서 놓친 검증에 맞췄다.