에이전트가 처리하는 네 가지 작업 유형

"포털 메인 페이지를 마무리해 주세요"라는 요청에는 서로 다른 일이 한꺼번에 몇 가지나 섞여 있습니다. 프로모션 목록에는 필터가 없고, 배너 버튼은 엉뚱한 곳으로 연결됩니다. 리더보드 데이터 준비 코드는 두 번 작성되어 있어 수정할 때마다 일이 두 배로 듭니다. 정작 프로모션 주소가 어디서 오는지는 아무도 정확히 기억하지 못하죠.

이런 요청을 받은 사람이라면 아마 되물어볼 겁니다. Claude Code도 질문할 수 있지만, 종종 빈틈을 스스로 메웁니다. 그럴듯하지만 아무도 부탁하지 않은 일을 덧붙이는 식이죠. 작업 유형마다 추가되는 일도 다릅니다. 필터에는 검색 기능이 따라오고, 링크 수정에는 새 디자인이 붙으며, 리팩터링 중에는 정렬 방식까지 "고치고", 조사 요청은 코드 수정으로 끝납니다.

무엇이 달라져야 할까요?

작업이 끝난 뒤 무엇이 달라졌는지를 보면 유형을 구분하기 쉽습니다.

• 이전에는 없던 동작이 생겼다면 feature, 즉 새 기능입니다.
• 동작이 기대한 대로 바뀌었다면 bugfix, 버그 수정입니다. 이미 구현되어 있지만 처음부터 합의한 대로 작동하지 않았던 경우도 여기에 포함됩니다.
• 겉으로 보이는 결과는 그대로이고 내부 코드 구조만 달라졌다면 refactoring입니다.
• 프로젝트에 관한 질문에 답을 얻고 소스 파일은 그대로라면 research, 조사입니다.

작업 유형을 알면 요청에 무엇을 명시하고 결과에서 무엇을 확인할지 정하기 쉬워집니다. 에이전트에게 얼마나 재량을 줄지는 실수의 대가와 작업 규모에도 달려 있습니다. 실제 사용자가 쓰는 코드를 수정할 때는 연습 프로젝트에 새 페이지를 추가할 때보다 더 꼼꼼히 확인해야 합니다. 조사 후 수정하는 식으로 유형이 섞인 작업도 있습니다. 이때는 단계마다 결과와 경계를 따로 정하세요.

새 기능

프로모션 목록에 활성 항목만 남기는 토글이 필요합니다. 조건부터 정해 두죠. active: true가 있는 프로모션을 활성 상태로 보고, A와 C는 이 값이 켜져 있고 B는 꺼져 있습니다. 데이터는 설명을 위한 예시이고, 아래 요청문은 여러분의 프로젝트에도 적용할 수 있는 템플릿입니다.

"활성 프로모션 필터를 추가해 줘"라고만 요청해도 에이전트는 아마 처리할 겁니다. 게다가 이것저것 더할 수 있죠. 토글 옆에 "필터를 만들었으니" 검색창을 넣고, 종료일순 정렬도 추가하는 식입니다. 하나씩 보면 모두 그럴듯합니다. 하지만 함께 묶이면 아무도 부탁하지 않은 작은 하위 시스템이 되고, 그 기능까지 확인해야 합니다.

페이지에 드러나는 추가 기능은 그나마 눈에 띕니다. 더 곤란한 건 에이전트가 여러분이 결정하지 않은 일을 조용히 정하는 경우입니다. Andrej Karpathy는 자신의 MenuGen 프로젝트에 관한 사례를 소개했습니다. Google로 로그인하고 Stripe로 결제하는 구조에서 에이전트는 이메일 주소를 기준으로 결제와 계정을 연결했습니다. 두 서비스에 등록된 이메일이 서로 다른 사용자는 결제해도 계정에 반영되지 않았습니다. 어떤 값으로 데이터를 연결하고 기존 데이터는 어떻게 처리할지는 여러분이 정할 일입니다. 가능하면 요청에 명시하세요. 여기서는 질문이 좀 단순합니다. active 값이 아예 없는 프로모션은 어떻게 할까요?

