AI 코딩 툴 제대로 쓰는 법 - 계획 없이 코드 짜면 망합니다

 

 

AI 코딩 도구, 여러분은 어떻게 사용하고 계신가요?

 

아마 대부분은 이렇게 하실 거예요.

"이 기능 만들어줘" → AI가 코드 쭉 작성 → 오류 뜨면 다시 물어보기 → 반복...

 

그런데 이 방식, 조금만 복잡한 기능이 나오면 금방 무너지기 시작합니다.

AI가 엉뚱한 방향으로 코드를 잔뜩 짜놓고, 수습하다 보면 오히려 시간이 더 걸리는 경험...

한 번쯤 겪어보셨죠?

 

오늘은 개발자 Boris Tane이 Claude Code를 9개월 동안 쓰면서 정착시킨 워크플로우를 소개해 드릴게요.

핵심은 딱 하나입니다.

 

"계획이 완전히 확정되기 전까지는 절대 코드를 짜게 하지 않는다"

 

 

1단계: 먼저 충분히 읽고 분석하라 (Research)

 

새로운 기능을 만들기 전, Claude Code에게 먼저 관련 코드를 깊게 읽고 이해하게 시킵니다.

 

그냥 "읽어봐"가 아니라, 이렇게 요청하는 거예요.

 

"이 폴더를 깊게 읽고, 어떻게 동작하는지 완전히 이해한 다음, 분석 내용을 research.md 파일에 정리해줘"

 

여기서 포인트는 두 가지예요.

 

"깊게", "완전히" 같은 단어를 꼭 써야 합니다.

이 말이 없으면 AI는 대충 훑고 넘어가거든요. 마치 시험 전날 교과서를 "그냥 눈으로만" 읽는 것처럼요.

 

그리고 결과를 파일로 저장하게 해야 합니다.

채팅창에 답변만 받으면 나중에 확인하기 어렵고, AI도 그 내용을 기억 못할 수 있어요.

파일로 남겨두면 내가 직접 읽어보고 "이 부분은 잘못 이해했네" 하고 수정 요청을 할 수 있습니다.

 

이 단계가 중요한 이유가 있어요.

AI 코딩의 가장 큰 실패 원인은 문법 오류가 아니라, 기존 시스템을 무시한 코드를 만드는 거거든요.

이미 있는 캐시 기능을 모르고 새로 만들거나, 기존 함수와 충돌하는 코드를 짜는 식이죠.

Research 단계가 이걸 막아줍니다.

 

 

그럼 새로운 프로젝트라면 어떻게 해야 할까요?

- 우선 만들고 싶은 앱의 요구사항을 문서로 정리해서 읽게 합니다.

- 또한 참고할 유사 오픈소스 프로젝트를 제공하고 "이 레포 구조 참고해서 분석해줘"라고 요청합니다.

- 사용할 라이브러리/프레임워크 문서를 제공하고 "Next.js + Prisma 조합으로 만들 건데, 이 스택의 일반적인 구조를 분석해줘"라고 요청합니다.

- 잘 만들어진 유사 구현체 코드를 붙여넣고 참고하게 합니다.

 

 

2단계: 코드 말고 계획서를 먼저 받아라 (Planning)

 

Research 내용을 직접 읽고 확인한 후, 이제 구현 계획을 요청합니다.

 

"이 기능을 만들 건데, 코드 말고 plan.md 파일에 구체적인 구현 계획을 작성해줘. 실제 코드 스니펫도 포함해서."

 

여기서도 중요한 게 있어요.

Claude Code에 내장된 플랜 모드가 있긴 한데, 그것보다 직접 .md 파일을 만드는 게 훨씬 낫습니다.

 

왜냐구요? 내가 그 파일을 직접 수정할 수 있거든요! 이게 핵심입니다.

 

 

3단계: 계획서에 메모를 달아가며 수정한다 (Annotation Cycle)

 

이 단계가 이 워크플로우에서 가장 독특하고 가장 효과적인 부분이에요.

 

