Claude Code 첫 실험: 적절한 문서화가 어떻게 2일간의 고군분투를 1시간의 빌드로 바꾸었나

실험으로서, 저는 Claude Code가 저를 위해 렌즈 모양 변환 도구(lens shape converter tool)를 빌드하도록 시도하며 이틀을 보냈습니다. 진행은 느렸고, Claude는 데모 데이터가 있음에도 불구하고 계속해서 추측을 반복했습니다. 출력값은 오류가 있었고 지속적인 수정이 필요했으며, 제가 예전에 작성했던 도구의 기존 코드베이스(codebase)를 읽게 한 후에도 부분적인 결과만을 얻었습니다. 하루가 지난 후, 저는 제 실수를 깨닫고 제가 두 달 동안 정성 들여 만든 도구—처음에는 PHP에서 TypeScript로 포팅하고 세밀하게 확장했던 도구—를 염두에 두고 처음부터 다시 시작했습니다.

이번에는 코드 한 줄을 쓰기 전에 약 2시간 동안 준비 작업을 했습니다. 참조용 SVG의 모든 부분과 그룹에 라벨을 붙였고, 각 요소의 기능과 관계를 설명하는 문서(documentation)를 작성했습니다. 그런 다음 Claude가 코드를 건드리기 전에 따라야 할 명시적인 단계별 프로세스가 포함된 상세한 프롬프트(prompt)를 구성했습니다.

Claude는 제 코드베이스를 읽고, 프로세스를 따랐으며, 단 한 번에 도구를 빌드했습니다. 제대로 작동했습니다. 진정한 깨달음의 순간이었습니다.

총 소요 시간: 5시간. 준비 2시간, 빌드 1시간, 나머지는 수동 검증, 실제 제품에 대한 스테이징 테스트(staging tests), 두 번째 기능 추가 및 새 구조로 제품 업데이트에 나누어 사용했습니다.

고군분투의 원인은 가이드와 설명의 부족이었습니다. 프레임 기하학(frame geometry), 좌표 로직(coordinate logic), 보정 특이사항(calibration quirks) 등 모든 것이 제 머릿속과 코드베이스에만 존재했습니다. 문서화를 통해 이를 명시적으로 만들고, Claude에게 라벨이 붙은 참조 파일, 데모 데이터, 그리고 기존 코드와 함께 계획을 제공하자, Claude는 추측을 멈추고 조립을 시작했습니다.

기반이 되는 툴체인(toolchain)을 구축하는 데 보낸 몇 주가 필수적인 첫 단계였습니다. 문서화와 계획이 깔끔한 실행을 가능하게 했습니다.
submitted by /u/Heruboy
[link] [comments]