AI에게 코드를 수정하게 하기 전에 준비해야 할 것들

TL;DR

1. 복잡도가 높은 작업은 절대 AI에게 바로 코드를 수정해달라고 하면 안된다.
2. Google 에서 발표한 Conductor 익스텐션에서 영감을 얻은 나만의 작업 루틴 spec.md → plan.md → test.md 사용법 공유

개요

요즘 긱뉴스에는 AI 얘기뿐이고, 댓글에선 전쟁이 벌어지고 있다.

AI 쇼크로 소프트웨어 업계(IBM, 넷플릭스 등) 주가가 일제히 급락하고, “개발자는 이제 끝났어” 라는 말이 들려온다.

확실한건 개발자의 역할이 ‘작성자’ 에서 ‘검수자’ 로 넘어갔다는 것.

그리고 현 사태에 대한 내 개인적인 감상을 덧붙이자면, ‘아직 개발자가 없어지기에는 부족한 점이 많다’ 에 가깝다.

이 생각이 얼마나 빠르게 구닥다리 발상이 될진 모르지만

바이브 코딩이라고 불리는 프롬프트에 의존하는 코딩의 가장 큰 문제는 ‘때때로 그 때에만 동작하는 최악의 코드를 짠다는 점’ 이다.

유지보수, 가독성, 복잡도 등은 전혀 고려하지 않고, 단순히 사용자가 지시한 내용만을 해결하기 위해 말도 안되는 코드를 써내려 간다.

사용자(검수자) 의 역량이 낮다면, 사람은 더이상 코드를 이해하려고 하지 않고, 해당 구현부는 블랙박스가 돼버린다.

잡설이 길었다.

어쨌든 최상위 요약에 남겨둔 내용이 이번 포스트에서 내가 말하고 싶은 내용이다.

자세히 하나씩 들어가 보겠다.

AI한테 코드를 맡겨도 되는건 혼자하는 사이드 프로젝트 뿐이다

까놓고 말해서, AI의 실력은 충분히 뛰어나다.

그러나 수년, 혹은 십수년간 쌓아온 복잡한 프로젝트를 AI 가 완벽하게 파악할 수 없는 노릇이다.

AI도 꼼꼼히 확인하지 않는다. 파일명 만으로 기능을 유추했다가 아예 작업을 리셋해야 하기도 하고 (파일명을 좀더 이쁘게 지었다면 불상사가 커지지 않았겠지만), 우리 프로젝트에서만 지켜지는 규칙들을 알 수 없다.

그런걸 알려주는 곳이 CLAUDE.md, Antigravity 의 Rules, Skills, 코덱스의 AGENTS.md 같은 문서다.

하지만, 정말 그것만으로 충분할까?

내 지금까지의 경험상으로는 아직이다. Gemini 3.1 Pro 도 , Claude Opus 4.6 도 아직 많이 멀었다고 생각한다.

대충 프롬프트로만, 세션 내에서만 휘발 될 수 있는 환경으로 작업을 시켰다가 그걸 고치기 위해 훨씬 많은 시간과 토큰을 사용한다.

절대 휘발되지 않게 단계를 정하고, 그 단계별 md 파일을 우리 작업공간에 두는것이 현명하다.

그런 작업 표준 모델을 노골적으로 Google에서 소개했는데, 그게 바로 작년 12월에 발표된 Gemini CLI Conductor Extension 이다.

Conductor extension

Conductor: Introducing context-driven development for Gemini CLI- Google Developers Blog

Conductor for Gemini CLI enables context-driven development. Formalize specs and plans in Markdown to control AI agents & keep code consistent.

https://developers.googleblog.com/conductor-introducing-context-driven-development-for-gemini-cli/

2025년 12월, Google이 Gemini CLI용 익스텐션인 Conductor를 발표했다.

Loading image...

Conductor는 실제로 세 단계로 동작한다.

하지만 나는 Conductor 자체를 쓰고 싶은 건 아니었다. 물론 써보긴 했는데, 커밋이 많이 쌓이고 심각할 정도로 느리다.

그래서 Conductor의 멘탈 모델만 차용해서 사용해보기로 했다. 도구가 아니라 방법론으로.

준비 단계에 시간을 많은 시간을 할애하기

핵심 원칙은 하나다.

"내가 계획을 직접 검토하고 승인하기 전까지 코드 작성은 절대 금지"

