나는 지금 다가올 완전 자동 AI 주도 개발을 향한 검증을 거듭하고 있다.

나는 15년의 소프트웨어 엔지니어 경험이 있다. 최근에는 프로덕트의 구상부터 인프라 설계·구현, Web 애플리케이션의 아키텍처 설계·구현, CI/CD, IaC, 테스트 설계·구현까지,

소프트웨어 엔지니어링의 모든 공정을 개발 리드 겸 구현자로서 딜리버리(Delivery)해냈다. 이것이 가능했던 이유는 AI 에이전트(AI Agent)를 전제로 한 체계가 있었기 때문이다.

최근 몇 달 사이, AI 주도 개발 주변의 '부품'들이 급속도로 갖춰지고 있다. CI/CD·IaC를 통한 토대 정비, Spec.md를 기점으로 한 설계·테스트 플로우, 리뷰 배분의 사고방식, 규약 설계, 고위험 영역의 구분——각각은 개별적으로 이야기되는 경우가 많지만, 이를 하나로 묶어 체계로서 나열된 정보는 아직 적다고 느낀다.

본 기사에서는 이러한 부품들을 '제로에서 시작하는 사람'이 헤매지 않고 쌓아 올릴 수 있도록 공정에 따라 정리한다.

TL;DR

• AI 주도 개발은 「토대(CI/CD·IaC) → 설계·테스트(Spec.md 기점) → 운용(리뷰 배분·규약·고위험 영역 특정)」이라는 3층 구조로 쌓아 올리면 길을 잃지 않는다.
• 리뷰는 「전부 읽기」에서 「실패 시의 영향 범위에 따라 농담(濃淡)을 두기」로 발상을 전환할 필요가 있다.
• 테스트 Green은 안심 재료이지 보증이 아니다. 단체 테스트(Unit Test)의 스코프 외(결선·환경 의존)를 별도 레이어로 자동화해 두어야 한다.

0. 전제 인식: 무엇이 변하는가

AI 에이전트를 본격 도입하면 PR 수와 코드량은 수 배에서 10배 규모로 증가한다. 이러한 양적 변화를 먼저 공유해 두지 않으면, 이후에 설명할 토대 정비나 리뷰 배분의 필요성이 '과도한 준비'처럼 보일 수 있다. 우선 「지금까지의 방식이 양적으로 더 이상 통하지 않는다」라는 전제를 두는 것이 체계화의 출발점이 된다.

1. 토대를 먼저 자동화한다 (CI/CD·IaC)

AI가 코드를 대량으로 생성하는 단계에 이르러서 토대를 정비하면 늦는다. CI/CD 파이프라인·IaC(Terraform 등)는 AI 주도 개발을 시작하기 전에 준비해 두어야 할 토대다.

목표는 단순하다. 개발자가 개별적인 배포 작업이나 인프라 구축에 신경 쓰지 않고 「개발에 집중할 수 있는」 상태를 먼저 만드는 것이다. 이 토대가 있어야 비로소 후술할 테스트 Green 게이트(섹션 6)나 고위험 영역의 리뷰(섹션 8)를 「얹을 수 있는」 상태가 된다. 반대로 말하면, CI/CD가 정비되지 않은 상태에서 테스트 게이트만 만들어도 기능하지 않는다. AI 주도 개발의 효율화는 생성 속도의 문제가 아니라, 생성된 것을 받아낼 토대가 갖춰져 있는가의 문제다.

2. 과제로부터 Spec.md로 떨어뜨리기

과제나 요구사항을 그대로 AI에게 전달하는 것이 아니라, 먼저 기능 요구사항으로서 언어화하는 공정을 거친다. 이 성과물을 여기서는 Spec.md라고 부른다.

Spec.md가 없는 상태에서 AI에게 구현을 의뢰하면, 기대치가 「암묵적 합의」에 의존하게 되어 후속 공정(테스트 설계·구현)의 어긋남을 초래하는 온상이 된다. 여기서 모호함을 없애두면 후속 공정의 정밀도가 올라간다는 위치를 갖는다. 무엇을 만들 것인가·만들지 않을 것인가의 경계선을 명문화하는 공정이라고 이해하면 쉬울 것이다. [1]

