41장. Claude Code로 기능 확장하기

새 프로젝트를 만드는 일도 신나지만, 진짜 실전은 이미 돌아가고 있는 서비스에 새 기능을 얹는 순간부터 시작됩니다. 처음부터 만드는 일은 빈 도화지에 그림을 그리는 느낌에 가깝습니다. 반면 기존 서비스에 기능을 추가하는 일은 이미 살고 있는 집에 방 하나를 더 붙이는 일과 비슷합니다.

벽을 하나 세우는 것보다 더 어려운 건, 원래 전기 배선이 어디로 지나가는지, 수도관은 어디에 있는지, 문을 여닫는 동선은 괜찮은지를 함께 생각해야 한다는 점입니다. 코드도 똑같습니다. 기능은 붙일 수 있어도, 기존 구조와 어울리지 않으면 금방 삐걱거리기 시작합니다.

그래서 이번 장의 핵심은 이것입니다.

Claude Code를 잘 쓰는 것은 코드를 빨리 추가하는 일이 아니라, 이미 있는 서비스에 어울리게 기능을 확장하는 일입니다.

처음 만드는 것보다 확장이 더 실전인 이유

이미 있는 코드베이스에는 보이지 않는 규칙이 숨어 있습니다. 폴더 구조, 컴포넌트 이름 방식, 데이터 불러오는 흐름, 에러 처리 방식, 테스트 습관 같은 것들입니다. Claude Code는 똑똑하지만, 이런 규칙을 처음부터 저절로 다 아는 것은 아닙니다. 그래서 아무 준비 없이 큰 저장소에 들어가면 기술적으로는 맞지만, 프로젝트 방식과는 어긋난 코드를 만들 수 있습니다.¹

예를 들어 같은 버튼 하나를 추가하더라도, 어떤 프로젝트는 공통 Button 컴포넌트를 반드시 재사용해야 하고, 어떤 프로젝트는 서버 액션 대신 API 라우트를 써야 하며, 어떤 프로젝트는 에러 메시지를 토스트로만 보여주도록 정해 두었을 수 있습니다.

초보자는 여기서 자주 이렇게 생각합니다.

"기능만 되면 된 거 아닌가?"

하지만 서비스는 기능만 돌아간다고 오래 버티지 않습니다. 기존 코드와 어울려야 다음 수정도 쉬워지고, 버그도 덜 나고, 미래의 내가 덜 괴로워집니다. 오늘의 기능 추가는 내일의 유지보수 비용을 함께 만든다는 뜻입니다.

Claude Code에게 먼저 이 서비스의 규칙을 알려주기

기능 확장을 잘하려면, Claude Code가 먼저 이 프로젝트의 생활 규칙을 알아야 합니다. 이때 가장 유용한 도구가 CLAUDE.md입니다. 이 파일은 프로젝트의 공통 규칙, 자주 쓰는 명령어, 중요한 금지 사항을 적어 두는 안내문 역할을 합니다.²

공식 가이드도 CLAUDE.md를 짧고 읽기 쉽게 유지하되, 실제로 반복해서 알려줘야 하는 정보만 담으라고 권합니다.³ 너무 길면 오히려 핵심 규칙이 묻히기 쉽습니다.

예를 들면 이런 내용이 좋습니다.

• 사용 중인 기술 스택과 버전

• 중요한 폴더 구조

• 테스트와 린트 실행 명령어

• 재사용해야 하는 공통 컴포넌트

• 새 라이브러리를 마음대로 추가하면 안 된다는 규칙

• .env, 배포 설정, 운영 DB 관련 파일은 함부로 건드리면 안 된다는 금지선

아주 단순하게 적으면 이런 느낌입니다.

# Project Context
- Stack: Next.js, TypeScript, Supabase, Vercel
- Reuse existing components in `components/`
- Do not add new npm packages without asking
- Never edit `.env` or production config directly
- Run `npm run lint` after code changes
- Prefer small diffs and explain changed files

프로젝트가 커졌다면 루트에 하나만 두지 말고, 특정 폴더 아래에 더 작은 CLAUDE.md를 두는 방식도 좋습니다. 예를 들어 app/ 아래에는 화면 규칙, lib/ 아래에는 데이터 처리 규칙을 따로 둘 수 있습니다.²

아직 파일이 없다면 Claude Code의 /init 같은 초기화 흐름으로 초안을 만들고, 그 뒤에 사람이 손으로 다듬는 편이 가장 현실적입니다.²