에이전트가 멋대로 움직이는 또 다른 원인은 참고할 코드입니다. 에이전트는 프로젝트에서 비슷한 코드를 찾아 그대로 따르는데, 그 코드가 마침 모두가 오래전부터 고치고 싶어 한 부분일 수도 있습니다. 프로젝트에 좋은 예시가 있다면 직접 지정해 주세요.

새 기능을 요청할 때는 사용자 시나리오 하나와 이번 작업에 포함되지 않는 항목을 분명히 적어야 합니다.

메인 페이지의 프로모션 목록에 "활성 항목만" 토글을 추가해 줘.
active: true인 레코드는 활성 상태고, 이 필드가 없으면 비활성 상태야.
현재 데이터로 확인해 줘: 켜면 A와 C, 끄면 A, B, C가 보여야 해.
검색, 정렬, 다른 필터는 추가하지 마. 별도 작업이야.
프로젝트에 비슷한 토글이 이미 있다면 같은 방식으로 만들고
어떤 토글을 참고했는지 알려 줘.
먼저 구현할 시나리오를 한 문장으로 말하고
내 답변을 기다려. 아직 파일은 수정하지 마.

마지막 두 줄은 부담이 적지만 효과가 있습니다. 시나리오를 다시 말하게 하면 여러분의 의도와 다른 점을 수정 전에 알아챌 수 있죠. 에이전트가 계획을 보여 주면 짧게 물어보세요. 해결책이 지나치게 복잡하거나 빠진 부분은 없는지, 그렇게 판단한 이유는 무엇인지요. 어떤 계획에도 쓸 수 있는 질문이지만, feature에서는 특히 유용합니다. 요청에 없는 기능이 여기서 끼어들기 쉽거든요. 작업이 끝나면 토글의 두 상태를 모두 확인하고 페이지에 다른 불필요한 항목이 생기지 않았는지도 살펴보세요.

버그 수정

메인 페이지의 배너 버튼은 프로모션 조건 페이지인 /campaign/를 열어야 하지만, 지금은 /old/로 연결됩니다.

에이전트가 가장 빠르게 할 수 있는 일은 버튼 링크에 /campaign/를 직접 넣는 것입니다. 주소가 원래 링크에 적혀 있었다면 그걸로 충분하죠. 하지만 여러 버튼이 함께 쓰는 공통 데이터에서 주소를 가져오는 경우라면 이렇게 넣어도 증상만 가려질 뿐입니다. 이 버튼은 작동하지만 데이터 오류는 남습니다. 또 자주 있는 일은 파일을 열어 둔 김에 배너의 여백과 색상까지 손보는 겁니다.

버튼만 봐서는 어떤 경우인지 알 수 없습니다. 코드를 살펴봐야 합니다.

요청하기 전에 직접 문제를 재현해 보세요. 버튼을 눌러 어디로 연결되는지 확인하면 됩니다. 문제가 재현되지 않는다면 작업을 서둘러 닫지 말고, 어떤 단계와 데이터에서 문제가 나타났는지 먼저 확인하세요. 재현했다면 이제 원인을 찾아야 합니다. 버튼이 주소를 어디서 가져오는지 모르겠다고요? 괜찮습니다. 바로 그 점을 에이전트에게 먼저 물어보면 됩니다.

메인 페이지의 배너 버튼이 /old/로 연결돼. /campaign/로 연결되어야 해.
먼저 버튼이 주소를 어디서 가져오는지 찾아서 해당 위치를 보여 줘.
아직 파일은 수정하지 마.
내가 확인한 뒤 주소가 정의된 곳을 수정해 줘.
배너 디자인은 건드리지 마.

수정한 뒤에는 처음 했던 동작을 다시 확인하세요. 버튼을 눌러 주소를 확인하고, 페이지에 프로모션 조건이 보이는지도 살펴보면 됩니다. 공통 주소 데이터가 바뀌었다면 이를 사용하는 다른 곳도 하나 더 확인하세요.

코드 구조 바꾸기

리더보드의 데이터 준비 코드가 거의 똑같은 형태로 두 번 작성되어 있어, 수정할 때마다 두 곳을 모두 고쳐야 합니다. 목표는 버전을 하나로 합치되 표의 결과는 바꾸지 않는 것입니다.

변경 후에도 그대로 유지되어야 하는 것을 불변 조건이라고 합니다. 여기서는 같은 데이터를 넣었을 때 참가자 순서와 표의 숫자가 그대로여야 합니다.

리팩터링에서 생기는 문제는 요란하지 않습니다. 점수가 같을 때 정렬 순서가 달라지고 반올림 결과가 바뀌어도 오류 메시지는 뜨지 않습니다. 표에 잘못된 값이 보일 뿐이죠. 에이전트는 두 버전을 합친 다음 아무것도 실행하지 않고도 "동작은 바뀌지 않았습니다"라고 보고할 수 있습니다. 또는 기존 정렬이 이상해 보인다며 슬쩍 "개선"할 수도 있습니다.

다음 순서의 데이터가 있다고 해 보죠. A는 10점, C는 20점, B도 20점, D는 15.5점입니다. 현재 표에는 C: 20, B: 20, D: 15.5, A: 10 순서로 표시됩니다. 리팩터링의 기준은 지금 코드가 내는 바로 이 결과입니다. 다른 결과를 원하더라도 일단은 그대로 두어야 합니다. 데이터 순서에는 의도가 있습니다. C가 B보다 먼저 있으므로 새 코드가 같은 점수를 이름순으로 정렬하면 B가 앞으로 튀어나옵니다. 소수점 값은 반올림이 달라졌는지 확인하는 데 도움이 됩니다.

두 가지 문제를 모두 막으려면 이렇게 요청할 수 있습니다.

리더보드 데이터 준비 코드가 두 곳에 반복돼 있어. 하나만 남겨 줘.
표의 동작은 바꾸지 마. 이상해 보이는 부분이 있어도
그런 부분은 따로 정리해 줘.
수정 전에 기존 검사를 실행하고 데이터 A: 10, C: 20, B: 20, D: 15.5의
표를 출력해 줘. 두 출력 결과를 저장해.
수정 후에도 같은 작업을 반복해서 비교해 줘.
보고서에는 데이터 준비 코드가 이제 어디에 있는지 보여 줘.

저장한 출력은 보고서의 "일치합니다"라는 한 줄에만 의존하지 말고 직접 비교하세요. 결과가 일치하면 적어도 이 데이터에서는 동작이 유지됐다는 뜻입니다. 그 이상은 아닙니다. 요청의 마지막 줄은 작업 자체를 확인합니다. 표가 같다는 사실만으로 중복 코드가 실제로 제거됐다고 볼 수는 없으니까요.

여기서는 어중간하게 끝내는 것이 아예 안 하느니만 못합니다. 복사본 하나는 남겨 두고 일부 호출만 새 버전으로 옮겼다고 해 보죠. 표는 그대로지만 데이터를 준비하는 방법은 여전히 두 가지입니다. 다음 요청에서 에이전트는 어느 쪽이 맞는지 알 수 없어 오래된 코드 위에 작업할 수도 있습니다. 합치기 시작했다면 하나의 버전으로 마무리하세요. 시간이 부족하다면 그 전에 멈추고 어디까지 진행했는지 기록해 두세요.

수정 없는 조사

Research는 다른 유형과 가장 크게 다릅니다. 결과물은 수정된 프로젝트가 아니라 답변입니다. 이 포털에서 궁금한 점은 프로모션 버튼이 연결할 주소를 코드 어디에서 정하는가입니다. 버그 수정도 같은 질문에서 시작하지만, 여기서는 수정을 전혀 요청하지 않습니다. 유형이 섞인 작업은 바로 이런 모습입니다. 먼저 조사하고, 그다음 별도 단계에서 수정합니다.

에이전트가 여기서 흔히 저지르는 실수는 두 가지입니다. 첫째, 조사 도중 직접 수정하기 시작합니다. 어색한 코드를 찾으면 설명하는 것보다 고치는 편이 더 쉬워 보일 수 있죠. 그러면 요구사항도 확인 절차도 없는 수정으로 바뀝니다. 둘째는 좀 더 미묘합니다. 에이전트가 코드를 읽고 페이지가 어떻게 작동하는지 자신 있게 설명하지만, 실제로 실행해 보지는 않았습니다. 읽은 내용을 요약한 것과 직접 관찰한 것은 겉으로 비슷해 보입니다.

세 번째 문제는 요청에서 시작됩니다. 다음에 무엇을 할지 미리 적으면 에이전트는 그 목표에 맞춰 답을 끌고 갈 수 있습니다. 현재 구조 대신 어떻게 하는 게 좋을지 의견을 내는 식이죠. 그러니 research에서는 지금 어떻게 구현되어 있는지 물어보고, 다음 단계의 계획은 잠시 미뤄 두세요. 아래 요청에는 나중에 주소를 고치겠다는 말이 없습니다.

메인 페이지의 배너 버튼이 주소를 어디서 가져오는지 찾아 줘. 아무것도 수정하지 마.
답변에는 관련 파일과 코드 위치, 서로 어떻게 연결되는지,
읽어서 확인한 내용과 실행해서 확인한 내용을 구분해서 적고,
아직 모르는 점도 알려 줘.

이 요청에 대한 좋은 답변은 대략 이렇습니다. "pages/home.html에서 버튼 주소는 promo.url을 가져오고, 값 /old/는 data/promo.json에 정의되어 있습니다. 두 파일을 읽어 확인했습니다. 페이지를 실행하지는 않았고, 스크립트가 주소를 바꾸는지도 확인하지 않았습니다." 연결 관계를 확인할 수 있고, 어디까지 알아냈는지도 솔직하게 밝혔습니다.

조사 중 수상한 부분을 찾았다면 답변에 별도 항목으로 남기세요. 무엇이 보이고 결론을 내리려면 무엇이 더 필요한지 적으면 됩니다. 수정은 별도 요구사항이 있는 다음 단계에서 하면 됩니다.

첫 단계와 경계

요점을 표 하나로 정리해 보겠습니다.

세 번째 열의 내용은 요청에서 미리 제한해 두면 좋습니다. 네 번째 열은 직접 확인하거나 에이전트에게 답변으로 보여 달라고 할 부분입니다.

반대로, 유형 이름만으로 어떤 일이든 허용되는 것은 아닙니다. "그냥 리팩터링이잖아요"라는 말이 모듈 절반을 다시 쓰라는 뜻은 아니고, "버그 수정이잖아요"라고 해서 디자인까지 바꿔도 되는 건 아닙니다. 유형은 질문과 확인 방법을 알려 줄 뿐, 경계는 여전히 여러분이 정해야 합니다.

요청문 여섯 개를 다시 써 보기

아래는 흔히 볼 수 있는 요청문 여섯 개입니다. 각각의 작업 유형을 정하고 에이전트가 추측할 부분을 줄이도록 결과, 경계, 확인 방법을 포함해 다시 써 보세요. 바로 뒤에 풀이가 있으니 먼저 직접 시도해 보세요.

1. "리더보드를 CSV로 내보내 주세요."
2. "리더보드에 참가자가 가끔 두 번 표시돼요. 고쳐 주세요."
3. "pages/home.html이 너무 크니 여러 파일로 나눠 주세요."
4. "메인 페이지는 왜 이렇게 느리게 로드되나요?"
5. "링크를 고치고 디자인도 다시 바꿔 주세요."
6. "포털을 더 좋게 만들어 주세요."

가능한 풀이 하나를 보겠습니다. 여러분의 표현은 달라도 괜찮습니다. 같은 기준이 들어 있는지가 중요합니다.

