범용 AI 프레임워크를 검토한 뒤, 이미 쓰던 작은 스킬을 하나의 흐름으로 묶었다. 이 글은 직접 만들기로 한 이유보다 요구사항부터 PR까지 이어지는 12단계를 실제로 어떻게 운영했는지에 집중한다.

전체 흐름

 1. 작업 브랜치 준비
      ↓
 2. 요구사항 정리
      ↓
 3. 관련 코드베이스 문맥 수집 (선택)
      ↓
 4. 작업 문서 생성
      ↓
 5. 설계 리뷰 (선택)
      ↓
 6. 테스트 선행 작성
      ↓
 7. 구현
      ↓
 8. 테스트 확인과 보완
      ↓
 9. 리뷰와 정적 검증
      ↓
10. 동적 검증 (선택)
      ↓
11. 커밋과 PR
      ↓
12. 소비자에게 변경 내용 공유

파이프라인 자체가 모든 단계를 처리하지는 않는다. 다음에 할 일을 정하고, 실제 작업은 각 역할의 작은 스킬이나 에이전트에 맡긴다.

작업마다 12단계를 모두 강제한 것이 아니라, 빠뜨리기 쉬운 확인 순서만 고정했다.

코드를 쓰기 전에 대화하는 구간

2단계부터 5단계까지는 구현보다 불확실성을 줄이는 데 쓴다. 이 구간을 길게 둔 이유는 에이전트가 확인되지 않은 정보를 그럴듯하게 채워 넣는 것이 싫었기 때문이다.

요구사항을 바로 해석하지 않는다

모호한 부분이 있으면 다음 단계로 넘어가기 전에 질문하게 했다. 복잡한 작업에서는 소크라테스식 인터뷰로 답에서 다음 질문을 뽑아냈다. 당시에는 oh-my-claudecode의 deep-interview를 연결해 사용했다.

나: "프로필 조회 신청 기능을 추가해"
AI: "신청 시 알림을 보내야 하나요?"
나: "푸시 알림을 보내야 해"
AI: "수락 전에는 어느 정보까지 보여주나요?"
나: "일부 정보만 보여줘"
AI: "일부 정보의 범위를 정해볼까요?"

질문 자체가 특별한 것은 아니다. 불명확한 채로 구현 단계에 들어가지 않는 것이 규칙이었다.

필요한 경우 다른 코드베이스를 함께 읽는다

백엔드 변경이 관리 화면, 배치, 모바일 클라이언트와 연결된 경우에만 문맥 수집 단계를 실행했다. 단일 저장소 안에서 끝나는 작업이라면 건너뛴다. 선택 단계로 둔 덕분에 작은 작업까지 무겁게 만들지 않았다.

작업 문서를 기준점으로 만든다

질문과 탐색 결과는 배경, 변경 대상, 제약, 테스트 체크리스트가 있는 짧은 작업 문서로 옮겼다. 이후 구현자와 리뷰어가 같은 문서를 보게 했다. 대화에서 합의한 조건이 구현 중에 사라지는 것을 막기 위한 기준점이었다.

기술 선택은 따로 꺼내 논의한다

에이전트가 일반적으로 좋은 방법이라는 이유만으로 캐시나 새로운 추상화를 선택하는 경우가 있었다. 그 선택이 기존 코드, 운영 제약, 팀의 유지보수 방식에도 맞는지는 별개였다.

AI: "캐시 적용을 권장합니다."
나: "이 데이터는 무효화 시점이 복잡한데?"
AI: "그렇다면 캐시 없이 조회 경로를 줄이는 편이 낫겠습니다."

설계 리뷰에서는 선택한 이유, 버린 대안, 프로젝트 제약을 한 번 더 확인했다. 에이전트는 대안을 넓히고, 최종 판단은 내가 내렸다.

구현은 작업 규모에 따라 달리 돌렸다

