AI 개발은 프롬프팅의 문제가 아니라 문서화의 문제다
요약
AI 코딩 도구의 성능 저하는 프롬프팅 기술의 부족이 아닌 컨텍스트 관리의 부재에서 발생합니다. 문서화를 AI와의 공유 메모리 시스템으로 활용하여 명확한 요구사항과 명세를 제공하는 것이 핵심입니다.
핵심 포인트
- AI 코딩의 핵심은 프롬프팅이 아닌 컨텍스트 관리임
- 문서화를 AI와 개발자 간의 공유 메모리 시스템으로 활용해야 함
- 명확한 명세(Specification)가 없으면 AI는 추측에 의존해 환각을 일으킴
- 계획, 문서화, 구축(Plan, Document, Build) 패턴의 중요성
대부분의 개발자들은 AI 코딩 도구를 사용하는 방식이 비슷합니다. 채팅창을 열고, 원하는 것을 설명한 뒤, 코드를 작성해 달라고 요청합니다. 때로는 작동하기도 합니다. 하지만 더 자주 발생하는 일은, 거의 비슷하지만 약간 틀린 결과물을 만들어내어 이를 수정하는 데 절약한 시간보다 더 많은 시간이 소요되는 것입니다.
저 역시 업무에서 AI를 사용하는 접근 방식을 바꾸기 전까지는 그런 경험을 했습니다. 차이점은 모델이 아니었습니다. 바로 방법론이었습니다. 저는 전문적인 프로젝트와 개인 프로젝트 모두에서 GitHub Copilot과 Claude를 사용하며 이 접근 방식을 적용해 왔고, 이는 일회성 프롬프팅 (ad-hoc prompting)보다 지속적으로 뛰어난 성능을 보여주었습니다. 제가 결국 깨달은 것은 저에게 프롬프팅 문제가 있었던 것이 아니라, 컨텍스트 관리 (context management) 문제가 있었다는 사실입니다. 문서화를 프로젝트 서류가 아닌 저와 AI 사이의 공유 메모리 시스템 (shared memory system)으로 취급하기 시작하자마자 즉각적인 이점을 느낄 수 있었습니다.
내가 계속 마주했던 문제
적절한 컨텍스트 (context) 없이 AI 도구에 무언가를 만들어 달라고 요청하는 것은, 유능한 개발자에게 대략적인 구두 설명만으로 작업하라고 요구하는 것과 같았습니다. AI는 빈틈을 추측으로 채웠습니다. 결과물은 저의 실제 요구사항이 아니라 그러한 추측을 반영했습니다.
그 결과는 컴파일은 되지만, 그럴듯해 보이기만 할 뿐 핵심을 놓친 코드였습니다.
이를 악화시키는 두 번째 문제가 있었습니다. AI 세션에는 제한이 있습니다. 컨텍스트 윈도우 (context windows)는 가득 차고, 세션은 만료되며, 프로젝트 중간에 다시 시작하려면 도구가 더 이상 접근할 수 없는 모든 내용을 다시 설명해야 합니다. 구조가 갖춰져 있지 않으면 매번 새로운 세션을 시작할 때마다 처음부터 다시 시작하는 기분이 들었습니다. 도구는 방향을 잃거나, 이전의 결정을 부정하거나, 더 이상 볼 수 없는 코드에 대해 환각 (hallucinate) 현상을 일으켰습니다. 문제는 도구가 아니었습니다. 공유된 컨텍스트의 부재였습니다.
소프트웨어 엔지니어링이 이미 알고 있었던 것
돌이켜보면, 저는 소프트웨어 엔지니어들이 수십 년 동안 이해해 온 사실을 재발견하고 있었습니다. 요구사항 (Requirements)이 중요합니다. 명세 (Specifications)가 중요합니다. 공유된 이해 (Shared understanding)가 중요합니다.
아키텍처 결정 기록 (Architecture Decision Records)을 작성하는 팀들은 단순히 문서 작성을 즐기기 때문에 그렇게 하는 것이 아닙니다. 기록된 문서 없이 내려진 결정은 잊히거나, 잘못 기억되거나, 혹은 보이지 않게 뒤집히기 때문에 그렇게 하는 것입니다. AI 도구를 사용할 때도 동일한 역학이 적용되지만, 그 위험 요소가 단일 세션(Single session) 내로 압축되어 있다는 점이 다릅니다. 명세 (Specification)가 없는 AI 도구는 문서도 없고 인수인계도 없이 프로젝트에 첫날 합류한 개발자와 정확히 같은 상황에 놓이게 됩니다. AI는 무언가를 수행하겠지만, 의도 (Intent)가 아닌 추측 (Guesswork)에 기반하여 수행할 것입니다.
AI가 대체하지 못한 것은 실행 전의 명확성 (Clarity)에 대한 필요성입니다. 오히려 AI는 그 필요성을 증폭시켰습니다. 모호한 요구사항을 가지고 작업하는 개발자는 명확하게 하기 위한 질문을 던지거나 모호함을 표시할 수 있습니다. 하지만 AI 도구는 자신 있게 진행하여 잘못된 결과물을 만들어낼 것입니다. 원칙은 변하지 않았습니다. 레버리지 (Leverage)가 변했을 뿐입니다. 서투르게 작성된 명세는 개발자의 속도를 늦출 수 있지만, 동일한 모호함이 AI 시스템을 완전히 다른 경로로 빠뜨릴 수 있습니다.
내가 정착한 패턴: 계획, 문서화, 구축 (Plan, Document, Build)
여러 프로젝트를 거치며, 나는 이 일관된 3단계 접근 방식에 정착했습니다. 개인마다 차이는 있을 수 있지만, 나에게 있어 이 방식은 결과물의 품질을 높이는 동시에 작동하는 코드를 생산하는 데 드는 전체 시간을 줄여주었습니다.
1단계는 AI와 함께 계획하는 것입니다. 코드 한 줄을 쓰기 전에, 나는 이 도구를 사고의 파트너 (Thinking partner)로 활용합니다. 나는 문제, 제약 조건 (Constraints), 피하고 싶은 것, 그리고 성공의 모습이 어떠해야 하는지를 설명합니다. 이것은 프롬프트 (Prompt)가 아니라 대화 (Conversation)입니다. 종종 여러 번의 대화가 오가며, 내가 생각을 정리함에 따라 계획은 계속 변경됩니다.
2단계는 공유 메모리 시스템 (Shared Memory System)을 생성하는 것입니다. 계획이 견고하다고 느껴지면, 도구에게 이를 구조화된 구현 가이드 (Implementation Guide)로 변환하도록 요청합니다. 이는 개발자나 완전히 새로운 AI 세션이 추가적인 설명 없이도 프로젝트를 처음부터 구축할 수 있을 만큼 충분히 상세해야 합니다. 다운로드 모듈의 경우, 입력 소스, 재시도 동작 (Retry behaviour), 저장 위치, 에러 처리 (Error handling), 그리고 예상되는 출력 계약 (Output contracts)을 정의하는 것을 의미합니다. 모든 통합 지점 (Integration point)을 기록하고, 모든 예외 케이스 (Edge case)를 고려해야 합니다.
3단계는 이를 바탕으로 구축하는 것입니다. 개별 작업들은 더 작고 독립적인 단위가 됩니다. "X를 수행하는 파이프라인을 구축해줘" 대신, 각 프롬프트는 "이 가이드의 3절에 기술된 다운로드 모듈을 구현해줘"가 됩니다. 컨텍스트 (Context)가 추론되는 것이 아니라 명시적이기 때문에 결과물이 더 정확해집니다.
실전에서의 공유 메모리 시스템
AI 도구는 세션 간에 메모리 (Memory)를 유지하지 않습니다. 새로운 대화를 시작할 때마다, 도구는 당신이 어제 무엇을 만들었는지, 어떤 아키텍처 결정 (Architectural decisions)이 내려졌는지, 혹은 어떤 제약 사항 (Constraints)에 합의했는지 알지 못합니다. 가이드가 없다면, 모든 세션의 첫 부분은 재구성 (Reconstruction)에 할애됩니다. 하지만 가이드가 있다면, 도구에게 문서를 건네주고 관련 섹션을 지목함으로써 정확히 중단했던 지점부터 다시 시작할 수 있습니다.
이 방식이 작동하게 만드는 습관은 진행 상황을 진행하면서 가이드에 직접 기록하는 것입니다. 완료된 섹션은 완료(Done)로 표시합니다. 구현 과정에서 변경된 결정 사항들은 본문 내에 기록합니다. 도구는 추측하는 것이 아니라 사실 (Facts)을 읽게 됩니다. 실제로 이 방식은 제가 정기적으로 겪었던 드리프트 (Drift) 및 환각 (Hallucination) 문제를 거의 완전히 제거해 주었습니다.
또한 이는 세션 제한 (Session limits)에 대한 불안감을 없애줍니다. 각 세션은 가이드에서 추출된 제한된 작업을 수행하며, 다음 단계로 넘어가기 전에 진행 상황이 캡처됩니다. 다음 세션은 그 지점에서 깔끔하게 이어집니다.
도움이 된 몇 가지 습관들
구현 가이드(implementation guide)가 존재하면, 프롬프트 자체는 더 단순해집니다. 이러한 습관들은 시행착오를 통해 발전해 왔으며, 제가 테스트한 두 가지 도구 모두에서 일관되게 효과가 있었습니다.
매 세션 시작 시 가이드를 명시적으로 참조하세요. 관련 섹션을 제공하고 무엇을 구현하고 있는지 명확하게 밝히십시오. 대화의 연속성(conversational continuity)에만 의존하는 것은 출력 품질을 저하시킵니다. 명시적인 컨텍스트(context)를 제공하는 것이 품질을 회복시킵니다.
한 번에 하나의 모듈씩 진행하세요. 경계가 정해진 작업(Bounded tasks)은 신뢰할 수 있고 테스트 가능한 코드를 생성합니다. 경계가 없는 프롬프트(Unbounded prompts)는 지름길을 택하게 만들고 일관성을 해칩니다. 명세(specification)가 그 경계를 정의합니다.
단순히 구현(implementation)에 대한 테스트가 아니라, 명세에 대한 테스트를 요청하세요. 가이드가 올바른 동작을 정의하고 있다면, 그 정의를 바탕으로 테스트를 작성할 수 있습니다. 이는 구현 중심의 테스트와는 다른 범주의 버그를 잡아낼 수 있게 합니다.
가이드를 살아있는 문서(living document)로 취급하세요. 구현 과정에서 무언가 변경되면 즉시 업데이트하십시오. 이는 결정 사항을 재검토할 때 ADR(Architecture Decision Records)을 최신 상태로 유지하는 것과 같습니다. 그렇지 않으면 공유 메모리(shared memory)가 현실과 괴리되어 더 이상 신뢰할 수 없게 됩니다.
이 접근 방식이 과할 때 (When This Approach Is Overkill)
모든 작업에 이 방식이 필요한 것은 아닙니다. 작은 스크립트, 빠른 일회성 자동화, 또는 좁은 범위의 프로토타입의 경우, 사전 계획에 드는 오버헤드(overhead)가 이점보다 더 큽니다. 이럴 때는 직접적인 프롬프팅(direct prompting)이 잘 작동하며 반복 비용도 낮습니다.
이 패턴은 여러 구성 요소가 있거나, 한 세션 이상에 걸쳐 진행되거나, 모듈 간의 일관성이 중요한 모든 작업에서 빛을 발합니다. 프로젝트가 복잡해질수록, 공유 메모리 시스템의 부재로 인해 발생하는 드리프트(drift), 재작업(rework), 그리고 디버깅 시간의 비용은 더욱 커집니다.
이것이 실제로 바꾸는 것
현실은 대부분의 개발자가 AI 도구를 프롬프팅의 문제로 다루고 있지만, 실제로는 컨텍스트 관리(context management) 문제에 직면해 있다는 것입니다. 더 나은 프롬프트는 미미한 이득을 줄 뿐입니다. 하지만 공유 메모리 시스템은 품질의 한계치(quality ceiling) 자체를 완전히 바꿔 놓습니다.
이 차이를 한 번 경험하고 나면 모든 것이 명확해집니다. 도구는 표류(drifting)를 멈춥니다. 세션이 보이지 않는 한계와 싸우고 있다는 느낌도 사라집니다. 입력값이 일관되기 때문에 출력값(output) 또한 일관되게 유지됩니다. 명세(specification)는 단순히 AI를 안내하는 것에 그치지 않습니다. 애초에 신뢰할 수 없는 출력을 만들어내는 조건들을 제거합니다.
AI 개발은 기본적으로 프롬프팅 (prompting)의 문제가 아닙니다. 그것은 문서화 (documentation)의 문제입니다. 이에 따라 적절히 대처한다면, 오늘날 사용 가능한 도구들은 대부분의 개발자가 현재 경험하고 있는 것보다 훨씬 더 강력한 능력을 발휘하게 될 것입니다. 이는 생산성 측면에서 결코 작은 변화가 아닙니다. 여러 세션에 걸쳐 진행되는 복잡한 프로젝트의 경우, 이는 제대로 작동하는 도구와 그렇지 않은 도구 사이의 차이를 만듭니다.
시작하는 방법
진입 장벽은 낮습니다. 선택한 AI 도구와 대화를 시작하여 구현 방법(implementation)이 아닌, 해결하고자 하는 문제(problem)를 설명하세요. AI에게 구조화된 계획(structured plan)을 생성하도록 요청하고, 맞지 않는 부분은 거부하며, 당신이 구축하고자 하는 것을 정확하게 나타낼 때까지 계획을 다듬으세요. 그런 다음, 그 계획을 새로운 AI 세션이 처음부터 실행할 수 있는 상세한 구현 가이드(implementation guide)로 변환하도록 요청하세요.
그 문서는 제가 작성했던 그 어떤 개별 프롬프트 (prompt)보다 저에게 더 큰 가치를 주었습니다. 저는 다양한 프로젝트 유형에서 Copilot과 Claude 모두에 이 패턴을 사용해 왔으며, 어떤 도구를 사용하든 핵심 접근 방식은 동일하게 유지됩니다. 왜냐하면 이 방식이 해결하는 근본적인 문제가 두 경우 모두 같기 때문입니다.
다른 무엇보다도 이 하나의 능력, 즉 공유 메모리 시스템 (shared memory system)을 구축하는 것을 개선하는 것은, 오늘날 개발자가 AI 도구와 작업하는 방식에 있어 적용할 수 있는 가장 레버리지가 높은 (highest-leverage) 변화 중 하나입니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기