클로드 코드의 비밀스러운 삶: 첫 번째 프롬프트

Source: Dev.to

위의 링크에 있는 전체 텍스트를 제공해 주시면, 해당 내용을 한국어로 번역해 드리겠습니다. 코드 블록, URL 및 마크다운 형식은 그대로 유지하고, 본문만 번역해 드립니다.

프롬프트의 품질이 곧 사고의 품질인 이유

Margaret는 선임 소프트웨어 엔지니어이고, Timothy는 그녀의 후배 동료입니다. 그들은 런던의 웅장한 빅토리아 시대 도서관에서 일합니다 — 정확성이 중시되고 모호함은 부드럽게 바로잡히는 그런 곳이죠. Timothy는 실제 문제와 자신이 꽤 자랑스러워하는 프롬프트를 가지고 찾아왔습니다.

Episode 3: 첫 번째 프롬프트의 기술

티모시가 가져온 것

그는 노트북을 이미 켜진 상태로 도착했으며, 마가렛은 이를 좋은 신호로 받아들였다. 이는 그가 문을 들어서기 전에 이미 생각하고 있었다는 뜻이었다.

“오늘은 진짜 문제야,” 그가 의자에 앉으며 말했다. “장난감 예제가 아니라. 코드베이스에서 나온 실제 문제야.”

“좋아,” 마가렛이 말했다. “네가 쓴 걸 보여줘.”

그는 노트북을 그녀에게 향해 돌렸다. 화면에는 그가 준비한 프롬프트가 표시되어 있었다:

“내 데이터 처리 파이프라인의 성능 문제를 해결해 주세요.”

마가렛은 그것을 읽었다. 그리고 인내가 필요한 순간에만 쓰는 특별한 표정을 안경 너머로 그에게 보였다.

“티모시,” 그녀가 말했다, “이 프롬프트에 뭐가 문제야?”

그는 약간 움직이며 말했다. “꽤 명확하다고 생각했어요.”

“전혀 명확하지 않아,” 그녀가 친절하게도 말했다. “이건 원하는 것이 무엇인지 알지만 아직 그것을 설명하는 작업을 하지 않은 사람의 프롬프트야.”

심문

그녀는 노트북을 그에게 다시 돌려놓고 손을 모았다.

“파이프라인에 대해 말해 주세요. 무엇을 하나요?”
“고객 거래 기록을 처리합니다. 데이터베이스에서 읽고, 비즈니스 로직을 적용한 뒤, 결과를 보고 테이블에 기록합니다.”

“레코드는 얼마나 있나요?”
“작은 실행에서는 몇 천 개 정도이고, 월간 배치에서는 약 4 백만 개 정도입니다.”

“성능 문제는요. 정확히 무슨 일이 일어나고 있나요?”
“월간 배치가 시간 초과됩니다. 예전에는 약 40분 정도에 완료됐었는데, 이제는 3시간 이상 걸리면서 중간에 실패하고 있습니다.”

“언제부터 바뀌었나요?”
티모시가 잠시 멈췄다. “약 3 주 전이요.”

“3 주 전에는 무엇이 바뀌었나요?”
또다시 멈춤—이번엔 더 길었다. “규제 준수를 위해 새로운 검증 단계를 추가했습니다.”

마가렛은 그를 똑바로 바라보았다. “그리고 당신은 Claude Code에게 내 데이터 처리 파이프라인의 성능 문제를 해결해라 라는 프롬프트를 주었죠.”

그는 약간 부끄러워하며 말할 여유를 가졌다. “그렇게 말하면—”

“당신이 그렇게 말한 이유는 바로 당신이 그렇게 적었기 때문이에요.” 그녀는 펜을 집어 들었다. “Claude Code는 텔레파시를 할 수 없습니다. 당신의 4 백만 레코드, 규제 검증, 3시간 타임아웃, 그리고 이 문제가 3 주 전에 시작됐다는 사실을 알지 못합니다. 당신은 맥락도, 제약도, 성공이 어떤 모습인지에 대한 힌트도 없이 문제만을 넘겨준 것이죠. 당신은 그것이 어떤 결과를 낼 것이라고 상상하나요?”

“뭔가 일반적인 것,” 그가 인정했다.

“뭔가 일반적인 것,” 그녀가 확인했다. “아마도 설득력 있게 들릴지는 몰라도 당신의 구체적인 상황에는 완전히 맞지 않는 결과일 겁니다. 그리고 그것을 발견하는 데 한 시간을 써야 할 것이고, 시작 단계에서 5분만이라도 신중히 생각했더라면 전혀 발생하지 않았을 문제입니다.”

네 가지 질문

그녀는 메모장에 작은 격자를 그렸다 — 네 개의 상자.

