Claude Code에 대해 내가 잘못 알고 있었던 것 (그리고 어떻게 해결했는가)

나의 첫 번째 Claude Code 풀 리퀘스트 (Pull Request, PR)는 200개의 파일로 이루어져 있었습니다. 문서화된 표준도, 워크플로우 (Workflow)도, 명확한 방향성도 없었습니다. 2주간의 패치 (Patching) 작업 끝에, 나는 그 이유를 이해했고 모든 것을 전면 개편했습니다.

어떻게 200개 파일짜리 PR을 만들게 되었나?

나는 막 그린필드 프로젝트 (Greenfield project)를 진행하는 새로운 팀에 합류했습니다. 프로세스 (Processes)는 여전히 형성되는 단계였습니다. 표준 (Standards)은 주로 사람들의 머릿속에만 존재했습니다. 나의 경우도 마찬가지였습니다.

나는 이미 다른 제품에 존재하는 기능을 구현해야 했습니다. 나의 계획은 이랬습니다: Claude에게 소스 저장소 (Source repo) 링크를 주고, 우리 프로젝트의 컨벤션 (Conventions)에 맞춰 해당 기능을 복제하도록 요청하는 것이었습니다.

Claude는 몇 분 만에 작업을 끝냈습니다. 나는 스스로가 대견하다고 느꼈습니다.

그러다 첫 번째 파일을 열었습니다.

그 파일은 내가 내 코드에 항상 요구해 왔던 품질을 충족하지 못했습니다. 하지만 PR은 이미 "완료"된 상태였습니다. 그리고 나는 전형적인 실수를 저질렀습니다. 한 걸음 물러나 접근 방식을 재고하는 대신, 패치 (Patching)를 시작했습니다.

프롬프트 (Prompt)를 계속 던졌습니다. 수정 사항을 계속 적용했습니다. 2주 동안 점진적인 수정 (Incremental corrections)이 이어졌지만, 내가 Claude에게 실질적인 방향을 제시하지 않았기 때문에 매번 조금씩 어긋났습니다.

코드 리뷰 (Code review)는 내가 이미 의심하던 바를 확인해 주었습니다. 품질이 확보되지 않았던 것입니다. 그리고 나는 그런 형태로 존재해서는 안 되었을 200개의 파일을 어떻게 고쳐야 할지 전혀 알 수 없었습니다.

진짜 문제는 Claude Code가 아니었다

Claude는 나의 표준을 알 방법이 없었습니다. 내가 그것을 문서로 작성하지 않았기 때문입니다.

내가 수동으로 작업할 때는 일관된 프로세스를 따릅니다: 비즈니스 요구사항 (Business requirements)을 상세히 분석하고, 명확히 하기 위한 질문을 던지며, 작업을 Jira 티켓으로 나누고, 팀과 조율한 다음, 알려진 컨벤션 (Conventions)에 따라 구현합니다.

Claude Code를 사용할 때, 나는 이 모든 단계를 건너뛰었습니다.

빠르고 유능한 도구에 대한 흥분 때문에 나는 조급해졌습니다. 도구가 제 역할을 제대로 수행하는 데 필요한 컨텍스트 (Context)를 제공하지 않은 채, 곧바로 구현 (Implementation) 단계로 뛰어들었습니다.

그것이 근본 원인입니다. 도구가 아니라 도구 주변에 결여된 구조가 문제였습니다.

현재의 워크플로우 (Workflow) 모습

이제 새로운 프로젝트를 시작할 때 제가 가장 먼저 하는 일은 /init을 실행하는 것입니다. Claude는 코드베이스를 분석하고 CLAUDE.md를 생성합니다. 이는 프로젝트의 메모리 역할을 하는 중앙 설정 파일입니다. 빌드 명령, 코딩 컨벤션 (Coding conventions), 아키텍처 결정, 명명 패턴 (Naming patterns) 등, 그렇지 않았다면 Claude가 매 세션마다 사용자에게 다시 설명해 달라고 요청했을 모든 정보가 여기에 담깁니다.

그다음으로 .claude/rules/ 디렉토리를 채웁니다. 이것은 프로젝트 규칙을 정리하기 위한 Claude Code의 내장 메커니즘입니다. 각 .md 파일은 하나의 주제를 다룹니다: code-style.md, testing.md, security.md 등입니다. YAML 프론트매터 (YAML frontmatter)를 통해 특정 파일 경로에 규칙을 할당할 수 있으므로, Claude가 백엔드 코드를 작업할 때 프론트엔드 규칙이 로드되지 않도록 할 수 있습니다.

또한 저는 .claude/settings.json에 설정된 Stop 훅 (Hook)을 통해 정적 분석 (Static analysis), 스타일 일관성, 테스트와 같은 품질 검사를 실행합니다. 이 훅은 별도의 컨텍스트에서 검사를 수행하는 서브에이전트 (Subagent)를 실행하므로, 활성 세션의 토큰을 소모하지 않습니다.

어떠한 구현을 하기 전에, 저는 계획을 세웁니다. Superpowers의 brainstorming 스킬을 사용하여 접근 방식을 깊이 생각한 다음, 질문을 하나씩 던지며 모순, 공백, 누락된 가정을 파헤치는 별도의 스킬인 Grill Me를 사용합니다. 만족스러운 결과가 나오면 그 결과를 PRD (Product Requirements Document)로 저장하고, 클래스 이름, 속성 (Properties), 아키텍처, 테스트를 포함한 상세한 구현 계획을 생성하는 writing-plans (이 또한 Superpowers 제공) 단계로 넘어갑니다.

대규모 기능은 종종 수십 개의 파일을 건드립니다. 이것이 관리 불가능한 하나의 PR (Pull Request)이 되도록 두는 대신, 저는 Claude에게 계획을 수직적 슬라이스 (Vertical slices) — 즉, 의미론적으로 응집되어 있고 독립적으로 검토 가능한 단위 — 로 나누도록 요청합니다.

구현은 executing-plans (Superpowers)를 통해 깨끗한 세션에서 실행됩니다.

코드가 작성되면 품질 검사를 실행한 다음, requesting-code-review (Superpowers)를 통해 출력물이 계획과 일치하는지 확인합니다. 모든 것이 통과되면 풀 리퀘스트 (Pull request)를 생성하며, 때로는 Jira 티켓 번호를 기반으로 Claude에게 직접 열어달라고 요청하기도 합니다.

만약 PR (Pull Request)이 너무 커지게 되면, 저는 Claude에게 이를 스택형 PR (stacked PRs)로 나누어 달라고 요청합니다. 즉, 첫 번째는 main 브랜치에서 분기하고, 그다음 PR들은 각각 이전 PR에서 분기하도록 하는 방식입니다.

팀 리뷰 과정에서 표준으로 유지할 만한 가치가 있는 내용이 발견되면, Claude에게 .claude/rules/ 내의 관련 파일을 업데이트하도록 요청합니다. 그러면 다음번에는 해당 표준이 자동으로 적용됩니다.

아무도 언급하지 않는 변화

워크플로우를 넘어, Claude Code는 개발자가 실제로 수행하는 업무의 본질을 변화시킵니다.

도구가 구현 (implementation)을 처리하게 되면, 여러분은 무엇을 왜 만들어야 하는지에 대한 상위 단계 (upstream)를 생각하는 데 더 많은 시간을 할애하게 됩니다. 상세 사양이 모두 작성된 티켓 (ticket)이 도착하기를 기다리는 대신, 비즈니스 가치를 염두에 두고 기능을 설계하게 됩니다.

실제로 여러분은 프로덕트 엔지니어 (product engineer)에 더 가까운 존재가 됩니다.

이것이 진정한 변화입니다. 그리고 이는 의도적으로 고민해 볼 가치가 있는 지점입니다.

첫 번째 프롬프트를 입력하기 전, 여기서부터 시작하세요

Claude Code 출력물의 품질은 여러분이 제공하는 컨텍스트 (context)의 품질에 직접적으로 비례합니다.

결과가 실망스럽다면, 던져야 할 질문은 "어떤 프롬프트를 작성해야 할까?"가 아니라 "내가 아직 무엇을 말해주지 않았는가?"여야 합니다.

CLAUDE.md, 규칙 파일 (rules files), 적절한 계획 (plan), 버티컬 슬라이스 (vertical slices) — 이것들이 바로 그 해답입니다.

먼저 그 토대를 구축하세요. 그러면 프롬프트는 자연스럽게 따라올 것입니다.

여러분의 Claude Code 워크플로우는 어떤 모습인가요?