기능 추가 전에 먼저 시킬 일은 구현이 아니라 탐색이다

기존 서비스에 기능을 붙일 때 초보자가 가장 많이 하는 실수는 바로 이것입니다.

"댓글 기능 추가해줘."

문장이 짧고 시원해서 좋아 보이지만, 기존 코드베이스에서는 조금 위험합니다. 댓글을 어디에 붙여야 하는지, 글 상세 화면이 어떤 구조인지, 로그인 상태는 어디서 확인하는지, 기존에 비슷한 저장 패턴이 있는지 먼저 알아야 하기 때문입니다.

그래서 첫 요청은 구현보다 탐색에 가까운 편이 좋습니다. 예를 들면 이렇게 시작할 수 있습니다.

댓글 기능을 추가하려고 해.
바로 구현하지 말고,
1) 현재 글 상세 화면이 어떤 파일들로 구성되는지,
2) 글 데이터와 사용자 정보가 어디서 오는지,
3) 기존 코드에서 재사용할 수 있는 패턴이 무엇인지
먼저 설명해줘.

이 요청의 장점은 큽니다. Claude Code가 먼저 구조를 읽고, 내가 이해할 수 있는 말로 지도를 그려주기 때문입니다. 기존 코드베이스에서는 이 지도가 정말 중요합니다. 지도 없이 공사부터 시작하면 벽이 아니라 수도관을 뚫을 수 있으니까요.

세션 범위를 좁게 잡아야 정확도가 올라간다

기존 저장소에서 Claude Code를 쓸 때는 "전체 프로젝트를 다 읽고 알아서 해줘"보다 "이번 작업과 관련된 범위만 보자"가 훨씬 낫습니다. 큰 코드베이스에서는 필요한 파일을 직접 짚어 주고, 한 세션에는 한 가지 목표만 두는 편이 더 정확합니다.¹

예를 들어 북마크 기능을 추가한다면, 이렇게 범위를 좁히는 편이 좋습니다.

이번 작업 범위는 아래 파일과 관련 폴더로 제한해줘.
- 글 목록 화면
- 글 상세 화면
- posts 관련 데이터 조회 함수
- auth 사용자 확인 로직
먼저 어떤 파일을 읽을지 제안하고,
그다음 계획만 설명해줘.

작업이 바뀌면 세션도 바꾸는 편이 좋습니다. 아까는 북마크 기능을 보다가, 갑자기 검색 정렬 문제까지 한 세션에서 같이 다루면 대화가 금방 흐려집니다. 한 세션에는 한 목표. 이것만 기억해도 품질이 꽤 달라집니다.¹

처음 확장하는 기능은 작고 검증 가능한 것이 좋다

기존 코드베이스에서 Claude Code를 믿기 시작하는 가장 좋은 방법은, 처음부터 거대한 구조 변경을 맡기지 않는 것입니다. 먼저 작고 확인하기 쉬운 기능으로 호흡을 맞춰보는 편이 낫습니다.¹

좋은 첫 확장 기능은 이런 느낌입니다.

• 프로필 소개글 한 줄 추가하기

• 글 상세 화면에 북마크 버튼 붙이기

• 내 글만 모아보는 필터 추가하기

• 목록 카드에 작성일 배지 추가하기

반대로 처음부터 너무 큰 일은 조심하는 편이 좋습니다. 인증 구조를 전면 개편하거나, 데이터베이스 스키마를 크게 갈아엎거나, 여러 모듈을 한꺼번에 리팩터링하는 일은 아직 이르다는 뜻입니다.¹

중요한 기준은 간단합니다.

끝났는지 내가 직접 확인할 수 있는가?

브라우저에서 눌러보고, 저장해보고, 실패도 일부러 만들어보며 확인할 수 있다면 좋은 확장 작업입니다.

실전 예시: 북마크 기능을 5단계로 확장하기

이제 이미 완성해 둔 글 서비스에 북마크 기능을 붙인다고 가정해봅시다. 이 기능은 기존 글 목록, 상세 화면, 로그인 상태, 데이터 저장 흐름과 모두 연결되기 때문에 "기능 확장"의 감각을 익히기에 딱 좋습니다.

첫 단계는 구현이 아니라 계획입니다.

우리 서비스에 북마크 기능을 추가하고 싶어.
바로 구현하지 말고,
초보자가 검토하기 쉬운 5단계로 나눠줘.
각 단계마다 목표, 바뀔 수 있는 파일, 완료 조건을 적어줘.

