당신은 최고의 엔지니어링 기술을 낭비하고 있습니다

내가 아는 최고의 엔지니어들은 사실 본인이 정말 못하는 일을 하며 하루를 보내고 있습니다.

그들은 코드를 작성하는 데 서툰 것이 아닙니다. 오히려 코딩에 있어 놀라운 실력을 갖추고 있죠. 하지만 그들은 자신이 가장 잘하는 일을 하는 것을 멈췄고, 아무도 그들에게 말해주지 않았습니다. 그들은 그저... 그렇게 흘러 들어갔을 뿐입니다. 저 또한 직장에서 너무 오랫동안 똑같은 일을 했습니다. 대규모 리포지토리 (repo) 마이그레이션 과정에서 Claude Code를 과도하게 사용하면서, 제가 실제로 시간을 어떻게 쓰고 있는지 뒤돌아보기 전까지는 그 사실조차 깨닫지 못했습니다.

이제 준비 과정이 곧 업무입니다. 그게 전부입니다.

코드를 작성하는 것이 아닙니다. 코드를 디버깅 (debugging) 하는 것도 아닙니다. 리뷰 (reviewing) 조차 아닙니다. Claude가 당신의 티켓 (ticket)을 한 번에 해결할지, 아니면 환각 (hallucination) 현상을 일으켜 순전한 AI 쓰레기를 만들어낼지를 결정하는 것은, AI가 단 한 줄의 코드를 쓰기 전에 당신이 문제를 얼마나 잘 설정하느냐에 달려 있습니다.

준비를 잘한다면 Claude는 이를 이해하고 아마 첫 시도에 완벽하게 해낼 것입니다. 준비를 하지 않는다면, 당신은 잘못된 것을 과도하게 확신하며 만들어내고 있는 AI와 싸우느라 세 시간을 허비하게 될 것입니다. 그리고 그 세 시간은 당신의 최고의 엔지니어링 기술인 문제를 사고하는 능력 (ability to think through problems) 이 뒷정리를 하는 데 완전히 낭비되는 시간입니다.

그래서 우리는 실제로 무엇이 되었는가?

마이그레이션 중간에 제가 깨달은 것은 이것입니다. 우리는 더 이상 코드를 작성하는 것이 아니라, 컨텍스트 (context)를 큐레이션 (curating) 하고 있다는 사실입니다.

이것은 기본적으로 항공 교통 관제 (air traffic control)와 같습니다, 그렇지 않나요? 관제사는 비행기를 직접 조종하지 않지만, 하늘의 모든 비행기는 안전하게 착륙하기 위해 관제사에게 의존합니다. 그들은 순서 (sequencing)를 정합니다. 어떤 비행기가 먼저 갈지, 어떤 비행기가 대기할지, 어떤 활주로가 비어 있는지를 말이죠. 그들에게는 제한된 공간 (공역) 이 있고, 만약 그 공간을 과부하 상태로 만들면 충돌이 발생합니다. 기술은 비행에 있는 것이 아니라, 조정 (coordination) 에 있습니다.

그것이 바로 우리가 지금 하고 있는 일입니다. '비행' — 즉 구현 (implementation) — 은 Claude가 처리합니다. 하지만 어떤 컨텍스트를 로드할지, 어떤 파일을 가리킬지, 어떤 순서로 문제를 해결할지, 그리고 어떤 제약 조건 (constraints) 을 설정할지를 결정하는 것은 바로 당신입니다. 당신은 제한된 공간을 관리하고, 아무것도 충돌하지 않도록 작업의 순서를 정하고 있습니다. 만약 당신의 순서 정하기가 틀린다면? 항공기가 아무리 유능하더라도 모든 것이 무너지고 맙니다.

이제 당신은 모든 코드 라인을 작성하는 대가로 급여를 받는 것이 아닙니다. 당신은 지금 당장 실제로 중요한 5%의 컨텍스트 (Context)가 무엇인지 파악하는 대가로 급여를 받습니다.

AI 코딩 도구의 베스트 프랙티스 (Best Practices)에 대해 말씀드리자면, 이들은 기본적으로 하나의 제약 조건으로 귀결됩니다. 즉, 당신이 AI에게 복잡한 문제를 해결해 달라고 요청할 때, AI는 전체 그림을 이해해야 한다는 것입니다. 파편화된 정보만 주면 AI는 추측하게 됩니다. 노이즈 (Noise)를 주면 AI는 압도당합니다. 컨텍스트 윈도우 (Context Window)를 잘못 채우면 Claude는 당신에게 경고하지 않습니다. 그저 자신 있게 잘못된 것을 만들어낼 뿐입니다. 그러면 당신은 15분이면 끝났을 일을 디버깅 (Debugging)하느라 3시간을 허비하게 될 것입니다.