이 원칙 아래, Conductor의 스펙문서를 좀 따라하고, 내가 경험적으로 추가한 단계까지 총 다섯 단계의 워크플로우를 운용한다.

1. 기존 코드 이해하기 → spec.md

어떤 기능이든 구현하기 전에, 먼저 에이전트에게 코드베이스를 탐색하게 한다.

관련 모듈, 기존 패턴, 사용 중인 유틸리티, 의존성 구조를 파악하는 단계다.

여기서 중요한건 세션으로만 남기지 말고, 반드시 spec.md 같은 문서로 남겨야 한다는 것이다.

이름은 크게 중요하지 않다. Conductor 컨벤션을 따랐고, 그게 경험적으로 효과가 좋았던 것 같다.

솔직히 AI 도 사람이랑 똑같다. 관련 내용을 훑어보라고 하면 진짜 훑어보기만 한다.

며칠전 풀스택 업무를 진행하면서 BE 로직에 대해서 스펙을 작성해달라고 했을때 나온 잡도리내용을 증거(?)로 첨부한다.

Loading image...

Loading image...

Loading image...

Loading image...

어쨋든 중요한건, 잡도리를 잘 하다 보면 정말 프로젝트 컨텍스트를 깊이 이해하게 되고, 그 문서는 내가 지우기 전까지 새로운 세션에게 얼마든지 읽힐 수 있다는 점이다.

2. 계획 수립 → plan.md

spec.md가 배경지식 이라면, plan.md는 기획문서 에 가깝다.

디자인 패턴, 아키텍처 결정, 구체적인 코드 구현 방법과 코드 스니펫 등을 미리 작성한다.

여기서 작성한 plan.md 파일은 개발자(검수자)인 내가 직접 꼼꼼히 확인해야 한다.

→ 여기서 시간을 가장 많이 써야한다!

만약 기획/정책이 필요하다면 이부분에 대해서 프롬프트로 논의를 하고, spec.md 를 수정하고, 다시 돌아오면 된다.

# ~~ 구현 계획

> **Status**: 구현 대기
> **Created**: 2026-02-24
> **스펙 참조**: [spec.md](./spec.md) <!-- 1번에서 만들었던 그 spec.md 맞다 -->

---

## 전체 정리 

### ~~


## 제약 사항

### ~~ 


## 우선순위 & 작업 순서

<!--
  여기에서 현재 문제와 해결방안에 대해서 아직 AI가 깊게 파악하고 있는 상태가 아니라고 판단되면,
  과감히 문서를 날리고 spec.md 작성으로 돌아간다
-->
### ~~ 

## 체크리스트

- [ ] ~~
- [ ] ~~
- [ ] ~~

필요에 따라 훨씬 많은 블럭이 생길 수 있다.

여기서 중요한 것은, plan.md 를 정말 꼼꼼히 만져줘야한다.

코드 스니펫이 있다고 했을때, 그것이 우리 프로젝트 컨벤션과 부합하는지, 예시(실제 구현을 그렇게 했을떄)도 적절한지, 유닛 테스트가 바로 가능한지 등을 여기서 판단하고, 수정을 요청해야한다.

그래서 이 단계까지가 가장 중요하다.

3. 구현과 검증 → test.md

plan.md 를 내가 승인했다(혹은 승인하기로 마음먹었다)면, 여기서부터 비로소 코드를 작성하게 된다.

에이전트는 plan.md의 체크리스트를 따라가며 Phase 별로 구현을 진행한다. 이때 프로젝트의 에이전트 룰이나 스킬 문서를 참고하게 하면, 컨벤션을 벗어나는 코드가 나올 확률이 확 줄어든다.

그렇게 정해진 틀 안에서 구현이 완료되면 test.md를 작성한다. 여기에는 유저 플로우, 필요한 테스트 목록, 엣지 케이스를 먼저 정리한다.

# ~~ 테스트 명세

> **구현 참조**: [plan.md](./plan.md)
> **Status**: 테스트 대기

---

## 유저 플로우

1. 사용자가 ~~ 화면에 진입한다
2. ~~ 버튼을 클릭한다
3. 정상적으로 ~~ 가 반영된다
4. 예외 상황 시 ~~ 토스트가 표시된다

## 필요한 테스트