“실제 엔지니어링 문제에 대한 프롬프트를 작성하기 전에,” 그녀가 말했습니다, “네 가지 질문에 답하세요. 반드시 프롬프트 자체에 넣어야 하는 것은 아니고, 먼저 스스로의 머릿속에서 답하고, 그 다음에 작성하는 내용에 반영하면 됩니다.”

1. 맥락은 무엇인가?
   우리가 작업하고 있는 시스템은 무엇이며, 그 시스템은 무엇을 수행하고, 어떤 제약 조건이 있나요? Claude Code는 문제가 존재하는 세계를 이해해야 합니다.

2. 구체적인 문제는 무엇인가?
   ‘성능 문제’가 아니라 구체적으로 설명하세요. 파이프라인은 매월 400만 건의 레코드를 처리하고, 최근 3시간 후에 타임아웃이 발생하기 시작했으며, 이전에는 40분 안에 완료되었습니다. 이 변화는 검증 단계가 추가된 시점과 일치합니다.

3. 이미 시도했거나 고려한 것이 있나요?
   이미 배제한 접근 방식이 있다면 명시하세요. 이론이 있다면 공유하세요. Claude Code에게 처음부터 생각해 달라는 것이 아니라, 당신과 함께 생각해 달라는 것입니다.

4. 좋은 해결책은 어떻게 보이나요?
   제약 조건은 무엇인가요? 특정 시간 내에 완료되어야 하나요? 출력 형식을 변경하면 안 되나요? 코드베이스의 어떤 부분을 건드리지 않아야 하나요? 시작하기 전에 성공을 정의하지 않으면, 성공을 보았을 때 인식하지 못하게 됩니다.

그녀는 펜을 내려놓으며 말했습니다. “이제 프롬프트를 다시 작성하세요.”

The Rewrite

Timothy는 몇 분 동안 조용히 있었다. Margaret는 차를 마시며 그를 재촉하지 않았다. 좋은 생각은 서두를 수 없으며, 그녀는 오래전에 침묵이 도움보다 더 생산적일 때가 많다는 것을 배웠다.

그는 노트북을 그녀에게 돌렸다.

“Python으로 만든 데이터 처리 파이프라인이 PostgreSQL 데이터베이스에서 고객 거래 기록을 읽고, 비즈니스 로직 검증을 적용한 뒤 결과를 보고 테이블에 기록합니다. 월간 배치 작업에서 약 400만 건의 레코드를 처리하던 파이프라인이 최근 3시간 후에 타임아웃되기 시작했는데, 이전에는 40분 안에 완료되었습니다. 이 변화는 3주 전에 새로운 규제 검증 단계가 추가된 시점과 일치합니다. 검증 로직이 루프 안에서 데이터베이스 쿼리를 실행하고 있는 것으로 추정되지만 아직 확인하지 못했습니다. 해결책은 출력 형식이나 테이블 스키마를 변경해서는 안 됩니다. 병목 현상을 찾아내고 이를 해결할 방법을 제시해 주실 수 있나요?”

Margaret는 그 내용을 꼼꼼히, 두 번이나 읽었다.

“더 나아졌네,” 그녀가 말했다. “훨씬 나아졌어.”

“그냥 나아졌다고?”

“상당히 나아졌어,” 그녀가 허락했다. “맥락, 구체적인 문제, 일정, 가설, 그리고 제약 조건을 모두 제공했어. 이제 Claude Code가 실제로 유용한 일을 할 수 있어.” 그녀는 잠시 멈추며 말했다. “추가로 제안하고 싶은 건—먼저 원하는 것을 말해줘. 마지막에 말하지 말고.”

“무슨 말이야?”

“실제 요청을 마지막 문장에 숨겨두었잖아. 원하는 결과를 먼저 제시하고 그 다음에 맥락을 제공해. 예를 들어: Python 데이터 파이프라인에서 성능 저하를 진단하고 수정해야 합니다—그 다음에 나머지를 덧붙이면 돼.”

변경 사항

Timothy가 조정을 했습니다. 프롬프트는 이제 의도에 대한 명확한 진술로 시작하고, 그 뒤에 그가 이미 작성한 모든 내용이 이어집니다.

“거기,” Margaret가 말했습니다. “이제 보낼 만한 프롬프트가 생겼어요.”

“뭐 좀 물어볼 수 있을까?”

Timothy가 말했습니다. “두 번째 프롬프트가 훨씬 길어요. 길이가 항상 좋다는 뜻인가요?”

“아니요,” Margaret가 즉시 대답했습니다. “길이가 장점이 아니라 정밀함이 장점입니다. 두 번째 프롬프트가 더 긴 이유는 첫 번째 프롬프트에 필수 정보가 빠져 있었기 때문이에요. 첫 번째 프롬프트가 정확하고 완전했더라면 적절한 길이가 되었을 겁니다.”

그는 그녀를 뚫어지게 바라보았습니다.

