AI가 생성한 코드를 이해하지 못한 채 프로젝트에 쌓아가고 있다면? ‘이해 부채’라는 새로운 개념이 우리가 느끼던 불안을 명확히 짚어줍니다. 그리고 GitHub이 제안하는 ‘스펙 중심 개발’ 방식이 이 문제의 실질적 해결책이 될 수 있습니다.
코드는 빠르게 늘어나는데, 이해는 못한다?
GitHub Copilot, Claude Code, Cursor… 요즘 이런 AI 코딩 도구 안 쓰는 개발자가 오히려 드물죠. “앱 A를 만들어줘, 기능 Y를 추가해줘” 하면 순식간에 코드가 쏟아집니다. 생산성이 확 올라간 건 사실이에요.
그런데 문제는 여기서 시작됩니다. 시간이 지나면 AI가 만든 코드를 수정하거나 버그를 고쳐야 하는 순간이 옵니다. 그때 깨닫죠. “이 코드가 정확히 뭘 하는 거지?”
레거시 시스템을 다뤄본 분이라면 익숙한 느낌일 겁니다. 다른 사람이 10년 전에 짠 코드를 보며 머리를 싸맨 경험 말이죠. 코드를 안전하게 바꾸려면 먼저 이해해야 하는데, 그게 쉽지 않다는 거.
차이가 있다면 규모와 속도입니다. AI는 초당 수백 줄의 코드를 쏟아냅니다. 그리고 아무도 그 코드를 제대로 읽지 않아요. 품질을 중시하는 팀이라면 코드 리뷰를 거치겠지만, 그러다 보면 AI로 아낀 시간이 다 사라집니다. 더 심각한 건, 많은 팀이 아예 읽지도 않고 커밋한다는 거예요.
이걸 ‘Comprehension Debt(이해 부채)’라고 부릅니다. 코드를 이해하는 것보다 빠르게 생성하면, 나중에 갚아야 할 빚이 쌓이는 거죠.
70%는 AI가 고쳐주지만, 나머지 30%는?
“그래도 AI한테 다시 물어보면 되지 않나요?” 맞습니다, 대부분은 그렇게 해결됩니다. 아마 70% 정도는요.
하지만 LLM 도구를 많이 써본 사람이라면 압니다. ‘Doom Loop’라는 게 있다는 걸요. AI한테 똑같은 문제를 여러 번 물어봐도, 다른 AI 도구를 다 돌려봐도 해결이 안 되는 순간. 결국 코드를 직접 고쳐야 하는데, 그 코드를 이해하는 데만 엄청난 시간이 걸립니다. 이게 바로 ‘이해 부채’를 갚는 순간이에요.
마크다운으로 프로그래밍하기
그렇다면 해결책은 뭘까요? GitHub이 제안하는 ‘스펙 중심 개발(Spec-driven Development)’이 흥미로운 답을 제시합니다.
핵심은 이겁니다: 마크다운 파일에 프로그램의 ‘명세(specification)’를 작성하고, AI가 그걸 실제 코드로 ‘컴파일’하게 하는 거예요.
실제 사례를 볼까요? GitHub의 한 개발자는 ‘GitHub Brain MCP Server’라는 프로젝트를 이 방식으로 만들었습니다. Go 코드를 직접 건드리는 일이 거의 없었대요. 대신 main.md라는 마크다운 파일에 이렇게 적습니다:
## CLI
Usage 섹션의 내용대로 CLI를 구현하세요.
정확한 인자와 변수명을 따르세요.
pull과 mcp 명령만 지원합니다.
## pull
- CLI 인자와 환경 변수를 Config 구조체로 변환:
- Organization: 조직명 (필수)
- GithubToken: GitHub API 토큰 (필수)
- DBDir: SQLite 데이터베이스 경로 (기본값: ./db)영어와 마크다운으로 코드를 짜는 거죠. 변수, 반복문, 조건문 다 들어갑니다. 그리고 compile.prompt.md라는 파일에 이렇게 적어요:
- main.md의 명세에 따라 앱을 업데이트하세요
- VS Code 작업으로 코드를 빌드하세요
- 사용된 라이브러리의 GitHub 홈페이지에서 문서와 예제를 가져오세요이제 AI에게 이 프롬프트를 실행하라고 하면, main.md를 읽고 main.go를 자동으로 생성합니다. 개발자는 주로 명세만 수정하고, 실제 Go 코드는 거의 안 봅니다.
실제로 어떻게 쓰나요?
워크플로우는 간단합니다:
README.md나main.md에서 명세를 수정- AI에게 Go 코드로 컴파일하라고 요청
- 앱을 실행하고 테스트
- 뭔가 이상하면 명세를 다시 수정
- 반복
프로젝트가 커지면 Linear나 Jira 같은 도구와 연결할 수도 있어요. AI가 명세를 읽고 스토리를 자동으로 만들고, PR까지 연결해줍니다.
한 개발자는 iOS 리마인더 앱을 이 방식으로 만들어봤습니다. 먼저 Claude Code에게 아이디어를 제시하고, 프로젝트 명세를 만들게 했어요. 그 명세를 Epic → Feature → Story → Task로 쪼갰습니다. 그리고 “스토리 1.1.1을 작업해줘”라고 하면 AI가 그 부분만 딱 만들어주는 거죠.
현장에서 배운 교훈
실제로 써본 사람들이 공통적으로 하는 얘기가 있습니다.
작게 쪼개라. AI에게 한꺼번에 큰 작업을 시키면 엉망이 됩니다. 작은 PR 단위로 나눠서 작업하고, Git 히스토리로 변경사항을 추적하세요.
컨텍스트가 핵심이다. AI에게 충분한 맥락을 주지 않으면 엉뚱한 방향으로 달려갑니다. 명세 파일이 이 역할을 해주는 거예요.
AI는 도구지, 대체자가 아니다. 모든 걸 AI에게 맡기지 마세요. 중요한 결정은 여전히 개발자가 해야 합니다. AI는 협력자예요.
claude.md 같은 파일을 활용하라. 프로젝트 맥락과 개발 프로세스를 적어두면, 새 세션을 시작할 때마다 AI가 자동으로 읽어서 맥락을 파악합니다.
당신의 프로젝트에도 적용해보세요
이해 부채는 이미 많은 프로젝트에 쌓이고 있습니다. 지금 당장은 괜찮아 보여도, 나중에 그 빚을 갚아야 할 때가 옵니다.
스펙 중심 개발이 완벽한 해결책은 아닙니다. 초반에 명세를 작성하는 수고가 필요하고, 습관을 바꿔야 해요. 하지만 소프트웨어 개발의 많은 것들이 그렇듯, 초반 투자가 나중에 엄청난 시간을 절약해줍니다.
결국 핵심은 이거예요: AI가 코드를 빠르게 만들어주는 건 좋지만, 그 코드를 이해하고 관리하는 건 여전히 우리 몫입니다. 그리고 스펙 중심 개발은 그 일을 훨씬 쉽게 만들어줍니다.
작은 프로젝트부터 시작해보세요. README.md에 명세를 적고, AI에게 그대로 구현하라고 해보세요. 익숙해지면 점점 큰 프로젝트에도 적용할 수 있을 겁니다.
참고자료
Comments