Markdown in /src

(htmx.org)

Hacker News2026년 9월 22일개발자 도구

AI 에이전트 코딩 시대에 마크다운은 단순한 문서를 넘어 코드의 의도와 설계를 담은 핵심 소스 코드로 진화하고 있으며, 이를 /src 디렉토리에 포함시켜 코드와 설계의 일치성을 확보하는 것이 소프트웨어 개발의 새로운 표준이 될 것입니다.

이 글의 핵심 포인트

1마크다운은 이제 단순한 문서가 아닌 소스 코드의 역할을 수행하고 있음
2LLM 기반 에이전트 코딩 환경에서 휘발성 프롬프트는 설계 의도를 유실시킬 위험이 있음
3마크다운 파일을 /src/md와 같이 소스 디렉토리 내에 포함시켜 코드와 설계의 로컬리티를 확보해야 함
4마크다운은 인간과 AI 에이전트 모두가 읽고 편집할 수 있는 텍스트 기반의 효율적인 매개체임
5기존의 고수준 기획서(Jira, Notion 등)와 별개로, 구현에 직결된 저수준 설계 결정사항을 마크다운으로 관리해야 함

이 글에 대한 공공지능 분석

왜 중요한가?

AI 에이전트가 코드를 생성하는 비중이 늘어날수록, 생성된 코드 자체보다 그 코드가 왜 그렇게 작성되었는지에 대한 '의도'를 관리하는 것이 소프트웨어 유지보수의 핵심이 되기 때문입니다.

어떤 배경과 맥락이 있나?

최근 개발 환경은 LLM이 고수준 명세를 저수준 코드로 변환하는 컴파일러와 유사한 역할을 수행하는 '에이전트 코딩' 시대로 빠르게 전환되고 있습니다.

업계에 어떤 영향을 주나?

개발 프로세스가 '코드 작성'에서 '명세(Markdown) 관리'로 이동하며, 문서와 코드 사이의 맥락 단절을 해결하는 로컬리티(Locality) 중심의 워크플로우가 표준이 될 것입니다.

한국 시장에 어떤 시사점이 있나?

빠른 실행력을 중시하는 한국 스타트업은 문서화 비용을 줄이면서도 AI 에이전트를 활용해 설계 품질을 유지할 수 있는 이 새로운 워크플로우를 선제적으로 도입하여 개발 생산성을 극대화할 필요가 있습니다.

이 글에 대한 큐레이터 의견

에이전트 코딩의 확산은 개발자의 역할을 '구현자'에서 '설계자 및 검증자'로 재정의하고 있습니다. 마크다운을 소스 코드의 일부로 편입시키는 제안은 코드와 문서 사이의 맥락 단절을 해결할 수 있는 매우 실용적인 접근입니다. 이는 특히 AI 에이전트가 프로젝트의 맥락을 즉각적으로 파악하게 함으로써, 새로운 팀원이 합류하거나 프로젝트가 확장될 때 발생하는 온보딩 비용을 획기적으로 낮출 수 있는 기회입니다.

하지만, 모든 설계 의도를 마크다운으로 관리할 때 발생할 수 있는 '문서의 비대화'와 '관리 부채'라는 리스크를 간과해서는 안 됩니다. 마크다운이 너무 상세해지면 오히려 코드 수정 시마다 문서를 업데이트해야 하는 번거로움이 발생하여, 결국 코드와 문서가 다시 불일치하게 되는 상황이 올 수 있습니다. 따라서 창업자들은 AI 에이전트가 읽기 적합한 수준의 '핵심적인 의도'만을 마크다운에 담고, 이를 자동화된 테스트나 코드 생성 파이프라인과 연결하는 정교한 프로세스를 구축하는 데 집중해야 합니다.

원문 보기 →