“묻는 질문은 *‘내가 충분히 썼는가?’*가 아니라 ‘이 안에 Claude Code가 나를 도와주기 위해 필요한 모든 것이 들어 있나요?’ 입니다. 때로는 두 문장일 수도 있고, 때로는 한 단락일 수도 있습니다. 문제가 길이를 결정하고, 그 반대는 아닙니다.”

Timothy는 천천히 고개를 끄덕였습니다.

“그러니까 프롬프트는 사실… 명확한 생각을 적어 놓은 것이라는 말이군요.”

“바로 그거죠,” Margaret가 말했습니다. “그게 언제나 그래왔습니다. Claude Code에 어려움을 겪는 개발자들은 도구 자체가 아니라 도구를 사용하기 전에 해야 할 사고 과정에서 어려움을 겪는 경우가 많아요. 프롬프트는 여러분의 이해 수준을 드러냅니다. 이해가 흐릿하면 프롬프트도 흐릿해지고, 출력도 흐릿해집니다.”

“그리고 내 이해가 명확하다면—”

“프롬프트도 명확해지고, Claude Code는 놀라운 작업을 수행할 겁니다.”

그녀는 메모장을 닫았습니다.

“이게 바로 제가 처음 대화에서 말했듯이, 도구는 여러분이 가져다 주는 것을 증폭시킨다는 이유입니다. 프롬프트에서 그 점이 가장 잘 드러나요.”

공유할 가치가 있는 가설

“가설을 언급했었죠,” 마가렛이 말했다. “검증 로직이 루프 안에서 데이터베이스 쿼리를 실행하고 있을지도 모른다고요. 정말 그렇게 생각하나요?”

“그게 가장 가능성이 높은 상황이에요,” 티모시가 답했다. “검증 단계에서 각 트랜잭션을 기준 테이블과 비교하고 있거든요. 만약 한 번에 하나씩 처리하고 있다면—”

“그럼 N+1 쿼리 문제가 발생한 거예요,” 마가렛이 말했다. “수백만 개의 개별 데이터베이스 호출 대신 소수의 효율적인 배치 쿼리만 있으면 되는데요.”

“그럼 모든 것이 설명되겠군요.”

“많은 부분이 설명될 겁니다, 맞아요.” 그녀가 그를 바라보며 말했다. “가설이 있으면 공유하세요. 클로드 코드가 당신의 허가를 필요로 해서 생각하는 것이 아니라—가설 자체가 정보이기 때문입니다. 도구에게 어디를 먼저 살펴봐야 할지, 어떤 접근이 탐색할 가치가 있는지, 그리고 어떤 것이 아마도 막다른 길인지 알려줍니다. 공유된 가설은 제약이 아닙니다. 그것은 선물입니다.”

티모시는 화면에 보이는 수정된 프롬프트를 바라보았다.

“나는 그 선물을 줬어요.”

“맞아요.” 마가렛은 작은 미소를 지었다. “그리고 만약 당신의 가설이 틀렸다면, 클로드 코드가 왜 그런지 알려줄 가능성이 높아요—그것도 유용하죠. 당신은 생각을 공유함으로써 아무것도 잃지 않아요. 오히려 얻는 것이 더 많습니다.”

Before He Sent It

One more thing, Margaret said, just as Timothy was about to hit Enter. “Read it aloud.”

He looked up. “I beg your pardon?”

“Read the prompt aloud. Before you send it.”

He did — slightly self‑consciously, but thoroughly. Halfway through, he stopped.

“I said recently twice,” he said.

“You did.”

“And I never specified which table the results are written to.”

“No.”

He made both corrections without being asked. Margaret said nothing; she didn’t need to.

When he sent it, the prompt was clean, precise, and complete. Claude Code’s response came back detailed, specific, and directly useful — identifying the likely N+1 pattern, suggesting a batched lookup approach, and flagging two other areas worth investigating.

Timothy read it with the focused expression of someone who understood what they were looking at.

“It knew exactly where to look,” he said quietly.

“Because you told it exactly where to look,” Margaret replied. “That is the partnership. You bring the context and the thinking. It brings the breadth and the speed. Neither is sufficient alone.”

She picked up her tea.

“The first prompt is not the beginning of the work, Timothy. It is the end of the thinking. Get the thinking right first, and everything that follows will be better for it.”

Outside, London went about its afternoon. Inside the library, a developer had just learned something that would serve him for the rest of his career — not a trick, not a shortcut, but a discipline.

The discipline of thinking clearly before asking.

Next episode: Margaret and Timothy explore what happens when Claude Code gets it wrong — confidently, convincingly, and completely. How to catch the errors that look like answers.

The Secret Life of Claude Code publishes on tech-reader.blog every other day.

If this series is useful to you, share it with a developer who needs to hear it.

Aaron Rose is a software engineer and technology writer at tech-reader.blog. For explainer videos and podcasts, check out the Tech‑Reader YouTube channel.