3. Spec.md로부터 테스트 설계·테스트 구현으로

Spec.md를 기준으로 테스트 케이스를 설계하고 인간이 리뷰한다. 단체·결합 테스트(Unit/Integration Test)를 AI에게 구현하게 한다.

여기서 중요한 것은 역할 분담이다. 테스트 설계는 인간(또는 프론티어 모델)이 수행하고, 구현은 AI에게 맡긴다는 분리를 의식한다. 테스트 설계까지 포함하여 AI에게 맡겨버리면, Spec.md의 해석 차이가 테스트에도 그대로 전파되어 「테스트는 통과하고 있지만 검증해야 할 것을 검증하지 못하고 있는」 상태를 감지할 수 없게 될 리스크가 있다.

4. E2E는 Playwright + GitHub Actions로 자동화

단체·결합 테스트는 「코드가 사양대로 작성되었는가」를 검증하지만, 「실제로 브라우저상에서 동작하는가」는 별개의 레이어 문제다. 이 층을 Playwright[2]로 시나리오화하여 GitHub Actions[3]의 CI 파이프라인에 통합한다.

주요 동선(로그인, 주요 기능의 일련의 조작 등)에 집중하여 E2E를 자동화해 둠으로써, 인증·CORS·스토리지 경로와 같은 「단체 테스트의 스코프 외」에서 발생하기 쉬운 결선 버그를 본방 투입 전에 감지할 수 있다. 이는 섹션 10에서 다룰 「테스트 Green 사고 정지」에 대한 예방책이 되기도 한다.

5. 리뷰 배분의 설계 사상

AI가 생성하는 PR(Pull Request) 수와 코드량이 몇 배 규모로 늘어나면, "모든 PR의 모든 행을 인간이 읽는다"는 전제는 더 이상 성립하지 않습니다. 여기서 발상의 전환이 필요합니다.

참고할 만한 것이 Mitchell Hashimoto가 실천하고 있는 "이 코드는 오래 살아남을 것인가, 아니면 곧 버려질 것인가"라는 판단 기준입니다. 다만 소프트웨어의 특성상 많은 코드가 오래 사용될 것을 전제로 작성되기 때문에, 이 기준을 그대로 적용하기는 어려운 경우도 있습니다. 대신 사용할 수 있는 것이 **"이 변경이 실패했을 때의 영향 범위"**라는 기준입니다. 이 수정이 망가졌을 때 피해가 어디까지 확산되는지에 따라 리뷰의 강도를 결정합니다.

덧붙여, 이 "영향 범위"를 누가 어떻게 판정할 것인가라는 프로세스 자체는 아직 확립된 방법이 있는 것은 아닙니다. 실제 운용에서는 PR을 연 사람의 안목에 의존하는 부분이 남아 있습니다.

이 부분은 엔지니어링 경험이 빛을 발하는 지점이며, 앞으로도 남아있을 포인트라고 생각합니다.

6. 테스트 Green 게이트를 운용하기

Spec.md를 기준으로 만들어진 테스트를 통과하는 것을 PR 머지(Merge)의 필수 조건으로 만듭니다. "테스트가 Green이 아니라면 머지할 수 없다"라는 게이트를 설치함으로써, 리뷰의 일부를 이곳으로 이양합니다.

이는 GitHub의 브랜치 설정에서 수행하는 것이 좋습니다.

다만 주의해야 할 점은, 테스트가 Green이라는 것과 테스트 자체가 올바르게 설계되어 있다는 것은 별개의 문제라는 점입니다. 패치 대상 지정 실수, 구버전 사양 추종 누락, 환경 의존성 간과, 너무 느슨한 어설션(Assertion) 등 "테스트 코드 자체의 결함"으로 인해 Green이 나오는 케이스는 실제로 발생할 수 있습니다. 테스트 Green 게이트는 테스트의 품질이 담보되었을 때 비로소 기능하는 메커니즘임을 이해해야 합니다.

7. 규약(CLAUDE.md)은 얇게 유지하기

