Claude.ai와 ClaudeCode를 사용하여 AI 주도 개발 (AI-driven development)을 진행할 때, 이 두 가지를 구분해서 사용하는 사람은 얼마나 될까요.

최근 Claude를 사용하기 시작한 이후, 간편한 상담 도구로서 채팅 기능 (Claude.ai)을 평소에 사용해 왔던 저는 깊게 생각하지 않고 설계 개발도 채팅으로 진행하여, 설계 검토부터 구현까지 동일한 채팅에서 그대로 계속해서 진행해 나갔습니다.

그 결과, 대화를 나눌 때마다 이면에서는 대화 이력이 쌓여갔고, 깨달았을 때는 단 한 번의 대화만으로 Pro 플랜의 5시간 이용 제한의 절반을 소비해 버릴 정도로 토큰 (Token)이 쌓여 있었습니다.

구현은 왠지 ClaudeCode가 더 나을 것 같다는 인식은 있지만, 그렇다면 처음부터 전부 ClaudeCode로 해도 괜찮은 것인지 등 AI 주도 개발에 대한 의문점들을 정리하여 나름의 진행 방식을 정리해 보았습니다.

개인 개발에서의 아이디어 발안 → 요구사항 정의 → 기본 설계 → 상세 설계 → 구현, 그리고 지속적인 수정

까지의 구체적인 절차를 개인용 AI 주도 개발의 진행 방식으로서 정리했습니다.

같은 부분에서 고민하고 계신 분들은 꼭 참고해 주시기 바랍니다.

• Claude.ai는 Pro 플랜 이용 (5시간마다 이용 제한 있음)
• 소스 코드는 GitHub로 관리
• 구현에는 ClaudeCode를 사용
• GitHub와 연동 완료

정리한 결과, 다음과 같은 심플한 역할 분담으로 진행합니다.

Claude.ai (Project 기능): 요구사항 정의 · 기본 설계를 진행하는 장소. 아직 형태가 갖춰지지 않은 검토 단계부터 대화 기반으로 내용을 구체화함

ClaudeCode: 상세 설계 이후, 사양에 기반하여 실제로 코드를 작성하는 작업장. 리포지토리 (Repository)를 직접 읽고 씀

요구사항 정의나 기본 설계 단계의 검토는 이야기가 옆길로 새거나 번잡해지기 쉽습니다. 이 번잡한 과정을 ClaudeCode에서 수행하고 그대로 리포지토리에 남기면, docs가 비대해질 뿐만 아니라 답변 정확도가 떨어지거나, 나중에 "결론이 무엇인가"를 추적하기 어려워지기도 합니다.

따라서 기본 설계까지는 Claude.ai에서 자유롭게 검토하고, 결론이 나오면 정리 · 요약한 후 깔끔한 상태로 리포지토리 측에 반영하도록 합니다. 여러 채팅을 간편하게 오갈 수 있고, 틈틈이 스마트폰으로 쉽게 사용할 수 있다는 점도 Claude.ai의 장점입니다.

반면 ClaudeCode의 강점은 리포지토리에 있는 현재의 코드를 이해한 상태에서 제안 · 수정까지 해준다는 점입니다. 따라서 실제 구현 시에는 ClaudeCode가 압도적으로 유리할 것입니다.

이 두 가지는 지식 (Knowledge)이 공유되지 않는다는 점에 주의가 필요합니다. Claude.ai의 Project "Knowledge"는 ClaudeCode에서 자동으로 보이지 않습니다. 따라서 후술하는 바와 같이, 기본 설계에서 상세 설계 · 구현으로 넘어갈 때는 설계 메모를 리포지토리 내부 (CLAUDE.md나 docs/ 폴더 등)에 다시 작성해야 합니다.

이후 공정별로 구체적인 진행 방법을 소개합니다.

0 베이스 단계에서는 Project를 만들지 않고 채팅 기능으로 진행합니다. 채팅은 스마트폰 앱에서도 구동할 수 있으므로, 전철 이동 시간이나 산책 등 틈틈이 아이디어를 검토하는 데에도 적합합니다. "이런 것을 만들고 싶다"라는 형태가 보이기 시작하는 타이밍에 해당 테마 전용의 Project를 만듭니다.

테마 전용 Project를 만들었다면, 그곳에서 요구사항 정의까지를 명확히 해 나갑니다. 어디까지를 요구사항 정의로 볼지는 개인차가 있겠지만, 최소한 배경 · 과제, 타겟, 스코프 (Scope, 할 것 / 하지 않을 것), 주요 유스케이스 (Use case), 성공 기준을 명확히 합니다.

요구사항이 어느 정도 정리되면 채팅에 다음과 같이 지시합니다.

지금까지의 논의를 요구사항 정의로서

requirements.md

형식으로 정리해 주세요. 배경 · 과제, 타겟, 스코프 (할 것 / 하지 않을 것), 주요 유스케이스, 성공 기준의 관점을 포함해 주세요.