6~8단계는 테스트, 구현, 재검증이다. 모든 작업에 같은 실행 방식을 쓰지 않았다.

규모실행 방식예시
작음현재 에이전트가 직접 구현필드 추가, 작은 설정 변경
중간구현과 검증을 반복한 기능의 여러 계층 수정
큼독립 작업을 여러 에이전트로 분리여러 모듈에 걸친 변경

파일 하나를 바꾸는데 에이전트 팀을 띄우는 것도 낭비고, 독립된 큰 작업을 한 컨텍스트에서 직렬로 처리하는 것도 비효율적이었다. 파이프라인은 구현 방법보다 먼저 작업 크기를 판단하게 했다.

테스트를 먼저 둘 수 있는 비즈니스 규칙은 테스트에서 시작했다. 구현 뒤에는 해당 테스트만 보는 데 그치지 않고 관련 테스트와 엣지 케이스를 다시 확인했다.

범용 흐름과 가장 달랐던 검증 구간

9~10단계에는 내가 실제로 놓쳤던 검증을 넣었다.

9. 리뷰와 정적 검증
   ├── 불필요한 코드와 복잡도 정리
   ├── 쿼리와 파라미터 매핑 확인
   ├── 변경 영향 범위 추적
   └── 기존 소비자와의 호환성 확인

10. 동적 검증
   ├── 로컬 서버에서 실제 API 호출
   └── 격리된 검증 환경에서 쿼리 실행

리뷰어는 변경된 파일 유형을 보고 필요한 검증만 선택했다. SQL이 없으면 쿼리 검증을 건너뛰고, API 계약이 바뀌지 않으면 호환성 검토를 생략했다. 건너뛴 이유를 남겨 “실행하지 않음”과 “잊어버림”을 구분했다.

동적 검증에서는 공개 글에 옮길 수 없는 내부 데이터나 접속 정보 대신, 격리된 로컬·개발 환경과 합성 데이터를 사용한다는 원칙을 두었다. 에이전트가 실행할 수 있는지보다 어떤 환경에서 무엇을 검증해도 되는지 먼저 정했다.

PR에서 끝내지 않고 소비자에게 연결했다

11단계는 변경 요약, 영향도, 테스트 결과를 PR에 모으는 단계다. 9단계에서 만든 결과를 다시 타이핑하지 않고 그대로 재사용했다.

API 계약이나 동작이 바뀌면 마지막 단계에서 이를 쓰는 사람에게 공유할 문서를 만들었다. 코드를 합치는 것과 변경이 전달되는 것은 다른 일이었다. 이 단계를 추가한 것은 구현은 끝났는데 소비자가 뒤늦게 변화를 아는 일을 몇 번 겪고 나서였다.

순서는 지키되 모든 단계를 강제하지 않았다

  • 문맥 수집, 설계 리뷰, 동적 검증은 선택 단계다.
  • 작은 설정 변경은 핵심 단계만 거쳐 끝낼 수 있다.
  • 테스트와 리뷰를 건너뛸 때는 한 번 더 이유를 확인한다.
  • 사용자가 마지막 단계부터 요청해도 앞선 필수 검증이 끝났는지 먼저 확인한다.

중요한 검증은 지키되 작업 크기에 맞춰 줄일 수 있어야 계속 쓸 수 있었다.

실수의 목록이 파이프라인이 됐다

12단계는 반복해서 놓친 일에서 생겼다.

쿼리 파라미터를 또 놓침       → 매핑 검증 추가
PR에 영향 설명이 빠짐         → 영향도 분석 연결
실행 결과를 직접 확인하기 어려움 → 동적 검증 추가
API 변경이 소비자에게 늦게 전달됨 → 공유 단계 추가

처음부터 12단계를 만들 필요는 없다. 반복해서 놓치는 일 하나를 먼저 자동화하고, 같은 실수가 다시 나오면 다음 확인 절차를 더했다.