AI 에이전트에게 읽힐 규약은 너무 두껍게 만들지 않는 것이 중요합니다. 지시사항이 길어지면 긴 컨텍스트의 중간 부분이 무시되기 쉬운 "Lost in the Middle" 현상이 발생하여, 오히려 규약 위반이 늘어날 가능성이 있습니다.

규약은 "두꺼울수록 더 잘 지켜진다"는 발상이 아니라, 필요 최소한으로 압축합니다. 또한, 과거에 겪었던 실패 패턴을 반복하지 않기 위한 메커니즘(Harness)도 규약 파일에 함께 두면 유효합니다.

다음 글에서 정리하고 있습니다.

8. 고위험 영역을 먼저 특정하기

"구문 체크는 통과하지만, 의미적으로 틀리면 피해가 크다"라는 성질을 가진 영역은 미리 뽑아둘 가치가 있습니다. 대표적인 예가 Terraform[4] 등의 IaC(Infrastructure as Code)입니다.

예를 들어, 로드 밸런서의 라우팅 설정이 의도와 반대로 되어 있어도 terraform validate나 plan 단계에서는 감지할 수 없으며, apply를 하고 나서야(혹은 본 운영 후에) 발견되는 케이스가 있습니다. 유사한 성질은 IAM 정책, DB 마이그레이션 SQL, API 사양(OpenAPI 정의)[5] 등에도 적용됩니다. 이러한 영역은 AI에 의한 자동 생성에만 전적으로 맡기지 말고, 작성자 이외의 사람이 "의도대로인지" 읽는 공정을 의도적으로 남겨둡니다.

9. 자동화할 수 없는 공정 분리하기

모든 것을 AI와 CI에 맡길 수는 없습니다. DB 마이그레이션의 상태 보정, IAM 역할(Role)의 수동 생성(권한 분리 설계상 의도적으로 자동화하지 않는 경우), 사내 승인 플로우, 인증 세션 획득 등 "아직 자동화되지 않았거나" 혹은 "애초에 자동화해서는 안 되는" 공정이 존재합니다.

제로 베이스에서 시작하는 단계에서 이를 리스트화해 두면, "왜 여기는 자동화되어 있지 않은가"를 매번 설명해야 하는 수고를 줄일 수 있습니다. 이유(기술적 제약인지, 설계상의 의도인지)를 명기해 두는 것이 중요합니다.

10. 함정에 선제 대응하기: 테스트 Green 사고 정지

테스트 Green은 "안심감"을 주지만, 그것은 "해당 테스트가 검증하는 범위 내에서 망가지지 않았다"는 확인일 뿐, "기능 전체가 올바르게 작동하고 있다"는 보장이 아닙니다.

전형적인 실패 패턴은 다음과 같은 구조입니다.

테스트 Green
↓
"확인했다"라는 안심감이 발생
...

이를 운용상의 의식 고취에만 의존하면 동일한 사고가 재발하므로, 시스템으로서 강제하는 것이 바람직합니다. 구체적으로는 배포 파이프라인의 최종 단계에 주요 엔드포인트에 대한 통신 확인을 필수화하거나, 섹션 4에서 도입한 Playwright의 E2E를 단체 테스트(Unit Test)로 감지하지 못했던 이력이 있는 경로로 한정하여 확충하는 등의 대응을 고려할 수 있습니다.

11. 시작 순서 (로드맵)

지금까지의 내용을 3층 구조로 정리하면 다음과 같습니다.

토대가 없다면 설계 · 테스트 층은 기능하지 않으며, 설계 · 테스트 층이 모호한 상태라면 운영 층의 리뷰 배분 판단 기준도 흔들립니다. 처음부터 시작하는 경우에는 이 순서를 건너뛰지 않고 쌓아 올리는 것이 멀리 돌아가는 것처럼 보여도 실제로는 지름길이 됩니다.

판단 기록이 남지 않는 문제와, Agentic RAG라는 접근 방식

AI가 대량의 코드를 생성하는 환경에서는 구현 속도와는 별개로, 의사결정 기록이 따라가지 못하는 문제가 발생합니다. 코드는 남지만, "왜 그 접근 방식을 선택했는가", "다른 수단을 채택하지 않은 이유는 무엇인가"와 같은 배경은 남지 않습니다. 이는 구현자의 머릿속에 있으며, 구두로 전달되고, 사람이 바뀔 때마다 희미해집니다. AI에 의해 개발 속도가 올라갈수록 이러한 의사결정의 공백은 넓어집니다.