출력된 내용을 확인하고 Knowledge에 업로드합니다. 이후 이 Project에서 채팅을 시작하면 파일을 자동으로 참조하므로 전제가 공유된 상태로 진행할 수 있습니다.

requirements.md를 Knowledge로 갖춘 Project에서 새로운 채팅을 열어 기술적인 실현 방침을 논의합니다. 요구사항 정의와는 논점의 입도 (Granularity)가 달라지므로, 채팅을 나누는 것이 진행하기 수월합니다.

기본 설계 (Basic Design) 단계에서는 「기술 스택 (Tech Stack)」, 「전체 아키텍처 (Overall Architecture)」, 「데이터 설계 방침 (Data Design Policy)」, 「구현 순서 로드맵 (Implementation Roadmap)」 등 논점이 여러 갈래로 나뉘기 쉬우므로, 하나의 채팅에서 논의를 계속하기보다 토픽별로 새로운 채팅을 만드는 것이 좋습니다. 동일한 토픽으로 묶어야 답변의 정밀도가 높아지기 때문입니다. 또한, 토큰 (Token) 절약 관점에서도 채팅을 세분화하는 것이 과거 이력을 적게 유지할 수 있는 방법입니다.

기본 설계의 내용은 basic_design.md라는 파일에 정리해 나갑니다. 처음부터 토픽별 헤더(Heading)만 준비해 둔 템플릿을 만들어 두도록 합시다.

각 토픽별 대화는 결론이 난 시점에 다음과 같이 지시합니다.

(예: 데이터 설계 방침)

"지금까지의 논의를 basic_design.md의 「데이터 설계 방침」 섹션 내용으로 정리해 주세요. 다른 섹션은 언급하지 마세요."

출력된 섹션 단위의 내용을 basic_design.md의 해당 부분에 교체하고, 업데이트된 basic_design.md를 Knowledge에 다시 업로드합니다.

동일한 파일명으로 추가하면 Claude.ai 측에서 이전 버전과 혼재되는 현상이 발생할 수 있으므로, 업로드하기 전에 오래된 파일을 삭제한 뒤 새로운 파일을 추가하는 것이 안전합니다.

기본 설계가 확정된 단계에서 ClaudeCode를 이용한 작업으로 넘어갑니다. 이 단계에서는 아직 리포지토리 (Repository)가 존재하지 않으므로, Claude.ai 채팅에 다음과 같이 지시하여 ClaudeCode가 자동으로 확인할 CLAUDE.md를 만들게 합니다.

"requirements.md와 basic_design.md의 내용을 바탕으로 ClaudeCode용 CLAUDE.md를 작성해 주세요.

• 프로젝트 개요, 기술 스택, 디렉토리 구성(Directory Structure) 예상치를 기재할 것
• 상세한 논의 경위는 쓰지 않고, 확정된 사양(Specification)만 간결하게 정리할 것
• 구현 순서 로드맵은 「다음에 할 일 (Next Steps)」 섹션으로 반영할 것"

출력된 CLAUDE.md를 확인하고 로컬에 저장해 둡니다.

프로젝트용 폴더를 만들고, 그 바로 아래에 방금 Claude.ai에서 작성한 CLAUDE.md를 둡니다. 이 폴더에서 claude 명령어를 실행하여 ClaudeCode를 기동하고 작업을 진행합니다 (GitHub 원격 리포지토리와의 연동은 별도로 설정해 둡니다).

먼저 대략적인 진행 방식을 설명하겠습니다.

⓪ claude 명령어를 실행하여 ClaudeCode를 기동한다.
① 세션을 시작하고 착수할 태스크 (Task)를 결정한다 (세션 시작 시 CLAUDE.md의 내용이 자동으로 읽힙니다).
② 태스크에 적합한 브랜치 (Branch)를 생성한다.
③ 플랜 모드 (Plan Mode)에서 요구사항을 확인하며 상세 설계를 다듬는다.
④ 상세 설계가 완료된 후, 코드를 생성하게 하고 차이점 (Diff)을 확인한다.
⑤ 테스트 및 동작 확인 등을 수행하여 코드 구현이 완료되었음을 확인한다.
⑥ 업데이트 내용을 CLAUDE.md에 반영한다.
⑦ PR (Pull Request)을 생성하고 GitHub 상에서 머지 (Merge)한다.
⑧ 세션을 종료한다.

이 ①~⑧ 과정을 하나의 사이클로 하여 반복하며 개발을 진행합니다.

• Plan Mode 활용: Shift+Tab으로 모드를 전환하여 「어떻게 변경할 것인가」를 검토한 뒤 구현으로 넘어간다 (코드 생성은 상세 설계가 다듬어진 후에 한다).
• 태스크를 작게 나누기: 「이 파일의 이 함수만 수정해 줘」와 같이 스코프 (Scope)를 좁혀서 의뢰한다.
• CLAUDE.md에 반영: 수정 후에는 그때마다 변경 사항을 CLAUDE.md에 반영한다.
• 세션 구분: 태스크가 바뀔 때마다 세션을 새로 만든다.