그래서 제가 공유하려는 모든 기술은 무엇일까요? 바로 그 제약 조건을 관리하는 것입니다. 당신은 더 이상 프롬프트 (Prompt)를 작성하는 것이 아니라, AI가 실제로 무엇을 보아야 하는지를 결정하는 것입니다.

대부분의 사람들이 실수하는 지점

모두가 Claude에게 프로젝트 전체를 한꺼번에 주고 싶어 합니다. 다들 그렇습니다. 마치 "여기 내 코드베이스 (Codebase)가 있으니, 이걸 마이그레이션 (Migrate)하고 알아서 해결해 봐"라고 말하는 것처럼 말이죠. 그러면 Claude는 당신을 환각 (Hallucination)의 벽으로 몰아넣을 것입니다.

작업 범위가 극도로 (EXTREMELY) 제한되지 않으면 Claude는 혼란에 빠집니다. 정말 '극도로' 말입니다. 당신을 망치는 것은 바로 이것입니다. 겉보기에는 맞지만 실제로는 아무것도 하지 않는 환각된 코드 말입니다.

프롬프트 하나당 작업 하나. PR (Pull Request) 하나당 주요 변경 사항 하나. 먼저 뼈대부터 구축하세요. 한 번에 뼈 한 마디씩만요. 느려 보이나요? 훨씬, 훨씬 더 빠릅니다. 각 작업이 깔끔하게 완료되기 때문입니다.

이는 단순히 코드 품질을 넘어 PR 리뷰 가능성 (Reviewability), QA 테스트 (QA Testing), 디버깅 (Debugging) 측면에서도 중요합니다. 무언가 고장 났을 때, 어떤 변경 사항이 원인이 되었는지 정확히 알 수 있습니다. 작고 타겟팅된 컨텍스트 (Context)는 더 나은 결과로 이어집니다. AI가 분석해야 할 노이즈가 적을수록 출력값은 더 정확해집니다.

하지만 아무도 말하지 않는 부분이 있습니다. 무엇인가를 체계화하기 전에, 단 하나의 전체 작업을 수동으로 처음부터 끝까지 직접 수행해 보세요. 딱 하나만요. 시작부터 끝까지, 지름길 없이 말입니다.

그 첫 번째 반복(rep)에서 모든 것을 배우게 됩니다. Claude가 어디에서 어려움을 겪나요? 실제로 어떤 컨텍스트 (context)가 필요한가요? 어디에서 가정을 하나요? 제대로 작동할 때의 "해피 패스 (happy path)"는 어떤 모습인가요?

우리의 리포지토리 마이그레이션 (repo migration)의 경우, 우리가 처음으로 마이그레이션한 작업은 엉망이었습니다. 예상보다 훨씬 오래 걸렸죠. 하지만 그 과정은 Claude가 성공하기 위해 정확히 무엇이 필요한지 — 어떤 파일을 참조해야 하는지, 의존성 (dependencies)을 어떤 순서로 구축해야 하는지, 우리 리포지토리의 CLAUDE.md에 어떤 지침을 넣어야 하는지 — 를 가르쳐 주었습니다. 그 이후의 모든 작업은 스파이크 (spike)를 먼저 수행했기 때문에 극적으로 빨라졌습니다. 한 번 성공적으로 수행하고 나면, 그것이 당신의 참조 패턴 (reference pattern)이 됩니다. 그리고 예시 기반 프롬프트 (example-driven prompts)는 명세 기반 프롬프트 (spec-driven prompts)보다 훨씬 더 일관된 결과를 만들어냅니다. 매번. 예외 없이 말입니다.

그리고 사람들이 끊임없이 실수하는 미묘한 포인트가 하나 더 있습니다. 바로 어떤 것이 어느 레이어 (layer)에 속하는지 AI에게 말해주는 것입니다. 명시적으로 말이죠. 만약 당신의 아키텍처 (architecture)에 뚜렷한 레이어들이 있다면, Claude는 자신이 어느 레이어에서 작업하고 있는지 알아야 합니다. 그렇지 않으면 레이어 전반에 걸쳐 중복된 로직을 작성할 것입니다. "시스템이 사용자 인증 여부를 레이어 A 자체에서 확인해야 할까요, 아니면 레이어 B에서 확인해야 할까요?"라고 명시하지 않으면, Claude는 추측할 것입니다. 그리고 틀린 추측을 할 것입니다.

간과되는 부분: 당신의 실수는 성공보다 더 가치가 있습니다

