Claude Code와 AI 지원 개발 워크플로우
코드 생성부터 디버깅, 리팩토링, 대규모 코드베이스 유지보수에 이르기까지 Claude Code를 일상적인 개발에 통합하는 실용적인 방법.
6개월 전, 저는 Claude Code를 주 개발 도구로 사용하기 시작했습니다. 가끔 상용구 코드를 위해 여는 장난감이 아니라, 제가 작업하는 모든 프로젝트에서 코드를 작성하고, 디버깅하고, 리팩토링하는 기본 인터페이스로 말이죠. 이러한 변화는 즉각적이지 않았습니다. 습관을 조정하고, 무엇을 위임하고 무엇을 수동으로 유지할지 배우며, 속도를 늦추기보다는 실제로 빠르게 만드는 워크플로우를 구축하는 데 몇 주가 걸렸습니다.
이 게시물은 그러한 워크플로우가 일상적인 실천에서 어떻게 보이는지, 어떤 패턴이 최고의 결과를 내는지, 그리고 AI 지원 개발이 여전히 부족한 부분이 어디인지에 대한 실용적인 설명입니다.
환경 설정
Claude Code는 터미널에서 실행됩니다. 파일 시스템에 직접 접근할 수 있고, 파일을 읽고 쓸 수 있으며, 셸 명령을 실행하고, Git과 상호작용할 수 있습니다. 이는 여러분이 붙여넣는 코드 스니펫으로 작동하는 채팅 기반 AI와는 근본적으로 다릅니다. Claude Code는 전체 프로젝트를 보고, 디렉토리 구조를 이해하며, 단일 작업으로 여러 파일에 걸쳐 변경 사항을 적용할 수 있습니다.
이를 생산적으로 만드는 설정:
CLAUDE.md 파일은 여러분이 작성할 가장 중요한 구성입니다. 이 파일들은 Claude Code가 자동으로 읽는 지침 파일입니다. 모든 프로젝트에 적용되는 표준을 위한 ~/.claude/CLAUDE.md의 전역 파일과 프로젝트별 규칙을 위한 저장소 루트의 프로젝트별 파일이 있습니다.
제 전역 CLAUDE.md는 코딩 표준을 설정합니다: 최대 파일 크기(~300줄), 컴포넌트 추출 규칙, 테스트 요구 사항, 커밋 규칙. 프로젝트 수준 파일은 기술 스택, 아키텍처 패턴, 명명 규칙 및 모든 도메인별 규칙을 지정합니다. 이는 선택 사항이 아닙니다. 이 파일들이 없으면 Claude Code는 작동하지만 프로젝트의 스타일이나 규칙과 일치하지 않는 코드를 생성합니다.
MCP 서버는 Claude Code가 접근할 수 있는 범위를 확장합니다. 저는 데이터베이스 서버(Claude가 개발 데이터베이스에 직접 쿼리할 수 있도록), 파일 검색 서버, 그리고 분석 데이터와 같은 특정 프로젝트 서버를 연결합니다. MCP 구성은 프로젝트 루트의 .mcp.json에 있습니다. 각 서버는 Claude Code가 Model Context Protocol을 통해 통신하는 별도의 프로세스입니다.
Git 통합은 내장되어 있지만 보호 장치가 필요합니다. 저는 Claude Code가 강제 푸시를 하지 않고, 요청 없이 커밋을 수정하지 않으며, pre-commit 훅을 건너뛰지 않도록 구성합니다. 이러한 파괴적인 작업은 직접 할 때는 쉽게 되돌릴 수 있지만, AI가 여러분이 모르는 사이에 수행하면 치명적일 수 있습니다.
일상적인 워크플로우 통합
아침 패턴
저는 각 코딩 세션을 프로젝트 디렉토리에서 Claude Code를 열고 오늘 작업할 내용에 대한 컨텍스트를 제공하는 것으로 시작합니다. 자세한 사양은 아닙니다. 제가 다룰 기능, 버그 또는 리팩토링에 대한 한두 문장 정도입니다.
"사용자 설정 페이지에 이메일 알림 환경설정을 추가하고 있습니다. 사용자는 새 메시지, 프로젝트 업데이트, 주간 요약에 대한 알림을 토글할 수 있어야 합니다. 설정은 데이터베이스에 유지되고 이메일 서비스와 동기화되어야 합니다."
이것은 의도를 설정합니다. 그러면 Claude Code는 세션의 모든 후속 요청에 대해 파일 위치, 명명 및 아키텍처에 대해 더 나은 결정을 내릴 수 있는 컨텍스트를 갖게 됩니다.
코드 생성 패턴
가장 효과적인 코드 생성 요청은 무엇을 할지에 대해서는 구체적이고 어떻게 할지에 대해서는 유연합니다. 좋은 요청은 동작, 제약 조건 및 통합 지점을 설명합니다. 나쁜 요청은 구현 단계를 하나씩 설명합니다. 그 시점에서는 직접 코드를 입력하는 것이 나을 수 있습니다.
좋은 요청: "알림 환경설정이 포함된 JSON 본문을 허용하는 PATCH 엔드포인트를 사용자 설정 라우터에 추가합니다. 각 환경설정 키가 허용된 유형 중 하나인지 유효성 검사를 수행합니다. user_settings 테이블에 유지합니다. 업데이트된 환경설정을 반환합니다."
나쁜 요청: "req와 res를 받아 body.preferences를 구조 분해하고, 이를 반복하며, 각 항목에 대해 db.update를 호출하고, 200을 반환하는 updateNotificationPrefs라는 함수를 생성합니다."
첫 번째 요청은 Claude Code에게 모범 사례를 적용할 여지를 줍니다. 프로젝트에서 이미 사용하는 유효성 검사 라이브러리를 사용하고, 다른 라우터에 설정된 오류 처리 패턴을 따르며, 기존 엔드포인트의 응답 형식과 일치시킬 것입니다. 두 번째 요청은 여러분이 설명한 것을 정확히 생성하며, 설명한 것이 이상적이지 않더라도 마찬가지입니다.
다중 파일 작업
이것이 Claude Code가 전통적인 코딩을 진정으로 능가하는 부분입니다. 기능이 여러 파일(데이터베이스 마이그레이션, 서비스 계층, 라우트 핸들러, React 컴포넌트 및 테스트)에 걸쳐 있을 때, Claude Code는 단일 작업으로 이 모든 것을 생성하거나 수정하면서 일관성을 유지할 수 있습니다.
"users 테이블에 notification_preferences JSONB 컬럼을 추가하고, 이에 대한 마이그레이션을 생성하고, 유효성 검사와 함께 환경설정을 업데이트하는 서비스 메서드를 추가하고, API 라우터를 통해 노출하고, 엔드포인트를 호출하는 설정 페이지용 React 컴포넌트를 생성합니다."
Claude Code는 이 모든 파일을 생성하고, 올바른 모듈을 가져오고, 마이그레이션, 서비스 및 API 계층 전반에 걸쳐 올바른 테이블 및 컬럼 이름을 사용하며, API 계약과 일치하는 프론트엔드 컴포넌트를 생성합니다. 이를 수동으로 수행하는 것은 끊임없이 파일을 전환하고 이름을 교차 참조해야 함을 의미합니다. 원자적으로 발생하는 것은 상당한 시간 절약입니다.
대화형 개선
최고의 결과는 단일 요청이 아닌 반복적인 대화에서 나옵니다. 저는 초기 구현을 생성하고, 검토한 다음 개선합니다.
"알림 환경설정 컴포넌트는 좋아 보이지만, 낙관적 업데이트를 사용해야 합니다. UI를 즉시 업데이트하고 API 호출이 실패하면 되돌려야 합니다. 또한 초기 가져오기를 위한 로딩 상태를 추가하세요."
이것은 Claude Code가 방금 생성한 것에 대한 완전한 컨텍스트를 가지고 있기 때문에 작동합니다. 정확한 컴포넌트를 수정하고, 프로젝트에서 사용하는 상태 관리 접근 방식을 사용하여 낙관적 업데이트 패턴을 추가하며, 생성한 다른 모든 것을 보존합니다.
AI를 이용한 디버깅
디버깅은 Claude Code가 가장 극적인 생산성 향상을 제공하는 부분입니다. 전통적인 디버깅 루프는 다음과 같습니다: 오류 읽기, 가설 형성, 로깅 추가, 재현, 로그 읽기, 가설 조정, 반복. Claude Code는 이를 압축합니다.
오류 진단
오류가 발생하면 스택 트레이스 또는 오류 메시지를 붙여넣고 "주간 요약 옵션을 토글한 후 알림 환경설정을 저장하려고 할 때 이 오류가 발생합니다"라고 말합니다. Claude Code는 다음을 수행할 수 있습니다.
- 관련 소스 파일을 읽어 코드 경로를 이해합니다.
- 스택 트레이스와 설명된 트리거를 기반으로 잠재적인 원인을 식별합니다.
- 유형 불일치, 누락된 null 검사 또는 경쟁 조건과 같은 일반적인 문제를 확인합니다.
- 작동 이유에 대한 설명과 함께 수정 사항을 제안합니다.
간단한 버그(누락된 await, 잘못된 속성 이름, off-by-one 오류)의 경우 Claude Code는 제가 수동으로 관련 줄을 찾는 것보다 빠르게 문제를 식별하고 수정합니다. 상태 관리, 비동기 타이밍 또는 여러 시스템 간의 상호 작용과 관련된 복잡한 버그의 경우, 정확한 수정 사항을 생성하지 못하더라도 검색 공간을 크게 좁힙니다.
로그 분석
"여기 서버 로그의 마지막 50줄이 있습니다. API가 /api/settings 엔드포인트에서 간헐적으로 500 오류를 반환합니다. 무엇이 잘못되었습니까?"
Claude Code는 로그를 읽고, 패턴을 식별하고(요청 본문이 특정 크기를 초과할 때 또는 두 요청이 동일한 리소스에 동시에 도달할 때 항상 오류가 발생함), 진단을 제안합니다. 그런 다음 본문 파서 제한 조정, 뮤텍스 추가 또는 경쟁 조건 수정과 같은 수정 사항을 직접 적용할 수 있습니다.
테스트 주도 디버깅
브라우저에서 쉽게 재현할 수 없는 버그를 발견하면 Claude Code에게 정확한 시나리오를 포착하는 실패 테스트를 작성하도록 요청합니다.
"빈 객체로 알림 환경설정을 저장한 다음, 유효한 환경설정으로 다시 저장하는 테스트를 작성하세요. 두 번째 저장이 첫 번째를 덮어써야 하는데, 병합되는 것 같습니다."
테스트는 통과하거나(가설을 반증) 실패합니다(버그를 확인하고 재현 가능한 사례를 제공). 어느 쪽이든, 저는 유지할 수 있는 테스트를 갖게 됩니다.
리팩토링 전략
리팩토링은 기계적으로 복잡하지만 개념적으로는 간단하기 때문에 AI 지원에 완벽한 사용 사례입니다. 리팩토링 후 코드가 어떻게 보여야 하는지 알고 있습니다. 문제는 아무것도 깨뜨리지 않고 모든 변경 사항을 일관되게 적용하는 것입니다.
컴포넌트 추출
"이 Dashboard 컴포넌트는 450줄입니다. 통계 패널, 활동 피드, 빠른 작업 섹션을 별도의 컴포넌트로 추출하세요. 같은 디렉토리에 유지하세요. 모든 props와 상태 관리를 보존하세요."
Claude Code는 컴포넌트를 읽고, 논리적 경계를 식별하고, 각 섹션을 적절한 props 인터페이스와 함께 자체 파일로 추출하며, Dashboard를 업데이트하여 새 컴포넌트를 구성합니다. 가져오기, 유형 정의 및 위로 올리거나 아래로 전달해야 하는 상태를 처리합니다.
이름 변경 및 재구조화
"프로젝트 전체에서 user 모듈을 account로 이름을 변경하세요. 여기에는 디렉토리 이름, 모든 파일 이름, 모든 가져오기 경로, 코드베이스의 모든 참조, 그리고 쿼리 계층의 데이터베이스 테이블 별칭이 포함됩니다."
이것은 지루하고 오류가 발생하기 쉬운 수동 작업입니다. Claude Code는 한 번에 이를 수행하고, 놓칠 수 있는 참조를 찾아내며, 나중에 테스트 스위트를 실행하여 아무것도 깨지지 않았는지 확인할 수 있습니다.
패턴 마이그레이션
"우리는 이전 오류 처리 패턴(모든 라우트 핸들러의 try/catch)에서 중앙 집중식 오류 미들웨어 패턴으로 마이그레이션하고 있습니다. 다음은 새 패턴의 예시입니다. 이를 /api/settings 디렉토리의 모든 라우트 핸들러에 적용하세요."
Claude Code는 예시를 읽고, 패턴을 이해하며, 모든 파일에 일관되게 적용합니다. 여러 try/catch 블록이 있는 라우트, 유지해야 하는 정리 로직이 있는 라우트, 특정 오류 유형을 catch하는 라우트와 같은 예외 상황을 처리합니다.
대규모 프로젝트에서 컨텍스트 유지
AI 지원 개발의 가장 큰 과제는 컨텍스트입니다. Claude Code는 컨텍스트 창(한 번에 고려할 수 있는 정보의 양에 대한 제한)을 가지고 있습니다. 작은 프로젝트에서는 모든 것을 읽을 수 있습니다. 큰 모노레포에서는 그럴 수 없습니다.
아키텍처 문서로서의 CLAUDE.md
CLAUDE.md 파일은 코딩 표준만을 위한 것이 아닙니다. 프로젝트의 아키텍처를 높은 수준에서 설명하는 데 사용하세요.
## 아키텍처
- API 라우트는 /src/routes에 있으며, 리소스당 하나의 파일
- 비즈니스 로직은 /src/services에 있으며, 라우트 핸들러에 의해 호출됨
- 데이터베이스 접근은 Drizzle ORM을 사용하며, 스키마는 /src/db/schema에 있음
- 프론트엔드 컴포넌트는 /src/components에 있으며, 기능별로 구성됨
- 공유 UI 컴포넌트는 /src/components/ui에 있음
- 상태 관리는 Zustand를 사용하며, 스토어는 /src/stores에 있음
이를 통해 Claude Code는 모든 파일을 읽지 않았더라도 프로젝트를 지능적으로 탐색할 수 있습니다. 데이터베이스 스키마를 어디서 찾아야 하는지, 새 컴포넌트를 어디에 배치해야 하는지, 계층이 어떻게 연결되는지 알고 있습니다.
전략적 파일 읽기
Claude Code에게 "전체 프로젝트를 읽으세요"라고 요청하지 마세요. 대신 관련 부분을 지적하세요.
"사용자 설정 서비스, 설정 API 라우트, 알림 환경설정 컴포넌트를 읽으세요. 환경설정 업데이트 엔드포인트에 속도 제한을 추가하고 싶습니다."
이것은 Claude Code에게 관련 없는 파일에 컨텍스트 창을 낭비하지 않고 필요한 컨텍스트를 정확히 제공합니다. 필요한 경우 추가 파일을 요청할 수 있지만, 집중적으로 시작하는 것이 좋습니다.
세션 연속성
긴 코딩 세션은 대화를 통해 자연스럽게 컨텍스트를 축적합니다. 그러나 새 세션을 시작하면 그 컨텍스트는 사라집니다. 저는 다음을 통해 이를 처리합니다.
- 최근 아키텍처 결정으로 CLAUDE.md를 업데이트합니다.
- 각 세션을 작업 중인 내용에 대한 간략한 컨텍스트 설명으로 시작합니다.
- Claude Code가 최근 변경 사항을 이해할 수 있도록 Git 커밋 메시지를 사용합니다.
Git 로그는 과소평가된 컨텍스트 소스입니다. Claude Code가 마지막 10개의 커밋 메시지를 읽으면 최근에 무엇이 변경되었는지 이해하고 진행 중인 작업과의 충돌을 피할 수 있습니다.
효과적인 부분과 부족한 부분
AI 지원이 뛰어난 부분
상용구 및 CRUD 작업. 유효성 검사, 오류 처리 및 테스트가 포함된 새 API 엔드포인트를 생성하는 것은 80%가 기계적입니다. Claude Code는 제가 입력하는 것보다 더 빠르고 일관되게 이를 생성합니다.
파일 간 일관성. 변경 사항이 8개의 파일(유형 정의, 스키마, 마이그레이션, 서비스, 라우트, 컴포넌트, 테스트, 문서)에 영향을 미쳐야 할 때, Claude Code는 이 모든 파일에 걸쳐 일관성을 유지합니다. 저는 필연적으로 하나를 업데이트하는 것을 잊어버립니다.
테스트 생성. 테스트하려는 동작을 설명하고 Claude Code가 테스트를 작성하도록 하는 것이 수동으로 작성하는 것보다 빠르며, 제가 생각하지 못했을 예외 상황을 포착합니다. "알림 환경설정 서비스에 대한 테스트를 작성하세요. 유효한 입력, 빈 입력, 유효하지 않은 환경설정 키, 데이터베이스 오류 및 동시 업데이트를 다루세요."
코드 검토 및 분석. "이 파일에 잠재적인 경쟁 조건이 있습니까?" 또는 "이 함수가 null 사용자로 호출되면 어떻게 됩니까?" Claude Code는 코드를 분석하고 수동 검토 중에 놓치기 쉬운 문제를 식별합니다.
새로운 API 및 라이브러리 학습. 익숙하지 않은 라이브러리를 사용해야 할 때, Claude Code는 문서와 수천 개의 사용 예시를 보았기 때문에 올바른 사용 패턴을 생성할 수 있습니다. 이는 모든 함수 시그니처에 대한 문서를 읽는 것보다 빠릅니다.
AI 지원이 부족한 부분
복잡한 비즈니스 로직. 로직이 비즈니스 도메인에 대한 깊은 이해를 요구할 때(규칙이 미묘하고, 예외 상황이 도메인별이며, 요구 사항이 모호함), AI 생성 코드는 종종 합리적으로 보이지만 중요한 미묘함을 놓칩니다. 저는 항상 핵심 비즈니스 로직을 직접 작성하고, 그 주변의 스캐폴딩을 위해 Claude Code를 사용합니다.
성능에 중요한 코드. Claude Code는 올바른 코드를 생성하지만, 반드시 최적의 코드를 생성하지는 않습니다. 핫 경로, 타이트 루프 또는 메모리에 민감한 작업의 경우, 저는 구현을 직접 작성하고 Claude Code를 사용하여 그 주변의 벤치마크 및 테스트를 생성합니다.
아키텍처 결정. Claude Code는 여러분이 설명하는 모든 아키텍처를 구현할 수 있지만, 여러분을 위해 아키텍처를 선택해서는 안 됩니다. 마이크로서비스와 모놀리스, SQL과 NoSQL, 서버 렌더링과 클라이언트 렌더링 사이의 절충점은 팀, 규모, 일정 및 사용자에 대한 이해를 필요로 합니다. AI는 그러한 컨텍스트를 가지고 있지 않습니다.
보안에 민감한 코드. 인증 흐름, 암호화, 접근 제어는 수동으로 작성하고 사람의 검토를 받습니다. Claude Code는 작동하는 인증 코드를 생성할 수 있지만, "작동하는" 것과 "안전한" 것은 다른 표준입니다.
AI 지원을 사용하지 말아야 할 때
Claude Code를 사용하는 것이 생산성을 적극적으로 해치는 상황이 있습니다.
코드를 깊이 이해해야 할 때. 복잡한 문제를 디버깅하거나 시스템이 어떻게 작동하는지 배우는 경우, AI가 수정 사항을 작성하도록 하면 문제를 이해하지 못하게 됩니다. 때로는 모든 줄을 수동으로 읽어야 합니다. 이해가 핵심이지, 수정이 핵심이 아닙니다.
작업에 30초 미만이 소요될 때. 변수 이름 변경, 오타 수정, CSS 값 조정 등은 그냥 직접 하세요. Claude Code에 변경 사항을 설명하는 오버헤드가 직접 하는 시간보다 더 큽니다.
사양이 불분명할 때. 무엇을 만들고 싶은지 모른다면, Claude Code는 자신감 있게 잘못된 것을 만들 것입니다. 먼저 요구 사항을 명확히 한 다음 구현을 위임하세요.
AI 생성 코드를 검토하는 데 작성하는 것보다 더 오래 걸릴 때. 짧고 중요한 함수의 경우, 15줄의 코드를 작성하는 것이 AI 생성 코드 15줄을 읽고, 정확성을 확인하고, 잠재적으로 문제를 수정하는 것보다 시간이 덜 걸립니다. 손익분기점은 복잡성에 따라 다르지만, 존재합니다.
실용적인 팁
몇 달간 매일 사용한 후, 다음은 지속적으로 최고의 결과를 내는 패턴입니다.
규칙에 대해 명시적으로 설명하세요. "기존 오류 처리 패턴을 사용하세요"는 아무것도 없는 것보다 낫지만, "asyncHandler 래퍼를 사용하고 적절한 상태 코드와 함께 AppError를 throw하세요"가 더 좋습니다. 방법에 대해 더 구체적일수록 나중에 수정할 필요가 줄어듭니다.
모든 변경 사항을 검토하세요. Claude Code는 변경 사항을 적용하기 전에 diff를 보여줍니다. 모든 diff를 읽으세요. 대충 훑어보는 것이 아니라 실제로 읽으세요. 이것이 문제를 포착하는 지점입니다. "AI가 아마 제대로 했을 거야"라고 생각하며 검토를 건너뛰는 것이 버그가 프로덕션에 도달하는 방식입니다.
점진적인 요청을 사용하세요. 하나의 메시지에 전체 기능을 설명하는 대신, 데이터베이스 계층 먼저, 그 다음 서비스 계층, 그 다음 API, 그 다음 프론트엔드 순으로 구축하세요. 다음 계층으로 넘어가기 전에 각 계층을 검토하세요. 이렇게 하면 체크포인트를 얻고 각 생성을 집중적으로 유지할 수 있습니다.
CLAUDE.md를 최신 상태로 유지하세요. 아키텍처 결정을 내릴 때 CLAUDE.md를 업데이트하세요. 새로운 패턴을 채택할 때 문서화하세요. 접근 방식을 폐기할 때 기록하세요. 이 파일은 코드 품질에 영향을 미치는 가장 강력한 지렛대입니다.
작성하기 전에 읽게 하세요. 변경 사항을 적용하기 전에 Claude Code에게 관련 파일을 읽도록 명시적으로 요청하세요. "기존 설정 라우트를 읽고 동일한 패턴을 따르는 새 라우트를 추가하세요." 이렇게 하면 처음부터 생성하는 것보다 프로젝트와 훨씬 더 잘 일치하는 코드가 생성됩니다.
AI 지원 개발은 타이핑을 덜 하는 것이 아닙니다. 아키텍처, 비즈니스 로직, 사용자 경험과 같이 중요한 결정에 인지적 노력을 집중하고, 그러한 결정을 코드로 기계적으로 번역하는 것을 위임하는 것입니다. Claude Code는 그러한 위임을 위해 제가 찾은 최고의 도구이지만, 여전히 도구일 뿐입니다. 개발자의 판단이 결과물을 좋게 만듭니다.