Adaptive SDD를 실무 프로젝트에 다시 적용하면서 손본 것들
2026.09.21 게시
이 시리즈는 작성 시점의 기록이다. 현재 기준은 Adaptive Agentic SDD 저장소에 정리해두었다.
![]()
개인 프로젝트에서 고도화했던 Adaptive SDD를 실무 프로젝트에 다시 적용해봤다.
처음 SDD를 쓰기 시작한 건 실무 쪽이었다. 그때는 규모가 작았고, 그 뼈대를 개인 프로젝트로 가져가서 멀티 Agent 병렬 개발, 작업 격리, 검증 Gate까지 붙여 Adaptive Agentic SDD로 정리했다.
Agent에게 바로 코드를 짜게 하지 않고, 현행 분석·변경 설계·검증 기준을 먼저 고정한 뒤 구현과 리뷰로 넘어간 운영 방식을 정리한 글이다.
Link - Agent에게 바로 개발시키지 않기 — 실무에서 AI 개발을 안정화한 방식
멀티 Agent 병렬 개발, 작업 격리, 검증 Gate를 실제로 운영하면서 Adaptive Agentic SDD로 정리한 글이다.
Link - 멀티 Agent 개발을 실제로 운영해보고 정리한 것들
이번에는 그걸 다시 실무 프로젝트로 가져왔다. 작업을 나누고, Agent에게 구현과 독립 리뷰를 맡기고, Git SHA를 기준으로 다음 작업을 넘기는 방식은 그대로다. 다만 환경이 달라지니 손볼 곳이 보였다. 제일 큰 차이는 제품 코드를 바꿀 때마다 Agent가 알아서 빌드하고 테스트를 돌리는 구조가 아니었다는 점이다.
처음에는 모델을 어떻게 배치할지 많이 봤다. 비용도 줄이고 싶었고, 작업에 맞는 모델을 쓰는 것도 중요하다고 생각했다.
그런데 막상 돌려보니 모델 선택보다 먼저 보이는 게 있었다.
부모 Agent가 이미 확인한 내용을 서브 Agent가 다시 찾고, 리뷰 결과를 받고도 다음에 뭘 해야 할지 다시 해석하는 부분이다. 사람이 직접 실행해야 하는 검증도 비슷했다. 실행할 내용만 넘겨서는 부족했고, 어떤 결과를 돌려받을지도 정해야 했다.
결국 이번에 손본 건 대부분 “무엇을 넘기고, 무엇을 돌려받을지”였다.
이번 글은 그 과정에서 바꾼 것들을 정리한 기록이다. 사례는 외부 API 연동 작업 하나로 일반화했다.
모델을 고르는 절차부터 줄였다
모델마다 비용과 처리 능력이 다르니 역할에 맞게 고르는 일은 필요하다.
그런데 추천하고, 선택을 기다리고, 이미 정한 내용을 다시 확인하는 과정까지 붙으니 모델 고르는 것 자체가 일이 됐다.
그래서 이슈를 제시할 때 모델과 추론 수준을 한 줄로 추천하고, 따로 지정하지 않으면 그대로 진행하도록 바꿨다. 현재 Agent 구성이 충분하면 모델을 맞추겠다고 호출을 추가하지 않는다. 사용자가 명시적으로 지정한 구성만 별도로 존중한다.
선택 절차를 줄이고 나니, 일을 넘기는 쪽이 더 보였다.
부모 Agent는 변경 파일, 직접 호출 관계, 관련 설정, 이미 실행한 검사 결과를 알고 있다. 그런데 서브 Agent에게 작업 이름과 넓은 경로만 던지면, 그쪽에서는 같은 내용을 처음부터 다시 찾는다.
그렇다고 부모의 대화를 통째로 넘기기도 애매했다. 구현하면서 내린 판단과 설명, 앞선 리뷰 결과까지 같이 들어간다. 독립적으로 문제를 찾아달라고 하면서 구현자의 설명부터 잔뜩 읽히는 셈이다.
그래서 무엇을 넘길지부터 정리했다.
요청할 내용과 돌려받을 결과를 같이 정했다
| 단계 | 전달 내용 |
|---|---|
| 1. 리뷰 요청 부모 Agent → 서브 Agent |
리뷰 대상, 읽을 범위, 확인된 사실, 검토할 질문, 반환 형식 |
| 2. 리뷰 결과 반환 서브 Agent → 부모 Agent |
판정, 차단 지적, AC별 결과, 확인하지 못한 범위 |
| 3. 다음 작업 결정 부모 Agent |
코드 수정 / 사람이 결정 / 근거 추가 조사 |
독립 리뷰 요청은 다섯 부분으로 나눴다.
| 구분 | 넣을 내용 |
|---|---|
| 리뷰 대상 | 이슈 버전, 리뷰 단계, 기준 SHA, 스냅샷과 동일성 확인 명령 |
| 읽을 범위 | 요구사항, 안전 규칙, 변경 파일, 확인에 필요한 직접 참조 |
| 확인된 사실 | 실제 실행한 명령과 결과 |
| 검토할 질문 | 인수 조건(AC)별 확인 사항, 실패 경로, 계약이 깨질 수 있는 조건 |
| 반환 형식 | 판정, 차단 지적, 근거 위치, AC별 결과, 확인하지 못한 범위 |
읽을 범위는 출발점이다. 주장을 확인하려면 호출자나 설정을 더 봐야 할 수도 있고, 그건 열어둔다. 대신 관련 계층 전체나 이전 버전 전문을 처음부터 다 넣지는 않는다.
확인된 사실과 구현자의 판단도 구분했다.
어떤 명령을 실행했고 결과가 어땠는지는 넘긴다. 하지만 “충분히 안전하게 구현했다”는 구현자의 판단이다. 구현자의 설명에 덜 의존해야 하는 리뷰에는 앞선 리뷰의 판정도 넘기지 않았다.
처음 만든 요청 양식도 한 번에 통과하지는 못했다. 양식 자체를 먼저 리뷰에 넘겼더니 안전 규칙과 검증 문서가 입력에서 빠졌고, 리뷰 종류에 따라 어떤 정보를 제외해야 하는지도 불명확하다는 지적이 나왔다. 그 부분을 보완했다.
입력을 줄이려다 리뷰에 필요한 내용까지 빼면 안 됐다.
결과를 받는 형식도 같이 정했다. 실제 양식을 줄이면 이 정도다.
판정: PASS / FAIL / BLOCKED / UNVERIFIED
차단 지적:
- 위치
- 문제가 발생하는 조건
- 위반한 AC 또는 계약
- 근거
AC별 결과:
- AC ID / 판정 / 근거
비차단 지적과 남은 위험:
확인하지 못한 범위:
파일 수정 여부:
부모 Agent는 이 결과를 보고 다음 작업을 정해야 한다. 코드를 고쳐야 하는지, 사람이 결정할 일인지, 판단할 근거부터 더 찾아야 하는지가 구분돼야 했다.
무엇을 돌려받을지 정하니 요청에 넣어야 할 내용도 더 명확해졌다.
검증 문서 초안은 구현을 맡은 Agent가 자체 검토 직후 작성하도록 했다. 부모는 AC가 빠지지 않았는지, 정적 확인과 실행 확인을 잘 나눴는지 보고 결과를 합친다. 구현 내용을 알고 있는 쪽이 초안을 쓰도록 역할을 나눈 것이다.
첫 적용 기록은 이랬다
당시 작업 완료 기록에 남아 있던 수치다. 원본 실행 로그를 다시 집계한 건 아니다.
앞선 연동 코드 변경 리뷰는 Opus로 약 11만–14만 토큰, 도구 호출 21–34회, 4–6분이었다. 새 요청 양식을 처음 적용한 문서 리뷰는 Sonnet으로 약 10.1만 토큰, 14회, 2.4분이었다. 작업도 모델도 달라서 양식의 효과로 계산할 수는 없고, 기록된 토큰 수가 청구 비용과 같지도 않다.
그보다 눈에 띈 건 재검토였다.
같은 작업에서 문구를 보완한 뒤 진행한 두 번의 재검토는 각각 도구 호출 3회에 28초, 38초였다. 이때는 지적을 낸 리뷰어를 그대로 이어서 쓰고, 바뀐 파일과 새 스냅샷, 수정한 지적을 중심으로 넘겼다.
최초 리뷰와 수정 확인은 필요한 내용이 달랐다. 처음에는 독립적으로 검토하게 하고, 수정 뒤에는 이전 지적과 바뀐 부분을 이어서 확인하게 했다. 이 재검토는 새 독립 리뷰로 세지 않았다.
다음에는 같은 작업과 같은 모델로 비교해봐야겠다. 특히 서브 Agent가 무엇을 다시 조사하는지, 부모가 결과를 받고 무엇을 다시 물어보는지 보고 싶다.
SHA를 넘기는 것만으로는 부족한 경우가 있었다
SHA를 기준으로 작업을 넘기는 방식은 개인 프로젝트에서도 쓰고 있었다.
이번에는 어느 시점에 무엇을 고정할지 더 나눴다. 승인받은 설계, 구현을 시작한 기준, 리뷰한 파일, 사람이 실행한 코드가 전부 같은 “현재 버전”은 아니었기 때문이다.
| 시점 | 남길 기준 |
|---|---|
| 1. 설계 승인 후 | 승인된 이슈 버전과 설계. Medium 이상은 설계 체크포인트 커밋 |
| 2. 리뷰 요청 전 | 기준 커밋, 대상 파일의 내용·상태, 이슈의 목표·AC·설계를 묶은 스냅샷 저장 |
| 3. 리뷰 종료 후 | 스냅샷을 다시 비교해 리뷰한 대상과 현재 대상이 같은지 확인 |
| 4. 사람이 실행할 때 | 실행 요청 시점의 대상 ID, 마지막 코드 변경 후 재기동 여부 |
| 5. 최종 정리 전 | 현재 변경에 연결된 리뷰와 검증 결과가 여전히 유효한지 확인 |
각 단계마다 전부 커밋한다는 뜻은 아니다. 리뷰를 요청할 때는 아직 커밋하지 않은 변경이나 새 파일도 있다. SHA만으로는 그 상태를 지정할 수 없어서, 파일 해시와 이슈에 적힌 목표·AC·설계를 묶는 스냅샷 도구를 만들었다.
진행 상태나 검증 결과를 적는 건 승인 내용의 변경으로 보지 않는다. 목표, AC, 설계가 달라질 때만 감지한다. 리뷰 전에 저장하고, 리뷰가 끝난 뒤와 최종 정리 전에 다시 비교한다.
이것도 실제로 쓰면서 한 번 손봤다.
다른 작업을 커밋해서 HEAD만 이동한 경우가 있었다. 리뷰한 파일도, 이슈의 목표·AC·설계도 그대로였다. 그런데 스냅샷은 달라졌다고 나왔고, 정리를 진행하려면 새 기준으로 스냅샷을 다시 떠야 했다.
그래서 비교 결과를 세 가지로 나눴다.
identical
HEAD, 대상 파일 상태·내용, 이슈의 목표·AC·설계가 같음
head-only
HEAD만 이동했고 대상 파일 상태·내용과 이슈의 목표·AC·설계는 같음
changed
대상 파일 상태·내용 또는 이슈의 목표·AC·설계가 달라짐
head-only면 기존 리뷰 대상 ID와 결과를 유지한다. 실제 내용이 바뀌었을 때만 영향받는 부분을 다시 검토한다.
설계 자체를 바꾼 경우도 있었다. 외부 API 주소를 설정으로 옮기면서 처음에는 해당 연동 전용 설정을 추가하려고 했다가, 기존 설정·매핑 구조를 재사용하는 쪽으로 바꿨다.
이때는 이슈 버전을 올리고 설계 체크포인트도 새로 남겼다. 이전 설계가 리뷰를 통과했어도 바뀐 설계까지 통과한 건 아니니까.
반대로 Small 작업은 설계 체크포인트 커밋을 생략했다. 승인된 이슈 버전으로 구현하고, 완료 확인 뒤 최종 커밋에 근거를 남기는 것으로 줄였다.
스냅샷이 확인해주는 건 리뷰한 대상이 지금 대상과 같은지까지다. 무엇을 리뷰할지 정하는 일과 리뷰 자체는 여전히 필요하다.
사람이 실행해야 하는 검증은 문서가 길어졌다
이번 적용에서는 제품 코드를 바꿀 때마다 Agent가 빌드와 테스트를 돌리고 결과까지 받는 흐름을 전제하지 않았다. 외부 API나 DB를 확인하는 일부 작업은 사람이 직접 실행해야 했다.
사람이 IDE에서 빌드하고 개발 환경에서 실행한 기록은 있고, 워크플로 보조 도구의 단위 검사도 돌렸다. 다만 제품 변경마다 자동으로 검증 결과를 받는 구조는 아니었다.
이 부분을 문서로 넘기려니 적을 게 많아졌다.
실행자가 다시 조사하지 않고 따라 하려면 준비 조건, 호출이나 쿼리, 사용할 값, 확인할 결과, 중단 조건이 있어야 했다. 데이터가 바뀌는 작업이라면 부수효과와 되돌리는 방법도 필요했다.
실행이 끝나고 무엇을 돌려받을지도 정해야 했다. “정상입니다”만 받아서는 기대한 결과와 실제 결과를 비교할 수 없다.
그래서 검증 문서를 역할별로 나눴다.
| 구역 | 내용 |
|---|---|
| 한눈에 보기 | 실행할 항목과 돌려줄 값 |
| 실행 절차 | 실행자가 따라 할 순서와 준비 조건 |
| 결과 반환 | 관측값을 기록할 형식 |
| 사용자 결정 | 사람이 판단하거나 선택할 사항 |
| Agent 판정 | 기대 결과와 비교 기준 |
실행자에게 PASS나 FAIL을 고르라고 하지는 않았다. HTTP 상태, 건수, 핵심 필드 값, 실행 시각, 재기동 여부를 돌려받고, 기대값과 비교하는 건 Agent가 한다.
문서 전체는 길어졌지만, 실행자가 전부 읽어야 하는 구조는 피했다.
서브 Agent에게 일을 넘길 때와 크게 다르지 않았다. 받는 쪽이 사람이라는 차이만 있었다. 실행에 필요한 내용을 넘기고, 다음 판단에 쓸 결과를 돌려받아야 했다.
검증 문서도 같이 리뷰해야 했다
문서를 만들었다고 끝은 아니었다. 적힌 절차로 실제 변경을 확인할 수 있는지도 봐야 했다.
요구사항 기준 코드 리뷰에 검증 문서를 같이 넘기고, 테스트 케이스(TC)에 대한 질문을 추가했다.
- 이번 변경이 빠졌거나 잘못 구현돼도 이 TC는 통과할 수 있나?
- 지금 코드에서 실제로 호출되는 진입점으로 실행할 수 있나?
- 적어둔 외부 호출과 부수효과가 실제 절차와 맞나?
- TC끼리 준비 조건이 충돌하지 않고, 확인하려는 요구사항을 직접 확인하나?
실제 외부 API 연동 작업에서는 요구사항 리뷰가 검증 문서의 로그 확인 항목 누락을 찾았다. 별도 코드 리뷰에서는 잘못된 입력이 의도한 오류 처리 경로를 벗어나, 정해둔 오류 응답이 나오지 않는 문제를 찾았다. 둘 다 수정하고 재검토했다.
이후 사람이 개발 환경에서 실행해 정상 요청의 200 응답과 건수, 잘못된 입력에 대한 고정된 400 응답, 확인 대상 로그 결과를 돌려줬다. 받은 결과는 해당 TC에 연결했다. 설정 구조를 바꾼 후속 작업에서도 다시 빌드하고 재기동한 뒤 실제 호출을 확인했다.
확인한 범위는 그 호출과 로그까지다. 상세 조회, 인증 정보 교체, 동시 호출, DB 실패 같은 조건은 실행하지 않았고, UNVERIFIED로 남겼다. 이후 가이드를 정리할 때도 그 범위를 구분했다.
코드를 수정하면 영향받는 TC의 이전 결과는 이력으로 남기고 재실행한다. 결과를 본 뒤 기대값을 바꾸는 경우에도 이전 기준을 지우지 않고, 변경 이유와 회차를 남긴다.
필요 없는 문서는 다시 줄였다
사람이 실행할 내용을 자세히 적어야 한다고 해서, 모든 작업에 긴 검증 문서가 필요한 건 아니었다.
실행 확인이 필요 없는 문서 변경에도 전체 양식을 붙이면 빈칸만 늘어난다. 실행 절차도 없고, 돌려받을 값도 없고, 사용자가 결정할 것도 없는데 항목을 채우게 되는 식이다.
그래서 정적 확인만 필요한 작업은 AC별 근거와 “실행 TC 0개”만 남기는 최소 형식을 허용했다. 실행 확인이 필요한데 TC를 만들지 못한 경우는 다르다. 그건 확인이 필요 없는 게 아니라 아직 확인하지 못한 것이므로, 사유를 남겨야 한다.
이번에 줄인 건 모델 선택 절차, Small의 설계 체크포인트, 실행할 게 없는 검증 문서다. 반대로 리뷰 요청에 넣을 내용, 리뷰 대상이 바뀌었는지 확인하는 절차, 사람이 돌려줄 결과 형식은 더 자세히 정했다.
문서를 무조건 짧게 만드는 쪽으로는 정리하기 어려웠다. 실행자가 다시 물어봐야 할 내용이 빠져 있으면 짧아도 부족한 문서다. 그렇다고 이번 작업에 필요 없는 빈 항목까지 남길 이유도 없었다.
검증 문서가 실행 결과를 대신해주지도 않는다. 무엇을 실행하고 무엇을 돌려줄지 정해두는 것이고, 실제로 확인한 범위는 실행 결과로 남겨야 한다. 다음 세션에서 이어받을 때도 그 구분이 있어야 했다.
일단은 이렇게 바꿔서 계속 써보려고 한다. 다음에는 서브 Agent가 같은 내용을 얼마나 다시 찾는지, 결과가 빠져서 다시 질문하는 일이 얼마나 생기는지, 이전 리뷰와 검증 결과를 어디까지 그대로 쓸 수 있는지 보려고 한다.
양식을 잘 채우는지만 보지 말고, 실제로 다시 묻고 다시 조사하는 일이 줄었는지도 봐야겠다.
관련 글과 방법론: