Claude Code를 최고의 설계 파트너로 만들기

• 처음 Claude Code를 사용할 때 단순히 프롬프트 지시와 수정 반복 방식으로 접근했지만, 복잡한 작업에서는 대화 기록 의존성과 컨텍스트 한계 문제를 겪음
• 이를 해결하기 위해 기능 구현 전에 계획 문서(plan document)를 작성하게 하고, 이를 새로운 세션의 단일 진실의 원천(SSOT) 으로 삼음
• 계획 문서는 요구사항 재정리, 구현 세부 설명, 코드 품질 확인 명령어 등을 포함하며, 구현 중에도 살아있는 문서(living document) 로 지속 업데이트됨
• 이렇게 하면 맥락 손실 문제가 해결되고, 새로운 세션에서도 단일 문서만으로 프로젝트를 이어갈 수 있음
• 결과적으로 AI는 단순한 실행 도구가 아니라, 개발자가 설계를 더 깊이 고민하고 기록하도록 유도하는 협력적 디자인 파트너 역할을 하게 됨

---

문제의식: 단순 대화 방식의 한계

• Claude Code와 대화형으로 작업을 진행할 때, 간단한 작업에는 적합하지만 복잡한 작업이 커질수록 여러 가지 중대한 한계가 발생함
  • 대화가 유일한 진실의 원천이 되어, 새로운 메시지가 이전 지시를 쉽게 덮어쓸 수 있으며, 그 순간을 명확히 인지하기 어려움
  • AI의 컨텍스트 크기 한계로 인해, 대화가 길어질수록 앞선 정보가 누락될 수 있음
  • Claude Code가 대화 압축 기능을 갖추고 있지만 이 한계를 완전히 해소하지는 못함

플랜 문서 중심 방식 실험

• 이런 문제 해결을 위해 플랜 문서 기반 접근을 시도함
  • 시작 시, Claude Code에게 구현할 기능이나 수정해야 할 버그 등에 대해 가능한 상세하게 설명함
  • 참조할 수 있는 기존 소스 파일이나 이전에 작성된 플랜 문서도 언급함
  • 지나치게 구체적인 구현 지시는 피하며, AI의 설계 제안 역할을 유도함
• 플랜 문서가 충분히 만족스러우면 대화 기록을 지우고 해당 플랜만 맥락으로 새로 시작함
  • 플랜에는 기능 요약, 구현 계획, 코드 및 의사코드, 타입/린트/테스트 명령 등이 포함되어 있음

협업적 설계 프로세스

• AI가 제안한 설계가 마음에 들지 않을 때, 구체적 피드백을 제공해 수정된 접근법을 유도함
• 논의 과정에서 AI의 첫 제안이 더 적합했다는 점을 깨닫기도 하며, 자체 설계만으로 코딩을 진행할 때보다 더 효율적임
• 체계적인 대화는 동료 개발자와 플랜을 논의하는 것과 유사한 경험 제공
• AI는 단독으로 전혀 다른 접근법을 제시하진 않으나, 질의하면 다른 대체안을 제안할 수도 있음

살아있는 문서(Living Document) 방식

• 플랜 문서를 한 번 작성하고 끝내지 않고, 기능 구현 도중에도 계속 갱신하게 함
  • 구현과정이나 타입 체크, 린트, 테스트 과정에서 드러나는 변경사항을 실시간 반영함
• 코드 커밋할 때마다 플랜의 최신 상태 점검을 요청하는 습관 형성
• 항상 최신의 플랜이 유지됨에 따라, 새 대화 세션에서도 플랜만 첨부하면 맥락 손실 없이 그대로 이어나갈 수 있음

코드 리뷰 및 개발 습관 변화

• 구현이 시작된 후에는 주기적으로 변경사항을 확인하고, 만족스러우면 AI의 작업을 더 신뢰하기도 함
• 최종 코드 검토 시 업데이트된 플랜 문서가 기술적 의사결정 근거를 파악하는 데 도움이 됨
• 사전에 치밀하게 플랜을 세워 문서화함으로써 더 나은 개발자로 성장하는 경험을 얻음
  • AI에게 설명해야 하므로 자신의 의사결정 과정을 명확하게 정리하게 됨

혼돈에서 체계로

• 이 방식은 플랜 문서가 진실의 단일 원천이 되게 하고, 맥락 손실 문제를 해소하며, 아키텍처적 사고를 촉진함
• 플랜 문서는 사양과 구현 로그를 모두 포함하며, ‘무엇’뿐만 아니라 ‘왜’, ‘어떻게’까지 기록함
• 끝 결과는 계획적이고, 문서화가 잘 되어 있으며, 신뢰성 높은 개발 프로세스임
• AI는 단순한 구현자가 아니라 협업 설계 파트너로 자리매김함

[jamsya]

개발자의 워크 플로우에서 PM과 아키텍트 역할의 비중이 더 커지는듯 합니다.

[GN⁺]

Hacker News 의견

• 지난 2주 동안 저녁 시간마다 claude code를 이용해 프로젝트를 한 번에 완성할 수 있는 "완벽한 프롬프트"를 만드느라 엄청 집중했음. 결국엔 CLAUDE.md 하나에 프로젝트 아키텍처, 모델 명세, 빌드 순서, 테스트 계층, 시나리오 등 8개의 다른 마크다운 파일을 참조하도록 구조를 짰음. 이 프로젝트는 Databricks Unity Catalog의 모델 기반 거버넌스 용인데, 관련 경험은 많지만 기존 툴이 충분히 유연하다고 느끼지 못함. 최종적으로 Databricks 전문가, Pydantic 전문가, 프롬프트 전문가 등 3개의 서브 에이전트로 실제 기획 파일 작업을 지원받음. 이 덕분에 마크다운 파일 품질이 예전 Pydantic 버전 문제부터 Unity Catalog에 대한 내 오해까지 여러 부분에서 크게 개선됨. 어제는 실제로 실행해 봤는데, 내가 몇 번 도구 사용을 승인해준 것 빼고 2시간 만에 대부분의 도구와 테스트가 완성됨. 이 방식이 예전과 너무 달라서 신기했는데, 기술적인 문서 작성을 꼼꼼히 하고 모두가 한 방향을 바라보게 하는 데 진짜 미래가 있다고 느낌. 코드를 직접 파는 것보다 생산성이 낫다고도 생각함. 다만 코드 작업 땐 몰입도가 높았지만, 여러 마크다운 문서를 다루면 집중력이 더 쉽게 흐트러지는 단점이 있음. 정말 흥미로운 시대임

  • Test-Driven Development처럼 시스템을 미리 설계하게 만드는 패턴이 새롭게 부상하는 게 느껴짐. 예전에는 코드를 만들면서 시스템을 점진적으로 그려 나갔다면, 이번처럼 AI 기반 개발은 영역을 앞서 설계하고 맵핑하게 해서 실제 코드는 단순히 설계를 실현하는 보일러플레이트 작업처럼 됨. AI는 이런 보일러플레이트에 정말 강함

  • 나도 똑같이 더 생산적인데 집중력은 더 흩어지는 현상이 고민임. 뭔가 이상하지만 당장엔 효과적임. 장기적으론 해법을 찾아야 할 듯. 지금 가장 잘 맞는 방법은 여러 에이전트를 프로젝트의 여러 리포지토리에서 각각 다른 태스크를 하게 하면서 계속 승인 작업을 하는 것임. 일종의 대규모 팀을 이끄는 프로젝트 매니저 느낌임. 역시나 흥미로운 시대임

  • 정말 신선한 방식임. 실제 실험에서 에이전트가 돌아가는 프레임워크가 뭔지 궁금함

  • 요즘 나도 제품 디테일, 사용자 여정 등을 음성으로 기록하고, 그걸로 기술 문서화 프로세스를 시작함. 최소한의 CLAUDE.md, 소프트웨어 개발은 Github 워크플로 활용, 근데 좋은 CI 워크플로 만드는 게 힘듦. 내 플레이북은 https://nocodo.com/playbook/임

• “계획 먼저 세우면 결과가 좋아진다”는 주장에 와닿지 않음. 난 예전부터 큰 기능이나 프로젝트는 당연히 머릿속에서든, 종이든, Confluence든, 화이트보드든 미리 구조와 이유, 방법을 생각했음. 소프트웨어 엔지니어링의 80%는 ‘뭘, 왜, 어떻게’ 할지 고민·확정하는 과정임. 이해관계자와 아이디어·목적을 확인하고, 리서치도 함. 마지막 20%만이 실제 코딩임. 예전부터 그래왔고, 제대로 된 기획이나 목표 정의에 AI가 꼭 필요한지 모르겠음

  • 큰 팀이나 문화가 자리잡은 환경에서는 그럴 수 있지만, 상당수 개발은 개인 프로젝트, 소규모 팀, 사이드 프로젝트, 빠른 POC, 일회성 자동화 툴 등에 집중됨. 이런 작업은 처음부터 문서/명세/테스트로 시작하지 않고, 코드와 고민·구현 과정을 섞어가며 진행함. TDD가 적합한 곳도 있지만 굳이 필요 없는 경우도 많음. 그런데 AI 코딩 에이전트 도입 뒤로는, 아이디어를 명확히 정의하고 명세로 정리하는 과정이 훨씬 중요해짐. 내 머릿속에서 떠오르는 모든 걸 말로 풀어내는 게 그만큼 필수임. 요즘 가장 핫한 프로그래밍 언어는 영어임

  • 난 개발과 설계를 혼합해서 진행하는 편임. 일단 코딩을 시작해서 계속 다듬고 발전시키는 식임. 대부분의 경우엔 대략적인 해결 방법이 뻔해서 시간 들여 깊게 계획할 필요 없다고 느낌

• 예전엔 프롬프트 엔지니어링이 농담거리였는데, 이제는 진짜 체감 중임. 클라우드 코드를 체계적으로 활용하려고 10~20분씩 꼼꼼한 프롬프트와 초기 기획에 매달릴 때도 있음. 나도 OP와 비슷하게 플랜을 파일로 저장하고, 새 컨텍스트에서 실행함. 정말 바라는 건 좋은 CLI임(현재 charm, cc 사용 중). 각각 구현, 플랜, 서브에이전트별 모델을 따로 쓸 수 있으면 최고일 듯. 로컬 모델로 구현하고 클라우드 모델로 플랜 짜거나 필요 시 스와핑해서 돈 아끼는 구조. Charm이 지금까지 써본 것 중에 컨텍스트 손실 없이 왔다갔다할 수 있게 잘 되어 있음. 병렬 서브에이전트 기능도 claudecode의 최고의 기능 중 하나임. (CCR은 시도해봤지만 기본 모델 이상 안 돼서 실망했음)

  • 프롬프트 엔지니어링이 지금 이슈가 된 건, 트위터 핫테이크나 콘텐츠 생산용 이슈 때문임. 하지만 실제로 프롬프트 엔지니어링은 옛날부터 중요했음. GIGO(“Garbage In, Garbage Out”, 쓰레기를 넣으면 결과도 쓰레기)는 모든 머신러닝 프로젝트에서 진리임. 그래서 동료나 친구들한테 “직접 써봐야 된다”고 계속 추천함. 6개월 전엔 안 되던 게 지금은 될 수도 있음. 실제로 손에 익혀야 뭐가 바뀌었는지, 뭐가 되는지 알 수 있음. 나는 네거티브 대신 실제 성공 사례나 블로그, gist, 예시들이 훨씬 더 가치 있다고 생각함. 아주 단순한 계산이나 오타 찾기가 아니라, 내 워크플로를 개선하고 도와줄 수 있어야 필요함. 프롬프트 엔지니어링은 10~15년 전 구글 실력 몰입해서, 계속 새로 나온 변화와 효과적인 패턴을 익히는 것과 같음

  • AI와 협업하려면 프롬프트 엔지니어링이 진짜 핵심임

  • AI를 쓰는 프로젝트가 내가 가장 문서화·테스트가 잘 된 프로젝트였음. LLM에게 성능을 끌어내려면 반드시 컨텍스트가 필요하니 문서화가 잘 되고, 테스트 생산 비용이 낮아졌으니 테스트가 더 많아짐. 오히려 코드 품질이 떨어진다는 예측과 달리, 더 좋아질 것임

  • 솔직히 "프롬프트 엔지니어링"이란 용어는 새로운 미디어를 이용한 아키텍처 설계임. 과거에는 "다이어그램 설계"라는 스킬이 각광받았듯, 지금은 새로운 방식의 아키텍처링임