첫 번째 작업이 성공하면, 그것을 참조 패턴 (reference pattern)으로 고정하세요. Claude가 당신의 설명에 의존하는 대신 실제 코드를 읽을 수 있도록 줄 번호와 함께 파일 경로를 포함하세요.

하지만 — 이 점은 매우 중요합니다 — 잘 작동하는 것만 기록하지 마세요. 무엇이 잘못되었는지도 기록하세요. 반복적인 작업을 하고 있다면, 실수와 그것을 피하는 방법을 기록하십시오. 직관에 어긋나는 동작, 일회성 예외 사항, 일반적인 아키텍처에 반하는 모든 것 — 그것들을 문서화하세요. 그렇지 않으면 Claude는 잘못된 패턴을 따를 것이고, 당신은 똑같은 문제를 세 번 디버깅하게 될 것입니다.

해결책은 이렇습니다: Claude가 실수를 하면, 스스로의 규칙을 업데이트하라고 지시하세요. 실수를 반복하게 두지 마세요. 시간이 흐르면서 당신의 문서화는 조직의 기억 (institutional memory)이 됩니다. 기본적으로 당신이 배운 모든 교훈이 고정되어 쌓이는 복리 기록인 셈입니다. 그것이 진정한 경쟁 우위입니다. 당신의 프롬프팅 (prompting) 기술이 아니라, 당신의 플레이북 (playbook) 말입니다.

전통적인 코드 작성 능력은 범용화 (commodity)되고 있습니다. 이제 희소성은 셋업 (setup) — 즉, 무엇을 요청해야 할지 아는 능력에 있습니다.

언제 준비를 멈춰야 하는가 (그리고 그냥 출시해야 하는가)

이러한 기술들은 복잡하고, 여러 세션에 걸치며, 여러 파일이 포함된 작업을 위한 것입니다. 과하게 적용하지 마세요.

생각하는 것과 실행하는 것을 분리하세요 — Claude에게 동일한 프롬프트 내에서 계획과 구현을 동시에 요구하지 마세요. 항상 먼저 계획을 세우라고 요청하세요. 코드가 아닌 계획을 출력하게 하십시오. 그 계획을 검토하세요. 그런 다음 실행하도록 지시하세요. 그리고 구현 중에 상황이 잘못되면, 계속 밀어붙이지 마세요. 다시 계획 단계로 돌아가 처음부터 다시 계획을 세우십시오. 새로운 계획은 망가진 구현물에 점진적인 패치 (patching)를 가하는 것보다 일관되게 더 낫습니다.

만약 작업이 하나의 프롬프트와 하나의 PR (Pull Request) 안에 들어온다면 — 한 줄짜리 버그 수정, 간단한 함수 추가, 설정 변경 등 — 그냥 직접 수행하세요. 모든 작업에 의존성 체인 (dependency chain), 스켈레톤 (skeleton), 참조 패턴 (reference pattern)이 필요한 것은 아닙니다. 올바른 질문은 이것입니다: "AI가 한 세션에 깔끔하게 담길 수 있는 것보다 더 많은 컨텍스트 (context)를 필요로 할 것인가?" 만약 그렇다면, 준비하세요. 아니라면, 그냥 요청하세요.

결론

과거에는 당신이 얼마나 많은 코드를 작성할 수 있는가로 평가받았습니다. 이제는 당신이 얼마나 잘 준비하는가로 평가받습니다. 그리고 이것은 강등이 아닙니다 — 당신이 요청하지 않은 승진입니다. 대부분의 사람들은 자신들이 승진했다는 사실을 아직 깨닫지 못했습니다.

Claude를 통해 최고의 결과를 얻고 있는 엔지니어들은 가장 영리한 프롬프트 (prompts)를 작성하는 사람들이 아닙니다. 그들은 Claude가 실패할 여지가 없도록 철저하게 준비하는 사람들입니다. 문제를 분해하세요. 작업 범위를 설정하세요. Claude에게 정확히 필요한 것만을 제공하세요 — 더도 말고 덜도 말고 딱 그만큼만 말입니다. 그리고 상황이 엉망이 되면, 세션 (session)을 종료하고 새로 시작하세요.

이제 코드는 스스로 작성됩니다. 당신의 역할은 그것이 올바른 것을 작성하고 있는지 확인하는 것입니다.

저는 Amazon과 The New York Times에서 근무했던 5년 이상의 경력을 가진 소프트웨어 엔지니어 (software engineer)입니다. 이것은 이론적인 예측이 아니라 실제 운영 환경 (production)에서의 업무를 통해 얻은 교훈입니다.