큰 요청을 명확한 단계로 나누는 방법

Claude에게 "로캘 목록을 추가하고, 검색과 국가 필터를 넣고, 디자인도 바꿔 주세요"라고 요청합니다. 에이전트는 여러 파일을 수정하고 완료했다고 알립니다. 얼핏 보면 페이지도 멀쩡합니다. 그런데 검색어를 입력하자 필요한 항목이 사라집니다. 입력란을 비워도 항목은 돌아오지 않습니다.

무엇이 잘못됐을까요? 검색일까요, 필터일까요, 아니면 목록 자체일까요? 모든 변경이 한꺼번에 들어가서 어느 하나도 따로 작동하는 모습을 확인하지 못했습니다. 검색을 고쳐 달라고 하니 또 수정이 생기고, 페이지 전체를 다시 확인합니다. 작업은 진행되는데 결과에 대한 확신은 점점 줄어듭니다.

뒤엉킨 여러 변경을 한꺼번에 풀지 않으려면 요청을 작고 확인 가능한 단계로 나누세요. 먼저 목록을 만들고 항목을 대조합니다. 그런 다음 검색을 추가해 그 목록에서 확인하세요. 그다음 필터로 넘어가고, 디자인 변경은 별도 단계로 남겨 둡니다. 그래도 실수는 생길 수 있지만, 확인을 마친 출발 상태가 있고 최근에 무엇을 바꿨는지도 분명합니다. 이런 단계를 어떻게 고르고 에이전트에게 요청할지 살펴보겠습니다.

왼쪽에는 한 번에 적용한 변경이 모여 있습니다. 오른쪽에는 아직 구체적인 원인을 가리키지 않는 공통 증상이 보입니다. 각 부분을 차례로 확인하면 문제가 나타난 시점을 마지막 수정과 연결하기 쉬워집니다.

바로 다음 결과를 고르세요

작업 분해는 과제를 여러 부분으로 나누는 것입니다. 에이전트와 일할 때는 각 결과를 따로 확인할 수 있도록 나누는 편이 좋습니다. 예를 들면 먼저 목록을 표시하고, 그다음 검색을 추가한 뒤, 마지막으로 필터를 넣습니다.

목록이 이미 작동한다면 다시 만들 필요는 없습니다. 아직 없는 동작 중 바로 다음에 필요한 것부터 시작하세요. 작동하는지 확실하지 않다면 페이지를 열어 먼저 확인하면 됩니다. 시작점은 보기 좋은 계획이 아니라 프로젝트의 현재 상태에 따라 정해집니다.

"먼저 HTML을 작성하고, 그다음 JavaScript를 작성해"라고 나누는 방법도 있지만, 결과를 확인하는 데 항상 도움이 되지는 않습니다. 제대로 작동하는 검색에는 HTML 입력란과 JavaScript 이벤트 처리기가 동시에 필요할 수 있습니다. 파일은 두 개지만 하나의 명확한 단계입니다.

동작 기준으로 요청을 나누세요

연습용 로캘 목록에는 항목이 네 개 있습니다. 로캘 코드, 언어, 국가는 아래와 같습니다. 이 데이터를 기준으로 결과를 확인하겠습니다.

이제 각 단계의 결과와 확인 방법을 구체적으로 정할 수 있습니다.

화살표는 확인을 마친 뒤 다음 단계로 넘어간다는 뜻입니다. 검색과 필터의 순서는 바꿔도 되지만 둘 다 목록이 필요합니다. 전체 디자인 변경은 별도 단계로 두세요. 핵심 동작이 작동한 뒤에 결과를 평가하는 편이 쉽습니다.

단계의 범위를 정하세요

목록은 준비됐다고 해 보겠습니다. Claude에게 검색을 추가해 달라고 요청하면서, 지금 상태로 유지해야 할 부분을 분명히 말하세요. 예시에서는 데이터와 페이지 동작이 app.js에 있고, 마크업은 index.html에 있습니다. 실제 프로젝트에서는 해당 경로를 사용하세요.

@index.html, @app.js 파일을 읽으세요.
로캘 네 개로 된 목록은 이미 작동합니다.
로캘 코드나 언어 이름으로 검색하는 입력란을 추가하세요.