• 최근 Claude Code를 잠깐 써봤는데, 추천받은 워크플로 해볼 예정임. 꽤 괜찮은 방식 같음. 그런데 CC 이용료가 생각보다 비쌈. 간단한 리팩토링에 5분 작업+15분 리뷰만 했는데 4달러나 들었음. 내가 직접 했다면 15~20분이면 끝났을 일임. 보통 기능 하나에 CC로 얼마 정도 쓰는지 궁금함. 아무도 가격 얘기를 안 함

  • 구독하면 $20~$200 플랫 차지로 일·주간 토큰 사용량 제한이 있음. https://support.anthropic.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan

  • AI 투자자들이 바라는 방향성은 노동 시장을 15% 마진으로 AI가 대체하는 구조임. 1:1로 개발자와 AI 예산이 같은 시대가 올 것임. 예를 들어 연봉 10만 불 짜리 시니어 개발자 한 명 몫이 10만 불 AI 예산으로 대체됨. AI 예산이 개발비에서 빠져나갈 것이고, 시니어 연봉은 내려갈 가능성이 높으며 개발팀 규모가 급격히 줄어들 수 있음. 지금은 VC가 전액 보조하는 '영토 확보' 단계인데, 트위터 VC 분위기 보면 이 단계가 곧 끝나갈 것 같음. 9개월 운영비에 5억 불을 몇 번이고 더 끌어오는 것도 한계에 다다름

  • Cursor에서 Claude Code로 일부 옮긴 이후로 비용이 많이 늘었음. 회사에서 주로 써서 상사 설득은 쉬웠지만, 사이드 프로젝트에서는 고민임. 재미 삼아 앱 부트스트랩할 때마다 20달러 내고 싶지는 않음

  • Sonnet(20유로/월), Opus(100유로/월) 두 모델을 선택해서 구독할 수 있음. 난 Sonnet 썼다가 나중에 Opus로 바꿈. Sonnet도 충분히 쓸만함. 토큰 한도 내에서는 내 용도로는 부족하지 않게 사용 중임. 다만 앞으로는 어떨지 확신 못함

  • "내가 직접 했어도 15~20분이면 됨"이라고 했는데, 그 15~20분을 다른 작업에 쓸 수 있지 않을까 생각해봄

• Visual Studio Code/ChatGPT5 프리뷰 조합을 사용하는 방식이 내 워크플로와 비슷함{아마 Github Copilot 구독으로 결제 중이지만 요즘은 확신이 없음}. 비에이전트 LLM은 코드가 빨리 망가지는 경향이 심하다고 느낌. 에이전트 모드를 쓰면서 코드 구축이 확 달라짐. 난 파이썬 개발자는 아니지만, LLM이 새 코드 더미를 짜주는 걸 보고 실제로 꽤 인상 받았음. 완성한 뒤엔 BitGrid에서 작은 LLM을 돌리고, 뒤늦게 코드를 완전히 이해하는 식으로 가려고 함. 작은 탐색 단계를 반복하고, 전체 설계를 내가 원하는 대로 유지하기 위해 일부 수정만 하는 구조임. LLM이 프로그래밍 파트너가 될 미래에 확신을 갖게 됨. Visual Studio Code/ChatGPT5 조합 쓰는 다른 사람도 있는지 궁금함

• AI 도구를 최적화하려다 보니, 개발자들이 '좋은 커뮤니케이션'과 '기대치 설정'의 가치를 재발견하는 것 같아서 흥미로움. 지금까지의 10x 개발자 이미지, 즉 이방인 혹은 괴짜 스타일은 재고할 때임

• Replit에서 비슷한 경험을 갖고 있음. 앱 크기가 커지면 설계 문서가 태스크와 진실의 소스가 되지 않으면 금방 무너짐. OpenAI는 챗이 느려지고 금방 먹통이 돼서, 문서를 따로 만들어 새 챗에 임포트하는 게 도움이 됨. 인간 차원에서도 우리 스스로도 그래야 한다고 느꼈음. 스스로 회고하며 문서화하고 ‘메모리’를 디자인 문서에 기록함으로써, 우리와 LLM 모두 자유로워질 수 있음

• 나도 최근 이 워크플로를 발견하고 매우 놀랐음. 중요한 건 claude에 최소한의 요구만 제공하고, 플랜 모드를 자유롭게 돌게 하는 것임. 만약 세일즈 지표 리포트라면 "Ultrathink relevant sales metrics"라고만 해도 다양한 지표를 알려주고, 순위를 매겨 추려볼 수 있게 함. 새로운 기능마다 디렉토리를 따로 만들고, 그 기능의 플랜을 파일로 작성하게 함. 이후엔 구현 계획, 필요한 데이터 쿼리, 실제 구현, 테스트, 유저 문서 작성까지 단계별로 시키고, QA로 보냄. 예전에는 세일즈 예측 기능 하나 만드는데 대규모 팀과 시간이 필요했는데, claude가 한나절에 도커 컨테이너로 구현함. 이 변화로 소프트웨어에 대한 내 관점이 바뀌는 중임. 예전엔 NDA, IP 등으로 회사들이 소스코드를 외부에 절대 내놓지 않았음. 그런데 이젠 20년 걸린 복잡한 ERP 시스템도 claude가 빠르게 재구현하고 문서, 테스트까지 첨부함. 현실적으로는 막 완벽하진 않지만, 진도가 정말 빠름

• Claude Code에서 좋은 피처를 뽑으려면 플랜을 먼저 제대로 작성하는 게 핵심임. 나는 최근 Cursor에서 GPT-5 High를 써서 플랜을 짜고, 그걸 Claude Code에 넣어 구현함. 코드베이스에서 바꿀 부분들을 미리 문서화하게 하면 추가로 15~20% 더 좋은 결과를 얻을 수 있음. 플랜 모델이 작동 방식, 아키텍처, 패턴을 문서화하고, 기능 설계까지 여기에 녹이면 결과물이 더 나음. 마지막으로, 반드시 문서와 플랜을 직접 리뷰·수정하는 것도 매우 큰 도움이 됨

  • 회사에서는 Google Workspace를 써서 Gemini가 “학술 스타일” 글쓰기에 아주 강력하지만, CC에 비해 코드 작성에는 약함. 그래서 Gemini에게 플랜을 충분히 구체적으로 정리하게 하고, 이걸 CC로 넘겨 내 코드베이스에서 수정·구현하게 함. 이 방식으로 새로운 기능 개발이나 기존 기능 확장에 놀랄만한 효과를 봄. 8주 만에 직접 만든 프로덕트가 현재 실제 프로덕션에서 고객 데모까지 진행 중임. CC의 경험과 결과물에 매우 흡족함. 예전에 HN에서도 밝혔듯, 우리 팀 내 인력으로도 상당 부분 할 수 있었지만 프론트엔드 작업은 엄두조차 못 냈음. 1년도 넘게 걸렸을 일, 더 많은 엔지니어와 데이터 사이언티스트의 노력이 필요했던 일이 대부분 2달 만에 완성됨. 기능 추가가 시간이 아니라 거의 ‘몇 초’ 만에 가능함. CC 덕분에 나는 내 경험이 여러 사람과 공유되고 있어 흥미로움

• 이런 프로세스에 프론트엔드 디자인을 우아하게 끼워넣는 좋은 방법을 발견한 사람이 있는지 궁금함. 대부분은 프론트엔드 프레임워크 언급, 혹은 figma 이미지 수준에 그침. 그걸로는 통합적 디자인 솔루션이라는 느낌이 안 듦