지금까지 써온 Terraform만을 엄격하게 리뷰한다는 판단도, 테스트 설계의 경위도, 실제로는 여러 번의 실패를 거쳐 사후적으로 굳어진 것입니다. 그 배경이 공유되지 않는다면, 새로운 멤버는 코드를 읽어도 "왜 이렇게 되어 있는지"를 추적할 수 없습니다. 이러한 문제는 어느 팀에서나 일어날 수 있는 구조적인 문제라고 생각합니다.

이 문제에 대해 채택한 접근 방식이, 설계 판단을 ADR 형식으로 체계화하고, 그것을 RAG의 지식 베이스(Knowledge Base)로서 에이전트가 자율적으로 검색 · 참조할 수 있도록 한 Agentic RAG 챗봇입니다.

**ADR (Architecture Decision Record)**은 어떤 설계 선택을 "무엇을 결정했는가"뿐만 아니라 "왜 그 선택지를 골랐는가", "다른 무엇을 검토하고 기각했는가", "그 트레이드오프 (Trade-off)는 무엇인가"까지 포함하여 기록하는 경량 문서 형식입니다. 코드나 구현 로그와 달리, 의사결정의 문맥 그 자체를 저장하는 것이 목적입니다.

이 챗봇은 ADR 문서군을 지식 베이스로 보유하며, 팀 멤버가 "왜 이 구성인가", "이 설계 판단의 배경은 무엇인가"라고 자연어로 문의하면 관련 ADR을 찾아 답변합니다.

정보가 개인에게 종속(Silo)된 상태로 남아 있으면, "왜 이 설계인가"라는 질문은 특정 인물에게 계속 집중됩니다. 그 인물의 스위칭 코스트 (Switching Cost)는 쌓여가며, 개발 속도가 올라갈수록 부하도 증가합니다.

Wiki나 문서 관리 도구에 판단 기록을 정리하는 방법도 검토했지만, 모두 "작성한 사람이 검색해서 읽는다"는 전제이며 동일한 문제를 안고 있습니다. RAG로서 구조화함으로써, 기록하는 측은 판단이 생겨난 타이밍에 ADR을 쓰기만 하면 되고, 참조하는 측은 자연어로 문의하기만 하면 된다는 비대칭적인 운영 코스트를 실현할 수 있습니다.

요약

AI 주도 개발은 단일 시책 (CI/CD, 테스트 자동화, 규약 정비 등)을 개별적으로 도입하는 것만으로는 체계가 되지 않습니다. 이번에 정리한 것은 다음의 3가지 포인트입니다.

• 토대 (CI/CD · IaC)를 먼저 정비함으로써, 개발자가 개발 그 자체에 집중할 수 있는 상태를 만든다
• Spec.md를 기점으로 한 설계 · 테스트 플로우를 거침으로써, AI에 대한 기대치의 편차를 상류 단계에서 해소한다
• 리뷰 · 규약 · 고위험 영역의 특정 · 미자동화 공정의 분류를 "운영 층"으로 위치시켜, 테스트 Green에 대한 과신을 방지한다

이것들을 시계열에 따라 쌓아 올리는 것이, AI 주도 개발을 처음부터 시작할 때의 하나의 유형이 될 것이라고 생각합니다.

참고 문헌

• Mitchell Hashimoto의 X 게시물 (에이전트 생성 코드의 리뷰에 대하여): https://x.com/mitchellh/status/2055390179687600139
• GitHub Spec Kit (Spec.md 기점의 개발 플로우): https://github.com/github/spec-kit
• Playwright (E2E 테스트 프레임워크): https://playwright.dev/
• GitHub Actions (CI/CD 파이프라인): https://github.com/features/actions
• Terraform (IaC 도구, HashiCorp): https://developer.hashicorp.com/terraform
• OpenAPI Initiative (API 사양 정의 표준): https://www.openapis.org/

게시물은 개인적인 견해를 바탕으로 하며, 소속 조직을 대표하지 않습니다.

Discussion