htmx 카슨 그로스 제안: 마크다운이 문서가 아니라 소스코드다, /src/md에 커밋하자
- htmx 저자 카슨 그로스가 2026년 9월 21일 에세이에서 마크다운을 문서가 아닌 소스코드로 취급해
/src/md에 체크인하고, 코드와 테스트는 일회성 프롬프트가 아닌 이 마크다운에서 도출해야 한다고 주장함 - 그로스는 LLM 워크플로가 컴파일러와 달리 원본 명세를 남기지 않아, 일회성 프롬프트 세션에서 나온 생성 코드가 코드베이스의 사실상 유일한 진실 원천이 된다고 지적함
- Hartley Brody의 "Markdown is the new source code"를 인용해 앱 로직이 마크다운으로 정의되고 생성 코드는 저수준 구현 상세가 된다는 관점을 소개함
/src/md의 마크다운은 기존 설계 문서보다 낮은 수준으로 아키텍처 결정, 소스 레벨 결정, 저수준 데이터 설계 결정을 담으며 프로젝트 매니저가 관리하는 문서보다 스펙에 가깝게 동작함- 그로스는 위치성 원칙을 근거로 코드 옆에 의도를 두면 위키와 Jira에 흩어진 "먼 곳의 스펙"이 사라지고, Linear와 위키는 고수준 설계와 이슈 워크플로만 맡게 된다고 설명함
Hacker News opinions
나는 마크다운을 보통 /docs에 넣는데 파일명 대문자도 안 씀. 문서 생성기가 이 파일을 먹고 HTML/PDF 내비게이션을 만들게 하는 식인데, 그래도 텍스트를 코드 가까이 두는 방향에는 대체로 동의함. 저자가 말하려는 게 그거 같은데?
예전에 TempleOS 만질 때는 OS 전체 텍스트가 리치 텍스트여서 주석에 그림이랑 접히는 섹션도 넣었었음. 진지한 소스에는 플레인 텍스트가 좋지만 다이어그램을 ASCII 아트 대신 바로 그려 넣었던 건 좀 그리움.
저자가 진짜 주장하는 건 리포에 넣는 디자인 문서임. LLM이 설계 결정이나 아키텍처, 트레이드오프 정리하는 .md 문서를 만드는 건 진짜 잘하고 나중에 기여자한테도 쓸모가 있음.
문서를 VCS에 넣는 건 찬성인데 /src에 넣는 건 절대 안 됨.
아예 요점을 놓친 거임. md 문서가 바로 소스라는 주장인데?
개발자용 문서는 /src에 넣어도 되는데 그 외는 안 됨. 개발자는 플로우 끊으면서 문서 찾는 걸 진짜 못 참아서 바로 보이는 곳에 둬야 함.
개발자 문서는 src에 있어야 나중에 전체 그림이 보임. 문제는 동기화라서 에이전트 하니스가 강제로 검사하게 해야 함.
나는 여전히 소스코드 자체가 문서고 유닛 테스트가 문서라는 생각이 좋음. LLM이 짠 코드를 사람이 읹기 좋게 고치는 게 요즘은 말 많은 주제가 됐는데, 그래도 그럴 가치가 있다고 봄.
src/md가 docs랑 뭐가 그렇게 다르지? 패키지 여러 개로 쪼개면 문서를 코드에 붙이는 게 의미가 있겠지만, packages/foo/docs 이런 식이면 될 듯함.
나는 저거 비슷한 방식을 꽤 오래 썼는데 마크다운을 GitHub 이슈로 저장함. 상세 스펙을 만들 때(보통 채팅 세션)는 구현 전에 컨텍스트를 아예 클리어해서 모델이 AGENT.md 같은 알려진 컨텍스트만 보게 함. 에이전트가 예전 프롬프트 지시를 다시 찾아볼 수 있다는 게 큰 장점이더라.
- Spec-Kit이나 OpenSpec, BMAD를 수동으로 만든 거 아닌가? 2. 마크다운이 일반 텍스트나 다른 마크업이랑 뭐가 다르다는 거지? 3. LLM이 결정적이지 않다는 걸 모르는 것 같음.
md/영어가 새 소스코드라는 말임. 마크다운은 영어에 맞고 LLM이 잘 읽고 쓰니까 메모리와 지시에 쓰이는 거고, 결정적이진 않아도 설명이 충분한 스펙을 작업 시스템으로 옮길 정도는 됨. 핵심 흐름은 md로 추론하고 테스트로 검증하는 방식이라 완벽하진 않은데, 실제 트렌드라서 열린 마음으로 들을 필요가 있음.
내가 좋아하는 프로젝트들은 보통 주석 안에 문서가 있음. SpiderMonkey가 좋은 예라서 설계를 왜 그렇게 했는지까지 길게 풀어 쓰는 주석이 있음. 위치성이 목표라면 주석보다 가까운 곳이 없고, 에이전트용 마크다운이 자주 바뀔 거라면 AGENTS.md 하나에 묶어두는 게 나음.
부강의 할 때 항상 학생들한테 "왜"를 쓰는 주석을 쓰라고 말함. 코드는 스스로 설명해야 한다는 말을 다들 하는데, 왜 그렇게 했는지 적어주면 5년 뒤에 코드 받아든 사람이 헛소리라고 생각하며 삽질할 일이 확 줄어듦.
몇 달 전에 비슷한 글을 썼었는데 정작 내 충고를 잘 지키진 못하고 있음. 프로그램 소스에서 진짜 흥미로운 부분은 그 프로그램을 만들기까지 뭘 했는지고, AI가 만든 코드는 나한테 바이너리랑 같은 범주임.
이 방향이면 마크다운용 deep module 같은 거랑 문서 추상화 레이어 관리 방법론이 곧 나올 듯. 진심인데, 서로 뒤엉킨 마크다운 덩어리를 관리하는 건 점점 어려워짐.
문서는 이미 우선순위 밀려서 썩는 곳인데 더 크고 복잡하게 만드는 건 답이 아님. 중첩되는 마크다운이나 restructured-text, asciidoc이면 블록 재사용이나 접히는 섹션 같은 건 이미 충분함.
그 길로 가면 마크다운에도 문법 하이라이트랑 go to definition, 디버거까지 달아주자는 얘기? 그리고 LLM을 컴파일러로 보는 비유가 별로인데, 스펙이 바뀔 때마다 프로젝트를 통째로 재빌드해야 하는 사태가 남. 토큰 비용도 엄청나고 매번 다른 구현이 나옴. 차라리 코드가 진실 원천이고 LLM은 아주 정교한 편집 도구로 보는 게 낫고, 프롬프트는 체크인하되 구현 기록인 문서로 취급하는 게 맞음.