저는 지난 몇 달 동안 Cursor와 Claude Code를 사용해 왔는데, 6주 차쯤 되었을 때 이상한 점을 발견했습니다. 도구들은 더 빨라지고 모델들은 더 똑똑해졌지만, 제 결과물은 그만큼의 속도로 개선되지 않았습니다. 저는 "이 인증 흐름(auth flow)을 리팩터링해줘"와 같이 모호한 프롬프트(prompt)를 입력했고, 그 결과 그럴듯하지만 형태가 뒤틀린 결과물을 받았습니다. 그러고 나서 에이전트(agent)와 20분 동안 논쟁하며 시간을 보냈죠. 병목 현상(bottleneck)은 AI가 아니었습니다. 그것은 제가 AI에게 주고 있던 입력값이었습니다.

그래서 저는 약간 무모한 시도를 해보았습니다. Cursor를 열기 전에 실제 문서(documentation)를 작성하기 시작한 것입니다. 사람 검토자를 위한 사양서(specs)가 아니라, Mermaid 다이어그램, 테이블 레이아웃, 엔드포인트 계약(endpoint contracts) 등 평소라면 아무도 읽지 않는 README에나 들어갈 법한 것들을 작성했습니다. 과하다는 생각이 들면 그만두겠다고 스스로 다짐했습니다. 몇 주가 지나자, 제가 생성한 AI 코드와 기존 브랜치에 있는 사람이 작성한 코드 사이의 차이(diff)가 눈에 띄게 줄어들었습니다. 솔직히 통제된 테스트를 통해 제대로 측정해 본 것은 아니니 참고만 하시길 바랍니다. 하지만 이 추세는 부정하기 어렵습니다.

저에게 효과가 있었던 비결은 문서 자체를 프롬프트(prompt)로 취급하는 것이었습니다. 거친 ER 다이어그램과 세 가지 API 형태를 Cursor의 컴포저(composer)에 쏟아 넣으면, 단순히 단어에 맞춰 패턴 매칭(pattern-match)을 하는 것이 아니라 파일 전체에 걸쳐 관계를 염두에 두는 것처럼 보입니다. 반대로 그냥 채팅만 할 때는 정반대의 상황이 발생합니다. Cursor는 멋진 모델을 기쁘게 작성한 뒤, 이전 턴에서 언급했던 컬럼(column)을 잊어버려 결국 아무것도 가리키지 않는 외래 키(foreign key)를 만들어냅니다. 강력한 추론 능력을 갖췄다는 Claude Code도 마찬가지입니다. 컨텍스트 윈도우(context window)에 없는 것에 대해서는 추론할 수 없기 때문입니다. 먼저 문서화하는 것이 만능 해결책(silver bullet)은 아닙니다. 오히려 주의력을 어디에 집중할지를 옮기는 것에 가깝습니다. 작은 Next.js 사이드 프로젝트를 운영하는 1인 개발자로서, 정확히 측정해 보지는 않았지만 아마 일주일에 몇 시간 정도는 아낀 것 같습니다.

이미 Cursor나 Claude Code를 유료로 사용 중인데 도구의 효용성이 떨어졌다고 느껴진다면 시도해 볼 만한 가치가 있습니다. 제가 아직 파악하지 못한 또 다른 점은 언제 이 방식을 사용하지 말아야 하는가 하는 것입니다. 작은 버그 수정이나 단일 파일 수정은 여전히 대충 작성한 프롬프트(prompt)를 사용하는 것이 더 빠르게 느껴집니다. 어쨌든, 먼저 문서를 작성한 다음 모델이 그것을 씹어 삼키게(chew on it) 하세요. 당신을 10배 더 빠르게 만들어주지는 않겠지만, AI가 생성한 코드가 마치 동전 던지기처럼 느껴지는 상황은 멈추게 해줄 것입니다.