신규 팀원이 합류했다. 문서는 부실하고, 코드를 짠 사람은 이미 팀을 떠났다. 이번 주 안에 뭔가를 배포해야 한다. 이 상황을 겪어본 개발자라면 안다—코드베이스 파악에 소비되는 첫 며칠이 얼마나 비효율적인지를. 그런데 지금은 이 문제를 AI로 상당 부분 해결할 수 있다. 단, '어떻게 쓰느냐'가 핵심이다.
낯선 코드베이스, AI를 독서 파트너로 쓰는 법
dev.to에 올라온 실전 가이드("How to Use AI to Understand an Unfamiliar Codebase")는 AI를 단순 자동완성이 아니라 구조화된 독서 파트너로 활용하는 4단계 워크플로우를 제시한다. 핵심은 추상에서 구체로 이동하는 순서다.
- 디렉터리 구조 먼저 — 파일 내용 없이 폴더 트리만 붙여넣고 아키텍처 패턴과 진입 포인트를 물어라. AI가 "이 구조만으로 답할 수 없는 질문"까지 뽑아주는 것이 포인트다.
- 파일 단위 구조화 분석 — 요약이 아닌 Purpose / Inputs·Outputs / Dependencies / Side effects / Gotchas 형식으로 요청하라. 특히 Gotchas 섹션은
getUser()가 실제로 로그를 쓰는 것처럼 이름과 동작이 어긋나는 지점을 잡아낸다. - 요청 흐름 추적 — 연관된 파일 2~3개를 한꺼번에 붙여넣고 특정 트리거(POST /api/orders 등)의 실행 경로를 추적시켜라. 과거엔 오후 내내 걸리던 콜 체인 추적이 10분 안에 가설 수준의 지도가 된다.
- New Contributor Cheat Sheet 생성 — 위 단계를 거친 뒤 AI에게 시스템 개요, 핵심 모듈 목록, 반드시 읽어야 할 파일 3~5개, 비명시적 컨벤션, 도메인 용어 사전을 담은 레퍼런스 문서를 만들게 하라. 팀 내부 위키에 붙여두면 다음 신규 입사자가 같은 삽질을 반복하지 않는다.
이 워크플로우가 효과적인 이유는 간단하다. 프롬프트가 구체적일수록 결과물의 품질이 올라간다. 막연한 질문에 막연한 답이 돌아오는 건 AI의 문제가 아니라 질문 설계의 문제다. 그리고 한 가지를 잊으면 안 된다—AI 출력은 검증해야 할 가설이지, 그대로 믿을 사실이 아니다.
Cursor로 FPGA까지: AI 코딩 어시스턴트의 실전 범위
AI 코딩 어시스턴트의 적용 범위가 어디까지인지 궁금하다면, Tang Nano 9K FPGA 개발에 Cursor IDE(Claude 기반)를 적용한 사례를 보자. Verilog 문법, 핀 배치, IP 코어 파라미터처럼 도메인 지식이 집약된 영역에서 AI를 어떻게 쓰는지 잘 보여준다.
핵심은 Knowledge Base를 먼저 만드는 것이다. 핀 어사인먼트, IP 코어 스펙, 자주 발생하는 실수를 담은 knowledge_base.md를 프로젝트에 두고, 모든 프롬프트에 이 컨텍스트를 바탕으로 요청한다. "HDMI 코드 만들어줘"가 아니라 "50MHz 입력 클럭에서 rPLL로 74.25MHz 픽셀 클럭을 만들고, OSER10으로 TMDS 직렬화, HDMI_CK=IO_17, HDMI_D0=IO_18 핀으로 출력하는 탑레벨 Verilog 모듈"처럼 구체적으로 요청해야 쓸 수 있는 결과가 나온다.
이 경험이 팀 온보딩에 주는 시사점은 분명하다. 도메인 지식이 없으면 AI가 생성한 코드를 검증할 수 없다. Cursor가 그럴듯한 Verilog를 뽑아내도, PLL VCO 범위가 스펙을 초과하는지, 타이밍 클로저가 가능한지는 개발자가 데이터시트를 보고 확인해야 한다. AI 어시스턴트 도입이 도메인 학습을 대체하지 않는다—오히려 도메인 지식을 갖춘 사람이 AI를 더 잘 쓴다.
에이전트가 짠 코드, 플랜 핑거프린트로 잠가라
코드베이스 이해와 생성 속도가 빨라지면 다음 문제가 떠오른다. 검토한 변경과 실제로 적용된 변경이 같은가? 이 질문이 trivial해 보이지만, 에이전트가 IaC 변경을 제안하는 환경에서는 치명적인 문제가 된다.
dev.to의 "You Can't Review an Agent. You Can Review a Plan."은 이 문제를 정확히 짚는다. PR 리뷰는 통과했지만, apply 시점에 상태(state)가 변경되어 검토한 플랜과 다른 플랜이 실제로 실행된 사례—아무것도 깨지지 않았지만, 그건 운이 좋았던 것이다.
저자가 제안하는 해법의 핵심은 신뢰의 단위를 에이전트가 아닌 특정 플랜으로 이동시키는 것이다. 에이전트는 다음 PR을 직전 PR의 품질과 무관하게 동일한 자신감으로 열기 때문에, 에이전트를 신뢰하는 건 구조적으로 불가능하다. 반면 저장된 플랜에 핑거프린트(plan hash + findings + signature)를 묶고, apply가 해당 핑거프린트와 일치하는 승인 레코드 없이는 실행을 거부하도록 설계하면, 검토된 것만 배포된다는 보장이 생긴다.
이 구조는 4개 레이어로 요약된다: Author(무엇을 원하는가) → Compiler(어떻게 구현하는가) → Observer(지금 무엇이 사실인가) → Evaluator(허용 가능한가). Author와 Compiler는 얼마든지 자유롭게 동작해도 된다—Evaluator를 통과하지 않으면 프로덕션에 닿지 않기 때문이다.
특히 Observer 레이어를 가볍게 여기지 말아야 한다. 대부분의 팀이 이 레이어를 "대시보드 몇 개"로 축소하지만, 에이전트와 외부 툴이 API를 통해 인프라를 변경하는 환경에서 Observer가 보지 못하는 아웃오브밴드 변경은 전체 하네스의 맹점이 된다. Terraform 상태, 클라우드 프로바이더 인벤토리, 드리프트 감지, 감사 로그—이것들이 에이전트가 변경을 제안하기 전에 현실 기반을 제공해야 한다.
팀 온보딩에서 배포 안전성까지: 세 가지를 엮으면
세 가지 실전 경험을 팀 온보딩 워크플로우 관점에서 엮으면 하나의 흐름이 보인다.
- 진입(Entry): AI 구조화 프롬프팅으로 낯선 코드베이스의 멘탈 맵을 빠르게 확보한다. 첫날 무작위로 파일을 열어보는 대신, 디렉터리 구조 → 핵심 파일 → 요청 흐름 → Cheat Sheet 순서로 접근한다.
- 생성(Generation): 도메인 컨텍스트를 Knowledge Base로 명문화하고 AI 코딩 어시스턴트와 반복적으로 정제한다. AI가 뽑은 코드는 언제나 데이터시트·스펙·테스트로 검증한다.
- 검증(Validation): 에이전트가 제안한 변경은 플랜 핑거프린트로 잠근다. 검토된 플랜만 배포되도록 CI 게이트를 설계하고, 에이전트의 자신감이 아닌 구조가 품질을 보장하게 만든다.
이 흐름에서 팀 리드가 설계해야 할 것은 도구 선택보다 경계 설정이다. AI가 자유롭게 움직일 수 있는 영역(코드 생성, 문서화, 분석)과 반드시 인간이 검증해야 하는 경계(도메인 정합성, 배포 승인)를 명확히 나누지 않으면, 속도는 AI가 올려줘도 사고는 팀이 고스란히 치른다.
신규 팀원 온보딩을 AI로 가속하는 것과 에이전트가 인프라를 변경하는 것—둘은 표면상 다른 문제처럼 보이지만, 근본적으로 같은 질문을 던진다. AI가 만든 결과물을 어떤 구조로 검증할 것인가? 이 질문에 답하지 않은 채 도구만 도입하면, 온보딩 시간이 줄어드는 대신 사후 디버깅 시간이 늘어난다.