"프롬프트 그만 날리고 마크다운을 /src에 넣자" htmx 개발자의 일침

요약 htmx의 창시자이자 몬태나 주립대 교수인 카슨 그로스(Carson Gross)가 AI 에이전트 코딩 시대에 걸맞은 새로운 코드베이스 관리 방안으로 '마크다운을 /src 디렉터리에 포함하자'는 에세이를 발표해 개발자들 사이에서 화제가 되고 있습니다. 저자는 최근 현업 컨설팅을 진행하며 LLM 기반의 에이전트 코딩이 대세로 자리 잡는 흐름을 체감했다고 밝힙니다. 많은 이들이 LLM을 마치 고급 명세를 저수준 코드로 변환해주는 컴파일러처럼 여기지만, 기존 컴파일러와 달리 LLM 코딩 세션은 휘발성 프롬프트만 남기고 진짜 '소스 코드(원천 의도)'를 유실한다는 결정적 차이가 있다고 지적합니다. 결국 일회성 채팅 프롬프트로 생성된 코드만이 유일한 진실의 원천(ground truth)으로 남는 문제가 발생한다는 것입니다. 이에 대한 해법으로 저자는 마크다운(.md)이야말로 새로운 시대의 진짜 소스 코드라고 주장합니다. 마크다운은 일반 텍스트라 Git diff나 코드 리뷰가 가능하고, 인간과 LLM 에이전트 모두 쉽게 읽고 쓸 수 있는 완벽한 매개체이기 때문입니다. 현재도 AGENTS.md나 TASK.md 등으로 부분 활용되고 있지만, 저자는 한 걸음 더 나아가 `/src/md` 같은 경로를 만들어 소스 코드 바로 옆에 아키텍처 및 데이터 설계 의도를 담은 마크다운을 함께 체크인하자고 제안합니다. 이러한 방식은 노션이나 슬랙 등 외부 도구에 명세가 흩어지는 '원격 명세' 문제를 없애고, 코드와 명세의 근접성(locality)을 극대화해 사람과 AI 에이전트 모두에게 최고의 컨텍스트를 제공할 수 있다고 강조합니다. 아울러 복잡한 테스트 코드나 프롬프트 대신, 소스 폴더 내 마크다운 문서를 핵심 명세로 삼고 여기서 코드와 테스트를 파생시키는 구조가 AI 코딩 시대의 표준 워크플로가 되어야 한다고 덧붙였습니다.