하지만 실제로 이 방식대로 진행하면 반복 작업이 많아 힘들기 때문에, 다음과 같이 궁리해 봅니다.

앞서 언급했듯이, 구현이 완료되면 다음 기능으로 넘어가기 전에 CLAUDE.md를 업데이트합니다. 이 작업은 태스크 완료 시점에 수행하기 때문에 잊기 쉽고, 정해진 규칙에 따라 업데이트하고 싶습니다. 또한 커밋 (Commit), 푸시 (Push), 브랜치 정리까지 포함하면 절차가 많아 매번 수동으로 하는 것은 번거로우므로, .claude/commands/에 커스텀 슬래시 명령어 (Slash Command)로 등록하여 일련의 흐름을 한꺼번에 수행할 수 있도록 합니다. update-claude-md.md라는 파일명으로 만들면 /update-claude-md로 호출할 수 있습니다.

project_name/
├── CLAUDE.md
└── .claude/
...

---
description: 이번 세션의 변경 내용을 CLAUDE.md에 반영하고, 차이(diff) 확인 후 커밋(commit)・푸시(push)・브랜치(branch) 정리까지 수행
allowed-tools: Bash(git status:*), Bash(git diff:*), Bash(git add:*), Bash(git commit:*), Bash(git push:*), Bash(git branch:*), Bash(git checkout:*), Bash(git pull:*), Read, Edit
...

/update-claude-md가 '세션의 종료'를 정리하는 명령어라면, 이것은 '세션의 시작'을 정리하는 명령어입니다. 세션을 시작할 때마다 CLAUDE.md를 다시 읽고 다음에 할 일을 검토하며, 브랜치를 만들고 작업을 시작하는 동일한 절차를 매번 반복하게 됩니다. 이 또한 매번 수동으로 하기에는 번거로우므로, 명령어로 만들어 자동화합니다. start-session.md라는 파일명으로 만들면 /start-session으로 호출할 수 있습니다.

project_name/
├── CLAUDE.md
└── .claude/
...

---
description: CLAUDE.md와 현재 git 상태를 확인하고, 다음 작업을 제안함
allowed-tools: Read, Bash(git status:*), Bash(git branch:*)
...

/start-session과 /update-claude-md를 조합하면, 기능 하나당 개발 사이클은 다음과 같은 흐름이 됩니다.

⓪ claude 명령어를 실행하여 ClaudeCode를 기동한다.

① /start-session을 실행한다 (CLAUDE.md와 실제 브랜치 상태를 대조하여 다음에 해야 할 태스크를 확인하고, 브랜치를 생성한다).

② Plan Mode에서 태스크를 실현하기 위한 상세 설계(detailed design)를 구체화한다.

③ 코드를 생성시키고, 차이(diff)를 확인하며 구현을 진행한다.

④ 테스트나 동작 확인 등을 수행하여 코드 구현이 완료되면 /update-claude-md를 실행한다 (코드 변경 확인, 브랜치 이름 재검토, CLAUDE.md 업데이트, 차이 승인, 커밋, 푸시까지 맡기며, 푸시가 끝나면 GitHub에서 PR을 생성 및 머지한다 〈이 부분만 수동〉. 머지 완료를 알리면 main 업데이트와 작업 브랜치 삭제까지 수행한다).

⑤ 명령어에 따라 /clear를 하고 ①로 돌아간다.

이 사이클을 기능별로 반복하는 형태가 됩니다.

세션의 시작과 종료가 모두 정형화됨으로써, "무엇부터 시작해야 할지", "CLAUDE.md 업데이트를 어떻게 해야 할지"를 매번 고민할 필요가 없어집니다.

게다가 /clear로 세션을 리셋하는 운용이 정착되면서, 불필요한 이전 논의나 코드가 이어지지 않고 대화 기록을 깨끗하게 유지할 수 있어 토큰(token) 절약으로도 이어집니다.

이 기사에서는 Claude.ai와 ClaudeCode의 활용 구분(使い分け)에 대해 고민했던 경험을 바탕으로, 개발 공정에 따른 역할 분담을 정리했습니다.

요건 정의(requirements definition) 및 기본 설계(basic design)는 Claude.ai에서 자유롭게 검토하여 requirements.md · basic_design.md에 정리하고, 상세 설계 이후부터는 ClaudeCode에 인계하여 구현을 진행합니다.

나아가 /start-session과 /update-claude-md라는 커스텀 명령어를 만들어 세션의 시작과 종료를 정형화함으로써, 대화 기록을 깨끗하게 유지하면서 기능 단위로 개발을 돌릴 수 있게 되었습니다.

아직 운용은 발전 단계에 있으며, GitHub Actions 연동을 통한 리뷰 자동화 등은 테스트 중입니다. 시도해보고 유효했던 점이 있다면 다시 기사로 정리하겠습니다.

여기까지 읽어주셔서 감사합니다. 도움이 되었다면 '좋아요'와 '팔로우'를 부탁드립니다. 큰 힘이 됩니다.