Claude가 plan.md를 작성하면, 에디터로 열어서 내가 직접 메모를 추가합니다.

 

예를 들면 이런 식이에요.

 

- AI가 선택적(optional)으로 표시한 파라미터 옆에 → "not optional (필수야)"

- AI가 PUT 방식을 쓰려는 부분에 → "아니, 이건 PATCH 방식으로 해야 해"

- 불필요한 섹션에 → "이 부분 통째로 빼줘, 캐싱 필요 없어"

 

메모 달기가 끝나면 Claude에게 보냅니다.

 

"파일에 메모 몇 개 추가했어. 그 메모들 반영해서 계획서 업데이트해줘. 아직 코드 짜지 마."

 

이 "아직 코드 짜지 마" 라는 말이 정말 중요합니다.

이 말이 없으면 AI가 계획이 충분하다고 판단하는 순간 바로 코드를 짜기 시작하거든요.

 

이 메모-수정 사이클을 1~6번 반복합니다. 내가 만족할 때 까지요.

 

이 방법이 왜 좋냐면, 채팅창에서 "3번 항목에서 그 방식은 틀렸어요, 왜냐면..." 이렇게 긴 설명을 쓰는 것보다, 그냥 파일에서 해당 부분에 직접 메모를 다는 게 훨씬 정확하고 빠르기 때문이에요.

 

계획서가 완성되면 마지막으로 이걸 요청합니다.

 

"계획에 단계별 할 일 목록(todo list)을 추가해줘. 아직 코드 짜지 말고."

 

이 체크리스트가 나중에 구현하면서 어디까지 완료됐는지 한눈에 확인할 수 있게 해줘요.

 

 

4단계: 이제 한 번에 다 만들어라 (Implementation)

 

계획이 완벽하게 다듬어졌다면, 이제 구현 명령을 내립니다.

 

"전부 구현해줘. 각 작업이 완료될 때마다 plan.md에 완료 표시해줘.

모든 단계가 끝날 때까지 멈추지 말고. 불필요한 주석 달지 말고, 타입 체크 계속 실행해줘."

 

이 명령 하나에 중요한 내용이 다 담겨 있어요.

 

- "모든 단계가 끝날 때까지 멈추지 말고" → 중간에 "이렇게 할까요?" 물어보지 않게

- "plan.md에 완료 표시" → 진행 상황을 파일로 추적

- "타입 체크 계속 실행" → 오류를 마지막이 아닌 중간중간에 잡기

 

이 단계에서 구현은 "지루해야 정상" 입니다.

창의적인 결정은 이미 계획 단계에서 다 끝났거든요. 구현은 그냥 기계적으로 실행하는 것!

 

 

결론: AI 코딩의 핵심은 "계획 먼저"

 

단계	할 일	핵심 포인트
1. Research	코드 깊게 분석, research.md 저장	"깊게", "완전히" 강조 필수
2. Planning	계획서 plan.md 작성	코드 짜지 말 것
3. Annotation	계획서에 직접 메모 달기	1~6번 반복
4. Implementation	한 번에 전부 구현	멈추지 않고 끝까지

 

이 워크플로우의 핵심 철학은 "생각과 실행을 분리" 하는 거예요.

계획이 완벽해지기 전까지는 절대 코드를 쓰지 않게 하고, 계획이 완성되면 중간에 확인 없이 쭉 실행하게 하는 것.

 

AI 코딩 도구가 점점 강력해지는 요즘, 어떻게 사용하느냐가 결과를 완전히 바꿉니다.

한 번 이 방법대로 써보시면, 예전 방식으로는 다시 못 돌아가실 거예요!

 

원문 : https://boristane.com/blog/how-i-use-claude-code/

 

 

#ClaudeCode #AI코딩 #개발생산성 #코딩워크플로우 #AI개발도구 #개발자팁 #프로그래밍 #AI활용법 #코드자동화 #개발효율화