그다음에는 한 단계씩 잠가서 진행합니다.

1. 먼저 현재 글 목록과 상세 화면에서 북마크 버튼이 들어갈 위치만 제안하게 합니다.

2. 다음으로 북마크 UI만 붙입니다. 아직 저장은 하지 않습니다.

3. 그다음 북마크 테이블이나 저장 로직을 연결합니다.

4. 저장 성공과 실패, 로그인 안 된 상태를 처리합니다.

5. 마지막으로 내 북마크 목록 화면이나 북마크 표시 상태를 점검합니다.

이 순서가 좋은 이유는 분명합니다. 화면, 저장, 예외 처리를 섞지 않기 때문입니다. UI가 이상한지, 저장이 안 되는지, 권한 처리가 틀린지를 각각 따로 볼 수 있습니다.

여기서 Claude Code에게 이렇게 말하면 더 안전합니다.

지금은 2단계만 진행해줘.
북마크 버튼 UI만 추가하고,
실제 DB 저장 로직은 넣지 말아줘.
기존 버튼 스타일을 재사용하고,
끝나면 바뀐 파일과 확인 방법을 설명해줘.

이 프롬프트의 좋은 점은 "무엇을 할지"뿐 아니라 "무엇을 하지 말지"도 함께 말해 준다는 것입니다. 기능 확장에서는 이 금지선이 정말 중요합니다.

기능이 붙는 것보다 기존 방식에 맞는지가 더 중요하다

새 기능을 붙였을 때 가장 먼저 감탄이 나오는 순간은 보통 이런 때입니다.

"오, 된다!"

그런데 기존 서비스에서는 그다음 질문이 훨씬 중요합니다.

"그런데 우리 서비스 방식으로도 맞게 됐나?"

이때 확인할 것은 대개 네 가지입니다.

• 기존 컴포넌트를 재사용했는가

• 데이터 처리 방식이 기존 패턴과 같은가

• 에러 처리 방식이 통일되어 있는가

• 새 파일 이름과 위치가 프로젝트 흐름에 맞는가

예를 들어 우리 서비스가 이미 components/ui/Button.tsx를 쓰고 있는데 Claude Code가 갑자기 BookmarkButtonNew.tsx를 만들고 스타일을 그 안에 따로 적어 두었다면, 기능은 되더라도 방향은 조금 어긋난 것입니다.

이럴 때는 바로 이렇게 되물으면 됩니다.

이 구현이 현재 프로젝트의 패턴과 얼마나 맞는지 점검해줘.
기존 공통 컴포넌트로 바꿀 수 있는 부분이 있으면 제안해줘.
새 라이브러리 없이 더 단순하게 만들 수 있다면 그렇게 수정해줘.

이 질문 하나가 "되는 코드"를 "우리 프로젝트에 어울리는 코드"로 바꾸는 데 큰 도움을 줍니다.

안전장치 없이 기능 확장을 맡기면 금방 불안해진다

기능 확장은 새 코드 몇 줄 더하는 일이 아닙니다. 원래 잘 돌아가던 부분을 함께 흔들 가능성이 있는 작업입니다. 그래서 Claude Code에게 맡길수록 안전장치가 필요합니다.

가장 기본은 브랜치와 작은 커밋입니다. feature/bookmark 같은 브랜치를 만들고, 단계가 끝날 때마다 작게 남기면 훨씬 안심됩니다. 마음에 들지 않으면 바로 되돌릴 수 있기 때문입니다.

그다음으로 유용한 것은 권한과 실행 범위입니다. Claude Code는 기본적으로 읽기 중심으로 시작하고, 파일 수정이나 명령 실행은 승인을 받는 구조를 권장합니다. 민감한 파일 접근을 막고, 필요할 때만 허용하는 방식이 더 안전합니다.⁴

특히 .env, 배포 설정, 운영 관련 스크립트, 외부 네트워크 접근은 조심해야 합니다. 필요하다면 샌드박스 같은 격리 환경을 써서 Claude Code가 허용된 디렉터리와 도메인 안에서만 움직이게 할 수 있습니다. 이런 방식은 승인 피로를 줄이면서도 경계는 유지하는 데 도움이 됩니다.⁵

쉽게 말하면 이렇습니다.

