티스토리 뷰
목차
솔직히 저는 꽤 오래 "이 기능 만들어줘" 한 줄로 AI 코딩을 시작했습니다. 결과물이 빠르게 나오니까 좋았는데, 작업 범위가 커질수록 AI가 기존 구조를 무시하고 제멋대로 코드를 쌓는 상황이 반복됐습니다. 리서치부터 계획, 주석, 구현까지 단계를 나눠 진행하는 방식이 이 문제를 어떻게 해결하는지 직접 확인해봤습니다.
리서치 없이 시작하면 왜 무너질까
제가 AI 코딩을 처음 쓰기 시작했을 때 가장 많이 겪었던 문제가 뭔지 아십니까? 이미 프로젝트 안에 공통 컴포넌트가 있는데도, AI가 그걸 모르고 비슷한 기능을 처음부터 새로 만들어버리는 상황이었습니다. 결국 제가 다시 코드를 뒤져서 중복 로직을 정리해야 했고, 오히려 시간이 더 걸렸습니다.
이 문제의 근본 원인은 단순합니다. AI에게 코드베이스를 제대로 파악할 시간을 주지 않은 것입니다. 그래서 워크플로우의 첫 단계는 코드 리서치(Code Research)입니다. 여기서 코드 리서치란 AI가 관련 폴더, 모듈, 시스템 구조를 단순히 훑는 것이 아니라 깊이 읽고 발견 내용을 'research.md' 파일에 상세하게 기록하는 과정을 말합니다.
프롬프트를 작성할 때 "깊이", "매우 상세히", "모든 세부 사항"과 같은 단어를 반드시 포함해야 합니다. 이 단어들이 없으면 AI는 함수 시그니처 수준에서만 파악하고 넘어가 버립니다. 제 경험상 이건 AI를 사람처럼 대하는 것과 비슷합니다. 대충 설명하면 대충 이해하고, 구체적으로 요구해야 구체적으로 파고듭니다.
AI 코딩에서 가장 치명적인 실패는 문법 에러가 아닙니다. 겉으로는 멀쩡하게 돌아가는 것처럼 보이지만, ORM(Object-Relational Mapping, 데이터베이스와 객체를 연결하는 기술) 관리를 무시하거나 기존 레이어를 우회하는 구현이 훨씬 위험합니다. 여기서 ORM이란 데이터베이스 쿼리를 직접 작성하지 않고 객체 단위로 데이터를 다루게 해주는 도구를 의미합니다. 이런 문제는 한참 뒤에야 드러나기 때문에, 리서치 단계가 사전에 이를 차단하는 역할을 합니다.
계획을 MD 파일로 분리해야 하는 이유
리서치가 끝나면 바로 구현으로 넘어가고 싶은 마음이 생기는데, 저도 처음엔 그렇게 했습니다. 그 결과는 AI가 제가 원하지 않는 방향으로 아키텍처를 설계하고, 저는 그걸 뒤늦게 발견해서 처음부터 다시 하는 상황이었습니다. 계획 단계를 건너뛰면 왜 이런 일이 생기는 걸까요?
이 워크플로우에서는 'plan.md'라는 별도 마크다운 파일에 구현 계획 전체를 작성하게 합니다. 계획에는 접근 방식, 코드 스니펫(Code Snippet, 재사용 가능한 짧은 코드 조각), 수정될 파일 경로, 트레이드 오프(Trade-off, 하나를 얻으면 다른 것을 포기해야 하는 상충 관계) 등이 모두 포함됩니다. 여기서 트레이드 오프란 예를 들어 성능을 높이면 코드가 복잡해지는 것처럼, 선택 사항 사이에서 발생하는 득실 관계를 뜻합니다.
Claude Code 내장 플랜 모드 대신 직접 MD 파일을 사용하는 이유가 있습니다. 에디터에서 직접 편집할 수 있고, 인라인 메모를 바로 추가할 수 있으며, 세션이 종료돼도 파일이 프로젝트 안에 남아 있어 작업의 연속성이 유지됩니다. 채팅창 안에서만 관리하면 세션이 날아가는 순간 맥락이 사라지는데, 파일로 남겨두면 그런 걱정이 없습니다.
소프트웨어 개발 방법론에서도 설계와 구현의 분리는 오래된 원칙입니다. 출처: Martin Fowler - Continuous Integration에서도 명확한 계획 없이 이루어지는 구현이 기술 부채(Technical Debt)를 누적시킨다는 점을 강조합니다. AI 코딩에서도 이 원칙은 동일하게 적용됩니다.
- 접근 방식과 이유를 명시한 상세 설명
- 수정될 파일 경로와 코드 스니펫
- 선택지 간 트레이드 오프 분석
- 도메인 제약 조건과 고려 사항
주석 달기 사이클이 핵심인 이유
계획이 완성됐다고 바로 구현을 맡기면 될까요? 제 경험상 이 단계를 건너뛰었을 때 가장 후회가 컸습니다. AI가 작성한 plan.md를 에디터에서 직접 열어보면 "이건 내가 의도한 게 아닌데"라는 부분이 꼭 보입니다. 그걸 발견하지 못하고 구현을 시작하면, 나중에 깃(Git)을 통째로 되돌려야 하는 상황이 생깁니다.
주석 달기 사이클은 이렇게 작동합니다. AI가 plan.md를 작성하면 개발자가 에디터에서 직접 검토합니다. 잘못된 가정이 있으면 그 위치에 인라인 메모를 바로 추가합니다. 예를 들어 PUT 요청을 써야 하는 곳에 PATCH를 쓰거나, 불필요한 캐싱 로직이 들어간 경우가 있었는데, 제가 직접 해당 줄 아래에 "이건 PUT으로 변경", "캐싱 제거" 같은 메모를 달았습니다. 그리고 AI에게 다시 보내 "메모를 반영하고 업데이트해라, 아직 구현하지 마"라고 지시합니다.
"아직 구현하지 마"라는 문장이 왜 중요할까요? 이 말이 없으면 AI가 계획이 충분하다고 스스로 판단하고 바로 코드를 쓰기 시작합니다. 개발자가 검토하지 않은 결정이 코드로 굳어지는 순간입니다. 이 문장 하나로 개발자가 결정권을 유지하는 구조가 완성됩니다.
이 방식은 소프트웨어 공학에서 말하는 쉐어드 뮤터블 스테이트 패턴(Shared Mutable State Pattern)과 유사합니다. 여기서 쉐어드 뮤터블 스테이트란 여러 주체가 하나의 공유 문서를 함께 수정하며 상태를 동기화하는 방식을 의미합니다. plan.md 파일이 개발자와 AI 사이의 공유 상태로 기능하면서, 모든 결정이 그 안에서 투명하게 관리됩니다. 출처: Agile Alliance - Iterative Development에서 강조하는 반복적 검토와 수정의 원칙이 이 단계에 그대로 녹아 있습니다.
구현은 기계적으로, 방향 전환은 과감하게
계획이 완전히 검토되고 승인되면 그때서야 구현 명령을 내립니다. 이 단계에서 저는 "전부 구현해라, any 타입 쓰지 마라, 타입 체크 지속 실행해라" 같은 표준 프롬프트를 씁니다. 이 시점에서 모든 중요한 결정은 이미 끝났기 때문에, 구현 자체는 창의적이지 않고 기계적입니다. 그리고 이게 의도된 것입니다.
여기서 타입 체크(Type Check)란 코드에서 데이터 타입이 올바르게 사용되고 있는지 자동으로 검증하는 과정입니다. TypeScript 같은 환경에서는 타입 체크를 지속적으로 실행하면 런타임 에러를 사전에 잡아낼 수 있습니다. 구현 단계에서 타입 체크를 병행하면 AI가 계획에서 벗어나는 순간을 빠르게 포착할 수 있습니다.
구현이 진행되는 동안 제 역할은 설계자에서 감독자로 바뀝니다. 이때 프롬프트는 극적으로 짧아집니다. "이 함수 구현 안 했잖아", "이거 메인 앱으로 옮겨" 수준입니다. 프론트엔드 작업에서는 브라우저 테스트 중 시각적 문제가 생기면 스크린샷을 첨부해서 설명합니다. 말로 길게 설명하는 것보다 이미지 한 장이 훨씬 빠릅니다.
만약 구현 도중 잘못된 방향으로 흘렀다면, 점진적으로 고치려 하지 않습니다. 제 경험상 잘못된 기반 위에 계속 패치를 쌓으면 결국 더 큰 문제가 생깁니다. 그럴 때는 git reset이나 git revert로 통째로 되돌리고 범위를 다시 좁히는 것이 훨씬 낫습니다. 여기서 git revert란 특정 커밋 이후의 변경 사항을 취소하고 이전 상태로 돌아가는 Git 명령어를 말합니다. 되돌리는 것이 두렵게 느껴질 수 있지만, 잘못된 방향을 고집하는 것보다 훨씬 빠른 길입니다.
자주 묻는 질문
Q. 클로드 코드에서 plan.md를 직접 쓰는 게 내장 플랜 모드보다 나은가요?
A. 내장 플랜 모드는 세션이 종료되면 내용이 사라집니다. plan.md는 프로젝트 폴더 안에 실제 파일로 남기 때문에 세션이 끊겨도 작업 연속성이 유지됩니다. 에디터에서 직접 편집하고 인라인 메모를 추가할 수 있다는 점도 실무에서는 훨씬 편합니다.
Q. "아직 구현하지 마"라는 문장을 꼭 매번 써야 하나요?
A. 네, 빠뜨리면 Claude Code가 계획이 충분하다고 자체 판단하고 바로 코드를 작성합니다. 개발자가 검토하지 않은 결정이 코드로 굳어지는 것을 막으려면 이 문장이 필수입니다. 짧지만 워크플로우 전체의 주도권을 지키는 핵심 문장입니다.
Q. 컨텍스트 윈도우가 꽉 차면 세션을 새로 시작해야 하지 않나요?
A. 컨텍스트 윈도우(Context Window)란 AI가 한 번에 처리할 수 있는 텍스트의 최대 길이를 뜻합니다. 하나의 긴 세션 안에서 리서치와 계획을 쌓아왔다면, 컨텍스트가 길어져도 AI는 이미 충분한 이해를 갖고 있습니다. 결정적으로 research.md와 plan.md가 영구적인 파일로 남아 있어 세션이 길어져도 맥락이 유지됩니다.
Q. 간단한 작업도 리서치 단계를 거쳐야 하나요?
A. 간단한 작업은 리서치 단계를 건너뛰어도 됩니다. 버튼 색상 변경이나 텍스트 수정처럼 범위가 명확한 경우는 바로 계획과 구현으로 진행해도 무방합니다. 리서치가 필요한 상황은 기존 시스템과 연결된 새 기능을 추가하거나, 여러 파일에 걸쳐 영향을 미치는 변경 작업일 때입니다.
결론
이 워크플로우를 보고 나서 제가 가장 크게 느낀 것은, AI를 잘 쓰는 비결이 영리한 프롬프트가 아니라 생각하는 것과 타이핑하는 것을 분리하는 규율에 있다는 점이었습니다. 리서치는 AI의 무지한 변경을 막고, 계획은 잘못된 방향의 구현을 막으며, 주석 달기 사이클은 개발자의 판단을 코드가 쓰이기 전에 주입합니다.
앞으로 저는 새 기능을 추가할 때 리서치 → 계획 → 주석 → 구현 → 검증의 흐름을 지키면서 AI에게 무엇을 만들지는 제가 결정하고, 어떻게 만들지는 AI에게 맡기는 방식을 유지해볼 생각입니다. AI에게 코드를 잘 쓰게 만드는 것보다, 코드를 쓰기 전에 무엇을 써야 하는지를 확실하게 만드는 것이 훨씬 중요합니다.