Claude Code에게 작업을 요청할 때, 어떤 흐름으로 진행하고 계신가요?

갑자기 하고 싶은 일을 대략적으로 전달하고, 그대로 구현까지 진행하게 하고 있지는 않으신가요?

이 기능을 구현해줘

→ 이러한 방식의 요청으로는 좋은 결과를 얻기 어렵습니다.

Claude Code의 공식 베스트 프랙티스( https://code.claude.com/docs/ja/best-practices )에서는 갑자기 구현하게 하는 것이 아니라, Explore → Plan → Implement → Commit와 같이 조사, 계획, 구현, 커밋(Commit)을 나누어 진행하는 방법을 소개하고 있습니다.

이 블로그에서는 Claude Code에게 단순히 구현만을 요청하는 것이 아니라,

조사부터 시작하여, 플랜(Plan)을 세우고, 구현하고, 검증하고, commit / PR까지 진행하는 중요성에 대해 정리합니다.

Claude Code를 얕게 사용하면 예를 들어 다음과 같이 됩니다.

이 기능을 구현해줘

Claude는 그럴싸하게 코드를 작성해 줍니다.

하지만 그것만으로는 몇 가지 문제가 있습니다.

• 기존 설계를 충분히 읽지 않음
• 영향 범위가 모호함
• 테스트 방침이 없음
• 동작 확인이 "했습니다"라는 자기 신고로 끝남
• PR 리뷰에서 사람이 대량으로 뒷수습을 해야 함

이러면 AI를 사용하고 있는 것처럼 보여도, 실제로는 개발 프로세스 자체는 별로 변하지 않았을지도 모릅니다.

반면, 조금 더 정중하게 사용하는 경우는 다음과 같습니다.

먼저 구현하지 말고 관련 코드를 조사해 주세요.
기존 설계, 변경이 필요한 파일, 영향 범위, 테스트 방침을 정리해 주세요.
그 후, 구현 계획을 제시해 주세요.
...

이 차이는 상당히 크다고 생각합니다.

Claude Code를 '구현자'로만 다루는 것이 아니라,

조사자, 설계 보조자, 구현자, 테스터, 리뷰어로서 단계적으로 사용하는 것.

이것이 첫걸음이 될 것이라고 생각합니다.

공식 베스트 프랙티스에서는 개발 흐름으로서 Explore → Plan → Implement → Commit가 소개되어 있습니다.

현장에서 사용한다면, 여기에 Verify를 명시적으로 추가한 5단계로 만들면 다루기 쉽습니다.

중요한 것은, 구현 전에 Explore와 Plan을 거치는 것이라고 생각합니다.

Claude에게 갑자기 코드를 쓰게 하면, 올바른 것처럼 보여도 문제 설정이 틀린 코드가 나올 수 있습니다.

가장 먼저 해야 할 일은 구현이 아니라 조사라고 생각합니다.

나쁜 예:

로그인 부분을 수정해줘

좋은 예:

먼저 구현하지 말고, 로그인 처리에 관계된 코드를 조사해 주세요.
특히 다음 사항을 확인해 주세요.
- 인증 플로우
...

Claude Code는 코드베이스를 읽을 수 있으므로, 처음에 "어디를 봐야 하는지"를 사람이 전부 지정할 필요는 없습니다.

다만, 무엇을 조사해주길 바라는지는 명확히 하는 것이 좋습니다.

나아가 조사가 커질 것 같은 경우에는 Subagents를 사용하는 것이 유효합니다.

Subagents를 사용하면 별도의 컨텍스트에서 조사를 진행하여, 메인 대화의 컨텍스트를 더럽히지 않고 결과만 반환하는 방식으로 진행할 수 있습니다.

조사 페이즈의 목적은 Claude가 "올바른 문제"를 파악하게 하는 것이라고 생각합니다.

조사가 끝나면 바로 구현하는 것이 아니라 계획을 내놓게 합니다.

여기서의 포인트는 플랜 모드(Plan Mode)로 진행하는 것이며, Claude Code 상에서 "shift+tab"을 눌러 plan mode에 들어가는 것이 중요합니다 (플랜 모드로 부탁합니다, 라고 입력해 두면 문맥에 따라 판단하여 자동으로 전환해 주는 경우도 있습니다).

이 플랜 모드가 매우 중요하므로, 이 부분만이라도 꼭 기억해 주셨으면 합니다.

구현 계획을 세워 주세요.
다음 형식으로 정리해 주세요.
1. 변경할 파일
...

여기서 사람이 해야 할 일은, 계획을 리뷰하고 이해하는 것입니다.

AI가 생각한 플랜을 이해하고 설명할 수 있는 것이 중요하다고 생각합니다.

또한, 플랜은 md 파일로 저장해 두면 나중에 되돌아볼 수 있어 편리합니다.

계획이 타당하다면 구현에 들어갑니다.

위의 계획에 따라 구현해 주세요.
계획에서 벗어나야 할 경우에는 구현 전에 이유를 설명해 주세요.
구현 후, 변경한 파일과 변경 이유를 정리해 주세요.

여기서 중요한 것은 Claude에게 너무 자유롭게 맡기지 않는 것이라고 생각합니다.

특히 주의해야 할 점은 다음과 같습니다.

• 덤으로 리팩터링 (Refactoring)을 하게 하지 말 것
• 관계없는 파일을 건드리지 않게 할 것
• 기존의 설계 사상 (Design Philosophy)을 깨뜨리지 않게 할 것
• 테스트 없이 "완료"하게 하지 말 것

큰 태스크에서는 처음부터 전부 시키는 것이 아니라, 파일 단위·책임 단위로 나누는 것이 안정적으로 유지하기 쉽습니다.

먼저 API 계층 (Layer)만 구현해 주세요.
UI나 테스트는 아직 변경하지 마세요.
완료되면 차이점 (Diff)을 설명해 주세요.

Claude Code는 자율적으로 움직일 수 있는 한편, 방치하면 스코프 (Scope)가 팽창해 버리는 경우가 있습니다.

인간의 업무는 직접 손을 움직이는 것에서, 스코프를 제어하는 것으로 조금씩 옮겨가게 됩니다.

Claude Code를 사용하는 데 있어 특히 중요한 것은 검증입니다.

나쁜 예:

돌아갔어?

좋은 예:

다음을 실행해 주세요.
- npm test
- npm run lint
...

해외의 실천가들도 AI가 작성한 코드는 "주니어 엔지니어가 제출한 코드"로 취급하여, 반드시 테스트·실행·리뷰를 한다는 사고방식을 강조하고 있습니다.

Addy Osmani 씨도 Claude Code와 같은 도구를 사용할 경우에는 구현 후에 테스트를 실행하고, 실패하면 AI에게 디버깅을 시키는 write code → run tests → fix 루프를 워크플로우 (Workflow)에 포함시키라고 말합니다.

Claude Code에 적합한 것은 바로 이러한 루프라고 생각합니다.

테스트가 실패하는 한, 원인을 조사하고 수정하여 재실행해 주세요.
테스트를 통과하면 최종 결과뿐만 아니라, 실패 원인과 수정 내용도 설명해 주세요.

나아가, Claude Code에는 /goal이라는 개념도 있습니다.

/goal은 "이 조건이 충족될 때까지 작업을 계속한다"라는 완료 조건을 설정하는 것입니다.

이는 매번 인간이 "계속해", "고쳐줘", "한 번 더 테스트해"라고 지시해야 하는 상태에서 벗어나기 위한 메커니즘입니다.

단, 완료 조건은 Claude의 출력상에서 확인할 수 있는 형태로 만들 필요가 있습니다.

구현과 검증이 끝나면 마지막으로 PR (Pull Request)화 합니다.

이번 변경 사항을 정리해 주세요.
- 개요
- 변경한 파일
...

이 정도까지 Claude에게 맡길 수 있게 되면 PR 리뷰의 질도 높아지기 쉽습니다.

특히 좋다고 생각하는 것은 Claude에게 "리뷰 관점"을 쓰게 하는 것입니다.

이 PR에서 리뷰어가 중점적으로 봐주었으면 하는 관점을 3가지 들어주세요.
사양(Specification)・보안(Security)・유지보수성(Maintainability)의 관점을 포함해 주세요.

AI가 만든 코드일수록 리뷰 관점을 명문화하는 것이 좋다고 생각합니다.

"어디를 봐야 할지 모르는 거대한 PR"은 AI 시대에 더욱 위험해지기 쉽습니다.

또한, 웹 페이지 구현 등의 경우에는 보고용으로 md 파일에 스크린샷을 포함한 main 브랜치와 작업 브랜치의 차이점을 리포트(Report)로 작성하고 있습니다.

이를 통해 main 브랜치와 작업 브랜치의 변경 사항을 시각적으로도 알기 쉽게 확인할 수 있고 보고용으로도 사용할 수 있어 추천합니다. (사이트 조작에는 Playwright를 사용하고 있습니다.)

2026년 현재, 해외의 Claude Code / Codex 주변에서는 단순히 "좋은 프롬프트 (Prompt)를 쓰는 것"보다, Loop Engineering이라는 개념이 논의되고 있습니다.

Loop Engineering이란 거칠게 말하면,

인간이 매번 프롬프트를 쓰는 것이 아니라, 에이전트 (Agent)가 지속적으로 조사·구현·검증·보고하는 메커니즘을 설계하는 것입니다.

Addy Osmani 씨 (Google의 소프트웨어 엔지니어)는 루프에 필요한 요소로 다음과 같은 것들을 꼽았습니다.

• Automations: 정기적으로 조사·트리아지 (Triage)한다
• Worktrees: 여러 에이전트의 작업 공간을 분리한다
• Skills: 프로젝트 지식을 재사용 가능하게 만든다
• Plugins / Connectors: GitHub, Slack, DB 등 외부 도구와 연결한다
• Subagents: 구현하는 AI와 확인하는 AI를 분리한다
• Memory: 대화 외부에 상태를 남긴다

이는 Claude Code의 기능군과도 상당히 대응됩니다.

이 정도 단계에 이르면, Claude Code 활용은 '프롬프트 기술'이 아니라 **개발 시스템 설계 (Development System Design)**에 가까워집니다.

Claude Code를 깊게 사용할수록 구현 속도는 올라갑니다.

하지만 속도가 올라가는 만큼 위험도 증가합니다.

• 이해하지 못한 코드가 늘어난다
• 사양 (Specification)의 미묘한 차이를 알아차리기 어렵다
• "테스트가 통과했으니 OK"라고 생각하기 쉽다
• AI의 제안을 리뷰하지 않고 그대로 수용하기 쉽다
• 권한이나 인증 정보 (Credentials) 취급이 위험해진다

해외의 실천가들도 AI가 작성한 코드는 반드시 리뷰하고, 테스트하며, 필요하다면 다른 모델이나 다른 세션에서 비판적으로 검토할 것을 권장하고 있습니다.

Claude Code를 사용하는 시대의 엔지니어의 가치는,

"직접 모든 코드를 작성하는 것"에서,

무엇을 만들지 결정하고, AI에게 올바르게 조사·구현·검증하게 하며, 결과물을 책임지고 판단하는 것으로 옮겨갑니다.

즉, Claude Code가 진화할수록 인간의 일이 사라지는 것이 아니라,

구현자(Implementer)에서 설계자(Designer)·리뷰어(Reviewer)·오케스트레이터(Orchestrator)로 옮겨가는 것이라고 생각합니다.

Claude Code를 제대로 사용한다는 것은 단순히 코드를 작성하게 하는 것이 아니라고 생각합니다.

• 구현 전에 Explore 하게 한다
• Plan을 인간이 리뷰한다
• 작게 구현하게 한다
• 테스트(Test)·lint·build로 검증하게 한다
• PR(Pull Request)까지 리뷰 가능한 형태로 정리한다
• CLAUDE.md / Skills / Hooks / MCP / Subagents / Worktrees를 통해 재현 가능한 루프를 만든다

이러한 흐름을 만들 수 있어야 비로소 Claude Code는 "편리한 코드 생성 AI"에서 "개발 프로세스를 바꾸는 에이전트 (Agent)"에 가까워지는 것이라고 생각합니다.

여러분도 Claude Code를 잘 활용하여 즐거운 개발 경험을 하시길 바랍니다!