기능 확장을 맡길 때는 "열심히 일하는 조수"보다 "울타리 안에서 일하는 조수"가 더 믿을 만합니다.

조금 위험한 기능은 스위치를 달고 공개하자

기능 확장 중에는 바로 전체 사용자에게 열기 부담스러운 것들이 있습니다. 예를 들어 새 추천 기능, 새 결제 흐름, 새 편집기처럼 실패했을 때 영향이 큰 기능들입니다. 이럴 때 유용한 방법이 기능 플래그입니다. 쉽게 말하면 켜고 끄는 스위치입니다.⁶

예를 들어 북마크 기능이 아직 불안하다면, 내부 테스트 계정에서만 켜 두고 일반 사용자에게는 숨길 수 있습니다. 기본값은 꺼 두고, 준비가 되면 켭니다. 그러면 Claude Code가 빠르게 코드를 만들어도, 공개는 사람이 천천히 결정할 수 있습니다.

초보자에게는 이것만 기억해도 충분합니다.

새 기능을 만들었다고 해서 바로 모두에게 보여줄 필요는 없다.

기능 확장의 속도와 공개의 속도는 같지 않아도 됩니다.

Claude Code에게 바로 써먹는 프롬프트

이 장의 내용을 실제로 적용할 수 있게, 기능 확장에 잘 맞는 프롬프트 틀을 남겨두겠습니다.

현재 구조 먼저 이해하기

이 기능을 바로 구현하지 말고,
현재 코드베이스에서 관련된 화면, 데이터 함수, 인증 흐름을 먼저 찾아 설명해줘.
재사용해야 할 기존 패턴도 함께 정리해줘.

범위 제한해서 한 단계만 진행하기

지금은 1단계만 진행해줘.
관련 파일만 최소한으로 수정하고,
새 라이브러리는 추가하지 말아줘.
작업이 끝나면 바뀐 파일과 확인 방법을 요약해줘.

프로젝트 규칙에 맞는지 다시 점검하기

지금 구현이 우리 프로젝트의 기존 패턴과 맞는지 검토해줘.
더 단순하거나 더 일관된 방식이 있다면 제안하고 수정해줘.

실패 상황까지 포함해 점검하기

이 기능의 수동 테스트 체크리스트를 만들어줘.
정상 동작, 로그인 안 된 상태, 중복 클릭, 저장 실패까지 포함해줘.

이 네 가지 프롬프트만 잘 써도, Claude Code와의 기능 확장 작업이 훨씬 덜 불안해집니다.

기능 확장에서 가장 중요한 질문

이번 장에서 꼭 남기고 싶은 질문이 하나 있습니다.

"이 기능은 추가됐는가?"보다 더 중요한 질문은,

"이 기능이 지금 서비스에 자연스럽게 스며들었는가?"입니다.

처음 만드는 단계에서는 속도가 주인공일 수 있습니다. 하지만 서비스가 한 번 만들어지고 나면, 그다음부터는 조화가 중요합니다. 화면도 어울려야 하고, 데이터 흐름도 맞아야 하고, 에러 처리도 기존과 비슷해야 합니다.

Claude Code는 기능을 빨리 붙이는 데 큰 힘이 됩니다. 하지만 어떤 기능을, 어디까지, 어떤 규칙 안에서 붙일지는 결국 사람이 정해야 합니다. 바로 그 판단이 초보자를 실전 개발자로 바꿉니다.

이번 장의 핵심 문장

기존 서비스에 기능을 붙일 때는, 새 코드를 많이 만드는 것보다 기존 코드와 잘 어울리게 만드는 것이 더 중요합니다.

처음부터 거창하게 확장하지 마세요. 먼저 구조를 읽고, 규칙을 알려주고, 범위를 좁히고, 작게 붙이고, 직접 검증하세요. 그러면 Claude Code는 무서운 자동 생성기가 아니라, 기존 서비스를 차근차근 키워 가는 믿을 만한 확장 도구가 됩니다.

이 감각이 생기면 어느 순간 이런 생각이 들게 됩니다.

"아, 나도 이제 그냥 만드는 사람이 아니라, 키워 가는 사람이구나."

참고

¹How to Use Claude Code on an Existing Large Codebase

²Using CLAUDE.md files: Customizing Claude Code for your codebase

³Best Practices for Claude Code

⁴Security - Claude Code Docs

⁵Making Claude Code more secure and autonomous with sandboxing

⁶Feature Flags with Claude Code: Safe Deployments with Toggle Management