기존 항목과 각 항목의 필드, 디자인은 유지하세요.
검색에 필요한 요소는 추가해도 됩니다.
국가 필터는 아직 만들지 마세요.

확인: German과 de-DE는 de-DE를 찾고,
zzz는 항목을 찾지 못하며, 검색어가 비어 있으면 네 항목이 모두 표시됩니다.

먼저 무엇을 바꿀지 설명하세요. 아직 파일은 수정하지 마세요.

답변을 읽어 보세요. 새로운 데이터나 테마 변경, 필터가 포함됐다면 실행 전에 범위를 다시 분명히 알려 주세요. 요청과 일치한다면 이 단계를 진행하도록 맡기면 됩니다. 말로 범위를 지정하면 작업을 안내할 수 있지만, 실제 결과도 범위에 맞는지 확인해야 합니다.

추가 동작이 모두 범위를 벗어나는 것은 아닙니다. 검색에는 입력란이 필요합니다. 전체 색상 변경은 별도의 요청입니다. 이렇게 물어보면 편합니다. "이 수정 없이도 선택한 결과를 얻을 수 있을까요?"

어디서 시작할지 불분명하다면

다른 사람의 프로젝트에서는 먼저 읽어 봐야 할 수 있습니다. 항목이 어디서 오고 어떤 파일이 목록을 표시하는지 모르는 상태에서 검색을 추가해 달라고 요청하는 건 좋지 않습니다.

페이지가 항목을 어디서 가져오고 어디서 목록을 표시하는지 찾으세요.
충분하다면 핵심 파일 두세 개를 읽으세요.
찾은 경로와 첫 번째로 할 만한 작은 단계를 제안하세요.
정보가 부족하다면 무엇을 더 읽어야 하는지 말하세요.
아직 파일은 수정하지 마세요.

이 단계의 결과는 찾아낸 파일과 각 파일의 역할에 대한 설명입니다. 답변 내용을 거기서 언급한 코드 부분과 대조하세요. "두세 개"는 시작을 위한 대략적인 기준이지, 필요한 코드를 더 읽지 말라는 뜻은 아닙니다.

다음 단계 전에 확인하세요

"검색이 준비됐습니다"라는 말만으로는 무엇을 확인했는지 알 수 없습니다. 페이지를 열고 요청에 든 사례를 시험해 보세요. 일치하는 결과, 결과 없음, 입력란 비우기를 확인합니다. 기존 항목과 필드도 그대로 남아 있는지 함께 살펴보세요.

입력란을 비운 뒤 행이 세 개만 보인다면 검색 작업을 계속하세요. 에이전트에게 한 동작과 예상 결과, 실제 결과를 알려 주세요. "입력란을 비웠습니다. 항목 네 개를 예상했는데 세 개만 보입니다." 지금 필터를 추가하면 원인을 찾기 더 어려워집니다.

때로는 단계를 더 작게 나눠야 합니다. 예를 들어 항목이 전혀 표시되지 않는다면 먼저 목록을 복구하고 확인하세요. 정렬에 대한 새 아이디어는 별도 항목으로 적어 두면 잊히지 않고 현재 수정 범위도 넓히지 않습니다.

왼쪽 갈래는 검색이 요청대로 작동할 때까지 검색 단계로 돌아갑니다. 오른쪽은 확인을 마친 뒤 열립니다. 필터를 추가한 다음에는 필터 자체와 검색과 함께 작동하는지도 확인하세요. 새 단계가 이미 작동하던 동작에 영향을 줄 수 있습니다.

Claude Code와 함께 작업하기

수정할 때마다 세 가지를 정리하세요. 지금 얻으려는 결과, 그대로 유지할 부분, 결과를 확인할 방법입니다. 에이전트에게 필요한 파일을 제공하고, 바로 다음 단계를 합의한 뒤 그 단계를 맡기세요. 확인을 마친 다음 앞으로 나아가거나 현재 수정을 다듬으면 됩니다.

한 단계가 여러 메시지에 걸릴 수도 있습니다. 어느 시점에서든 이렇게 말할 수 있는지가 더 중요합니다. "지금은 검색을 추가합니다. 목록은 이미 확인했습니다. 필터는 아직 대기 중입니다."