코딩 AI에게 구현시키기 전에 코드베이스에서 찾아야 할 것

코딩 AI에게 기능을 맡기기 전, “버튼 하나 추가해 줘”라고 바로 말하고 싶을 때가 있습니다. 문장도 짧고 결과도 빨리 보고 싶으니까요. 그런데 코드베이스는 빈 캔버스가 아닙니다. 이미 폴더의 역할, 상태를 다루는 방식, 데이터를 오가는 길, 그리고 지켜야 할 약속이 쌓여 있습니다. 그걸 찾지 않고 구현부터 시키면 AI는 열심히 일하면서도 엉뚱한 서랍에 양말을 넣을 수 있습니다 (정리한 사람만 더 피곤해지는 그 서랍 말입니다).

흔한 오해: 요구사항만 주면 위치도 방법도 알겠지

AI가 코드를 잘 생성한다는 사실과, 이 저장소의 맥락을 이미 안다는 사실은 다릅니다. 요구사항은 “무엇을 만들지”를 알려 줍니다. 반면 코드베이스 조사는 “어디에 두고, 어떤 기존 방식을 따라야 하는지”를 알려 줍니다.

그래서 구현 전 조사는 저장소를 길게 소개하는 발표가 아닙니다. 새 코드가 들어갈 자리, 재사용할 구조, 참고할 파일, 보존할 제약을 찾는 증거 수집입니다. 없는 패턴을 있는 척 추정하지 않는 것도 이 과정의 중요한 결과입니다. 코드베이스가 조용하면 “여기에는 뚜렷한 관례가 확인되지 않았다”라고 말하는 편이 낫습니다. AI가 탐정 모자를 썼다고 해서 벽장 뒤에 없는 비밀 통로까지 만들 필요는 없으니까요.

구현 전에 찾을 다섯 가지 증거

1. 구조와 자리

먼저 프로젝트의 구조(architecture and structure) 를 봅니다. 기능 관련 코드가 어떤 디렉터리에 모이는지, 화면·도메인·데이터 계층이 어떤 식으로 나뉘는지, 새 파일이 자연스럽게 들어갈 위치가 어디인지를 확인합니다.

여기서 얻는 답은 단순히 “파일 목록”이 아닙니다. 새 기능을 기존 구조 안에 놓을 수 있는 기준입니다. 가구를 들이기 전에 방의 문과 동선을 재는 일과 비슷합니다. 멋진 책장도 문을 통과하지 못하면 일단 난감하잖아요.

2. 닮은 기능

다음은 유사 구현(analogous features) 입니다. 이미 비슷한 일을 하는 화면, 기능, 서비스, 또는 모델을 찾습니다. 그 파일들은 추상적인 조언보다 훨씬 가까운 참고점이 됩니다. 어떤 파일을 기준으로 새 코드를 작성할지, 기존 패턴을 어디까지 재사용할지 결정하는 근거가 되기 때문입니다.

단, 닮았다는 이유만으로 복사하면 안 됩니다. 유사 구현은 정답지가 아니라 현재 저장소 안의 지역 선례입니다. 같은 모양의 컵이라도 뜨거운 국을 담는지 차가운 물을 담는지에 따라 확인할 것이 달라집니다 (주방에서 자주 배우는 겸손입니다).

3. 상태 관리 방식

세 번째는 상태 관리(state management) 방식입니다. 상태 관리는 화면이나 기능이 무엇을 기억하고, 그 값이 어디에서 어떻게 바뀌는지를 다루는 방식입니다. AI가 이 흐름을 모르고 기능을 더하면, 값은 생겼는데 누가 소유하는지 알 수 없는 상황이 생길 수 있습니다.

따라서 현재 프로젝트에서 상태를 어디서 만들고 읽고 갱신하는지, 비슷한 기능은 어떤 패턴을 쓰는지 먼저 확인합니다. 이 조사는 “새 값을 어디에 둘까?”뿐 아니라 “기존 상태 흐름을 어떻게 보존할까?”에 답하게 합니다.

4. 데이터 계층

네 번째는 데이터 계층(data layer) 입니다. 데이터를 읽고 전달하고 보관하는 경로가 어떻게 나뉘는지 확인합니다. 기존 코드가 저장소와 서비스 같은 역할을 구분하고 있다면, 새 기능도 어느 계층을 거쳐야 하는지 그 구조에서 찾아야 합니다.

상태와 데이터는 서로 이어지지만 같은 질문은 아닙니다. 화면이 값을 누가 들고 있는지와, 그 값이 어디서 와서 어디로 가는지를 따로 살피면 책임을 한 파일에 몰아넣는 일을 줄일 수 있습니다.

5. 제약과 관례

다섯 번째는 제약과 관례(constraints and conventions) 입니다. 문서화된 규칙, 이미 사용 중인 이름 짓기, 파일 배치, 도구 사용 방식처럼 새 작업이 지켜야 할 약속을 찾습니다. AI가 보기에는 선택지가 여러 개여도, 저장소에는 이미 선택된 길이 있을 수 있습니다.

이 단계는 거창한 새 설계를 만들기 위한 시간이 아닙니다. 오히려 넓은 리팩터링이나 추측성 구조 변경을 피하고, 확인된 관례를 따라 작은 변경을 만들기 위한 안전장치입니다. “새로우면 멋지다”보다 기존 맥락과 맞는다가 먼저입니다.

AI에게 요구할 출력은 ‘요약’보다 ‘근거 있는 다음 행동’입니다

조사 결과를 받을 때 “구조를 요약해 줘”에서 끝내지 말고, 구현에 필요한 답을 요청해 보세요.

1. 새 코드는 어느 위치에 두는 것이 기존 구조와 맞는가?
2. 어떤 유사 구현과 파일을 참고해야 하는가?
3. 상태와 데이터는 현재 어떤 경로를 따르는가?
4. 지켜야 할 문서화된 제약과 관례는 무엇인가?

이 질문들은 AI를 만능 설계자로 만들기보다, 현재 저장소에서 발견한 사실을 바탕으로 계획하게 합니다. 이 글에서 다루는 조사 흐름은 Flutter와 Dart 저장소에 한정됩니다. 프로젝트 구조와 패키지 메타데이터, Dart 파일, 해당 생태계의 상태 관리·저장소·서비스 패턴을 직접 살펴보는 것이 핵심입니다.

구현 속도는 조사와 싸우지 않습니다

조사는 느린 준비 운동처럼 보일 수 있습니다. 하지만 필요한 증거를 먼저 모으면 AI가 낸 코드가 이 저장소에 맞는지 판단할 근거가 생기고, 왜 그 위치와 방식이 선택됐는지도 설명할 수 있습니다. 한 번 둘러보고 넣은 레고 블록은 맞는 홈에 들어가지만, 눈 감고 끼운 블록은 나중에 발바닥을 기다립니다.

다음 구현 요청에서는 다섯 가지 증거를 먼저 찾아보세요. 프로젝트 구조, 상태 관리, 데이터 계층, 유사 구현, 문서화된 관례. 그리고 발견하지 못한 것은 발견하지 못했다고 남겨 두세요. 그 정직한 한 줄이야말로 AI와 함께 코드를 바꿀 때 가장 든든한 시작점입니다.