Whiteboard가 던지는 질문, AI의 설계도를 어디까지 믿을까

핵심 요약

• AI가 구현을 맡는 환경에서는 IDE를 설계를 이해하고 검토하는 곳으로도 생각해 볼 수 있습니다.
• 설계를 시각화하면 구조를 이해하기 쉽지만, 실제 코드가 제대로 동작하는지까지 보장하지는 않습니다.
• AI가 만든 코드와 설명에는 같은 잘못된 전제가 깔려 있을 수 있습니다.
• 설계 설명에서 실제 구현과 테스트 결과를 함께 확인할 수 있어야 코드 리뷰에 도움이 됩니다.

코드를 직접 편집하지 않는 IDE는 얼핏 모순처럼 들립니다. 하지만 AI 코딩 에이전트가 구현을 맡는다면, 사람에게는 설계와 변경 이유를 이해할 수 있는 화면도 중요해집니다. Whiteboard를 보며 생각해 볼 지점도 여기입니다. AI의 설명이 코드를 이해하는 데 도움이 되는지, 설명을 읽은 것만으로 검증까지 마쳤다고 착각하게 되는지 살펴봐야 합니다.

코드를 쓰는 화면 다음에는 무엇이 필요할까

IDE는 코드 작성과 실행, 오류 추적을 한곳에서 처리하는 통합 개발 환경입니다. 개발자가 직접 코드를 입력한다면 편집기가 중심이 되는 게 자연스럽습니다.

그런데 AI 에이전트에 “로그인 기능을 추가해 주세요”라고 맡겼다고 해보겠습니다. 어떤 파일에 몇 줄이 추가됐는지 확인하는 것만으로는 충분하지 않습니다. 사용자 정보를 어디에 저장하고, 접근 권한을 어디서 검사하는지도 알아야 합니다.

이때는 파일 목록과는 조금 다른 화면이 필요할 수 있습니다. 요청이 들어온 뒤 어떤 과정을 거쳐 응답으로 돌아가는지 보여주는 설계도가 도움이 되겠죠.

그렇다면 코드를 직접 편집하지 않는 도구도 쓸모가 있습니다. 이 도구를 평가할 때 살펴볼 것은 편집 기능을 없앴다는 사실보다 검토에 필요한 정보를 얼마나 잘 보여주느냐입니다.

화살표 하나가 감추는 구현의 차이

설계도에 다음과 같은 흐름이 있다고 해보겠습니다.

사용자 요청 → 권한 확인 → 데이터 조회

구조는 쉽게 이해됩니다. 하지만 이 그림만으로는 권한 확인을 제대로 구현했는지 알 수 없습니다.

로그인 여부만 확인하는 것과 해당 데이터의 소유자인지까지 확인하는 것은 다릅니다. 확인에 실패했을 때 실행이 멈추는지도 살펴봐야 합니다. 그림에서는 이런 차이가 모두 ‘권한 확인’이라는 상자 하나에 가려질 수 있습니다.

시각화는 세부 사항을 덜어내므로 읽기 쉽습니다. 그런데 코드 리뷰에서는 그렇게 덜어낸 세부 사항이 중요할 때가 있습니다.

설계도를 읽을 때도 의도한 구조와 구현된 동작을 구분해야 합니다. “여기서 권한을 검사합니다”라는 설명은 어디를 확인해야 하는지 알려줍니다. 그곳에서 검사를 올바르게 하는지까지 입증해 주지는 않습니다.

AI의 설명이 자연스러울수록 놓치기 쉬운 것

AI에게 코드를 작성하게 한 뒤, 같은 AI에게 그 코드의 설계를 설명해 달라고 할 수 있습니다.

이때 설명과 코드가 서로 잘 맞더라도 안심하기는 이릅니다. 둘 다 같은 잘못된 전제에서 출발했을 수 있기 때문입니다.

예를 들어 AI가 “로그인한 사용자는 모든 문서를 읽어도 된다”고 가정했다고 해보겠습니다. 코드는 로그인 여부만 검사합니다. 설명에는 “인증된 사용자만 접근할 수 있도록 보호했습니다”라고 적힐 수 있습니다.

문장은 그럴듯하고 코드와도 모순되지 않습니다. 하지만 실제 요구사항이 “자신의 문서만 읽을 수 있다”였다면 코드도 설명도 핵심을 놓친 셈입니다.

그래서 코드와 설명이 일치한다는 이유만으로 리뷰를 끝내기는 어렵습니다. 요구사항을 기준으로 다른 사용자의 문서에 접근하는 상황을 시험해야 합니다. 설명이 맞아 보이는 것과 요구사항을 충족하는 것은 따로 확인해야 합니다.

좋은 설계 화면은 확인할 곳을 알려줍니다

제가 이런 도구에서 기대하는 것은 다이어그램을 본 뒤에도 검토를 이어갈 수 있는 기능입니다. 설명을 읽다가 의문이 생기면 그 근거를 바로 확인할 수 있어야 합니다.

도구를 살펴볼 때는 다음 세 가지를 확인하고 싶습니다.

• 설계도의 요소에서 해당 기능을 구현한 코드로 이동할 수 있는가.
• 변경 전후를 비교해 데이터 흐름이나 접근 권한이 달라진 부분을 찾을 수 있는가.
• 동작을 설명하는 곳 옆에서 관련 테스트와 실행 결과를 확인할 수 있는가.

예를 들어 “권한 없는 요청을 차단한다”는 설명을 누르면 검사 코드와 실패 상황을 다룬 테스트가 함께 보이는 방식입니다. 테스트가 통과했더라도 어떤 조건에서 시험한 결과인지까지 확인할 수 있어야 합니다.

오픈소스 도구를 평가할 때도 소스를 공개했는지와 함께 설명이 근거로 어떻게 이어지는지 살펴봐야 합니다. 도구 자체의 코드를 볼 수 있다는 장점과 도구가 내놓은 설명의 근거를 쉽게 확인할 수 있다는 장점은 서로 다르기 때문입니다.

Whiteboard를 계기로 IDE가 사람이 코드를 이해하고 판단하는 일을 어떻게 도울 수 있을지 생각하게 됩니다. AI의 설계 설명은 검토를 시작할 때 유용할 수 있습니다. 다만 변경을 승인하려면 “이렇게 동작합니다”라는 설명을 뒷받침할 근거까지 확인할 수 있어야 합니다.