### Unit Tests
- [ ] ~~ 훅의 CRUD 동작 검증
- [ ] ~~ 컴포넌트의 렌더링 및 인터랙션
- [ ] ~~ 유틸 함수의 경계값 처리

### Integration Tests
- [ ] ~~ 추가 후 관련 화면에 정상 반영 확인
- [ ] 서버 에러 시 롤백 동작

### Edge Cases
- [ ] 잘못된 입력값에 대한 방어 로직
- [ ] 동시 요청 시 Race Condition 방지 확인
- [ ] 네트워크 끊김 시 UX

왜 테스트 코드를 바로 짜지 않고 이 문서를 먼저 만드느냐?

테스트도 기획이 필요하기 때문이다.

에이전트에게 "테스트 코드 짜줘" 라고만 하면, 정말 의미 없고 영양가 없는 테스트를 양산한다.

핵심 시나리오를 빠뜨리거나, 흔히 옛날 테스트코드를 짤때 흔히 하는 실수인 절대 실패할 수 없는 이미 검증된 부분만 반복 테스트하는 경우가 많다.

test.md에 내가 검증하고 싶은 시나리오를 먼저 명시하면, 에이전트는 그 목록을 기반으로 테스트 코드를 작성한다. 결과물의 퀄리티가 완전히 다르다.

2026.02.27 추가)

테스트 코드가 새로운 해자(Moat)가 되는 시대 | GeekNews

성공의 역설: 프로젝트가 성장할수록 하위 호환성과 거대한 코드베이스(The Ship of Theseus)라는 짐을 지게 됩니다. 반면 경쟁자는 기존 프로젝트의 API 규격과 문서, 테스트 코드를 AI에 학습시켜 핵심 가치만 추출한

https://news.hada.io/topic?id=27030

보면서 공감이 많이 되는 글이라 첨부한다.

이제 코드 구현은 AI가 미친듯이 뽑아내는 시대다.

정확성 확보, 유지보수, 보안 이슈, 테스트 부담을 줄이는 것이 앞으로의 개발자가 가져야할 책임이 아닐까.

4. 코드 리뷰와 QA

테스트까지 통과했으면 마지막 단계다.

여기서도 자동화에 기대지 않는다. 에이전트가 만든 코드를 내가 직접 읽는다. plan.md에서 합의한 설계 방향대로 구현됐는지, spec.md에서 파악한 기존 패턴과 어긋나는 부분은 없는지 확인한다.

이 단계에선 에이전트한테 코드리뷰를 또 시킨다. 괜찮은 지적을 해올 때가 있다.

그리고 PR을 올린다. 이때 spec.md, plan.md, test.md는 레포에 같이 남겨둔다. 동료가 리뷰할 때 ‘이게 왜 이렇게 짜여 있지?’ 라는 질문에 대한 답이 거기에 다 있다.

5. 문서 정리

작업물이 성공적으로 마무리되면 spec.md, plan.md, test.md 등의 문서를 정리한다.

삭제하진 않는다.

나중에 비슷한 작업이 생겼을 때 에이전트에게 이전 Conversation 을 읽히기위해 Inbox를 뒤지지 않아도 된다.

“이 문서 기반으로 작업했던거 말인데…” 하고 시작하면 된다.

히스토리가 쌓일수록 에이전트의 컨텍스트가 두꺼워진다.

필자는 완료된 문서는 내 이름으로 된 workspaces 디렉토리에  .archive/ 같은 폴더로 옮기고 있다.

끝맺음

이 글을 쓰면서 다시 한번 느낀 건, 옛날이건 AI 에이전트 시대이건 개발자에게 가장 중요한 능력은 문제를 정의하고 해결하는 능력이라는 거다.

물론 아는게 없으면 검수도 못하니까 개발 지식도 너무너무 중요하다.

결국 AI가 아무리 똑똑해져도, 뭘 만들어야 하는지를 정하는 건 사람의 몫이다.

그 결정을 문서화하고, 단계별로 검증하고, 최종 승인하는 과정. 이게 내가 찾은 현시점에서의 최선의 워크플로우다.

구글에서 이미 두달 전에 알려주기도 했고

특정 도구에 종속될 필요 없다. 마크다운 파일 몇 개와 "승인 전까지 코드 금지" 라는 원칙 하나면 된다.

중요한 건 도구가 아니라, 도구를 다루는 방법이다.