1. 리더보드 내보내기.
Feature입니다. 시나리오가 빠져 있습니다. 어떤 열을 파일에 넣을지, 행 순서는 어떻게 할지, 내보내기 버튼은 어디에 둘지 정해야 합니다. 놓치기 쉬운 데이터 관련 질문도 있습니다. 아직 점수가 없는 참가자도 파일에 포함할까요? 직접 정하지 않으면 에이전트가 대신 결정합니다. 하지 않을 일도 따로 적으세요. 가져오기, 열 선택, 다른 형식 지원은 이번 작업에 포함하지 않습니다. 확인은 간단합니다. A, B, C, D 데이터로 파일을 내보내 화면의 표와 행을 비교하세요.

2. 참가자가 두 번 표시됨.
Bugfix지만 여기서 중요한 말은 "고쳐 주세요"가 아니라 "가끔"입니다. 중복이 언제 생기는지 모르면 에이전트는 무엇을 고칠지 알 수 없습니다. 가장 쉽게 떠올릴 해결책은 표를 보여 주기 전에 중복을 제거하는 것이죠. 바로 이게 숨겨진 증상입니다. 먼저 어떤 동작 뒤에, 어떤 데이터에서 행이 두 배로 나타나는지 확인하세요. 그런 다음 코드를 수정하지 말고 문제가 생기는 위치를 찾도록 요청하세요. 확인할 때는 중복이 발생했던 바로 그 시나리오를 다시 실행하면 됩니다.

3. 큰 파일 나누기.
Refactoring입니다. 다만 불변 조건을 정하지 않아 "아무것도 망가지지 않았다"는 말을 확인할 기준이 없습니다. 페이지가 이전처럼 보이고 작동해야 한다고 적으세요. 배너, 프로모션 목록, 리더보드가 대상입니다. 수정 전에는 검사 결과도 기록해야 합니다. 그리고 유혹을 막아 두세요. 마크업을 여러 파일로 옮기는 김에 에이전트가 여백을 고치거나 클래스 이름을 바꿀 수도 있습니다.

4. 느린 페이지.
Research입니다. 속도를 높이라는 작업이 아니라 질문이죠. 하지만 에이전트는 "더 빠르게 만들어 줘"라는 요청으로 오해하기 쉽습니다. "아무것도 바꾸지 마"라는 제한이 없다면 추측에 따른 최적화를 내놓을 수 있습니다. 답변에서는 측정한 내용과 코드를 읽어 알아낸 내용을 구분하라고 하세요. "이미지 용량이 몇 MB입니다"는 에이전트가 확인했다면 사실이고, "스크립트가 느리게 만드는 것 같습니다"는 추측입니다. 원인을 알게 된 뒤 수정은 다음 단계에서 요청하면 됩니다.

5. 링크 수정과 디자인 변경.
한 요청에 결과가 두 가지입니다. 링크 수정은 bugfix입니다. 새 디자인은 네 가지 유형 중 어디에도 딱 들어맞지 않습니다. 동작이 아니라 모양이 달라지기 때문입니다. 가장 가까운 것은 feature지만, 결과를 시나리오가 아니라 목업이나 스크린샷 같은 참고 자료로 정의합니다. 먼저 bugfix 항목의 요청으로 링크를 수정하고, 확인을 마친 다음 디자인을 바꾸세요.

이제 @banner-mockup.png 목업에 맞춰 배너 디자인을 바꿔 줘.
버튼 주소와 문구는 수정하지 마.

6. 포털 개선.
유형을 정할 수 없고 굳이 추측할 필요도 없습니다. 요청한 사람에게 무엇이 지금 불편한지 물어보면 됩니다. 여러분이 직접 요청했다면 스스로에게 물어보세요. 에이전트에게 질문을 맡길 수도 있습니다.

무언가를 바꾸기 전에, 정확히 무엇을 개선할지 파악하는 데
필요한 질문을 최대 다섯 개까지 해 줘.
파일은 수정하지 마.

답을 듣다 보면 작업 유형은 대개 저절로 드러납니다.