/src에 있는 Markdown – Markdown를 소스 코드처럼 취급하기

TL;DR

• Markdown은 문서화에서 소스 코드로 전환되고 있습니다.
• 코드와 함께 /src/md 폴더에 Markdown을 저장하세요.
• 일시적인 프롬프트 세션에 의존하는 대신, 그 Markdown에서 코드와 테스트를 유도하세요.

왜 Markdown을 소스 코드처럼 취급해야 하는가

Markdown은 전통적인 소스 파일의 핵심 특성을 충족합니다: 순수 텍스트이며, diff 가능하고, 검색 가능하며, 풀 리퀘스트에서 쉽게 검토할 수 있습니다. 대규모 언어 모델(LLM)은 Markdown을 자연스럽게 읽고 쓸 수 있으며, 인간은 전용 도구 없이도 편집할 수 있습니다. 따라서 Markdown은 컴파일러의 고수준 사양이 기계 코드를 이끄는 것처럼, 코드 생성을 이끄는 의도 계층으로 작용할 수 있습니다.

일시적 프롬프팅의 문제점

현재의 에이전트 워크플로우는 종종 임시적인 프롬프트 시리즈를 통해 코드를 생성합니다. 결과적으로 생성된 코드가 사실상의 참조 기준이 되지만, 프롬프트 자체는 Slack, Linear, 또는 개인 노트에 흩어져 있습니다. 이러한 "프롬프트 부패"는 다음과 같은 문제를 야기합니다:

• 미래의 개발자와 에이전트에게 맥락 상실.
• 원본 사양을 버전 관리할 수 없는 상태.
• 에이전트가 누락된 의도를 재구성해야 할 때 토큰 사용량 증가.

/src/md 디렉터리의 장점

의도의 근접성

코드를 설명하는 Markdown을 코드 옆에 두면 "사양의 거리감" 문제를 해결할 수 있습니다. 개발자는 소스 트리 밖으로 나가지 않고도 모듈의 논리를 확인할 수 있으며, 에이전트도 추가 조회 없이 동일한 맥락을 가져올 수 있습니다.

인간-에이전트 대칭성

인간과 LLM 모두 동일한 Markdown 파일을 소비할 수 있어, 의도, 아키텍처 결정, 데이터 모델에 대한 단일 참조 기준을 확보할 수 있습니다.

버전 관리 및 검토

Markdown 파일은 코드와 동일한 Git 워크플로우에 참여합니다: diff 가능하고, linting이 가능하며, 풀 리퀘스트 댓글에서 논의할 수 있습니다. 이를 통해 의도 변경 사항을 감사하고 검토할 수 있습니다.

Markdown이 테스트와 어떻게 보완되는가

테스트는 자동 정확성 검증에 필수적이지만, 저수준이며 종종 기능이 존재하는 이유를 숨깁니다. /src/md에 의도를 저장하고, 그 의도에서 테스트를 생성함으로써 명확한 업무 분담을 달성할 수 있습니다:

• Markdown – 행동, 아키텍처, 데이터에 대한 사양 같은 설명.
• 테스트 – 생성된 코드가 사양과 일치하는지를 구체적으로 검증하는 내용.

제안된 /src/md 레이아웃

구체적인 폴더 구조는 Markdown을 체계적으로 정리하고 탐색 가능하게 유지하는 데 도움이 됩니다:

src/
  md/
    README.md          # 에이전트와 인간을 위한 진입점
    TODO.md            # 모듈의 열린 작업 목록
    OVERVIEW.md        # 모듈의 기술적 개요
    features/
      FEATURE_1.md     # 기능별 설명
    data/
      DATAMODEL_1.md   # 데이터 모델 정의
    api/
      API_1.md         # API 계약 및 사용법
    infrastructure/
      INFRA_1.md       # 인프라 의존성

하위 폴더는 선택 사항이며, 기능, 데이터, API, 인프라 등 논리적 축을 따라 관심사를 분리할 수 있게 해줍니다.

커뮤니티 피드백 요약

• 프롬프트 부패 우려 – @aDyslecticCrow는 오래된 프롬프트를 저장하면 리포지토리가 혼잡해지고 토큰 사용량이 증가할 수 있다고 경고했습니다. 공감대는 Markdown을 최소화하고 최신 상태로 유지하며, 모든 프롬프트의 완전한 녹음이 아니라 의도로 취급해야 한다는 점입니다.
• 혼잡 vs 가치 – @benrutter는 과도한 Markdown이 리포지토리를 부풀리고 유지보수가 어려울 수 있다고 주장했습니다. 그는 주로 리뷰나 회귀 분석 시에만 Markdown을 사용하고, 모든 프롬프트를 영구적으로 저장하지 말 것을 제안했습니다.
• 도구 지원 – @xg15는 Markdown에 대한 구문 강조 및 탐색 기능에 대해 묻습니다. 기존 IDE 확장 기능은 이미 풍부한 Markdown 지원을 제공하며, Varar 또는 Cucumber 스타일의 린터 도구를 통해 일관성을 강제할 수 있습니다.
• 대체 배치 위치 – @ktpsns와 @maxk42는 문서를 /docs 또는 별도의 README 파일에 두는 것을 선호합니다. 핵심 차이는 근접성입니다: 코드 옆에 의도를 두는 것(즉, /src/md)은 구현과 논리 사이의 정신적 거리를 줄입니다.
• 문학적 프로그래밍의 영감 – @sroerick는 이 접근 방식을 느슨하게 컴파일되는 DSL이나 문학적 프로그래밍에 비유하며, "사양이 코드와 일치하는" 워크플로우의 필요성을 강조했습니다.
• 표준화 제안 – @divbzero는 중앙 인덱스 대신 각 하위 디렉터리에 README.md를 사용하는 것이 좋다고 제안하여 일반적인 리포지토리 관행과 일치시켰습니다.

실용적인 워크플로우

1. 새로운 기능, 데이터 모델, 또는 API를 설명하는 Markdown 파일을 /src/md에 생성하거나 업데이트합니다.
2. 해당 Markdown을 프롬프트로 사용하여 LLM을 실행하여 코드를 생성하거나 업데이트합니다.
3. 동일한 Markdown에서 테스트를 자동으로 생성합니다 (예: 커스텀 생성기 또는 mdtest 같은 도구 사용).
4. Markdown과 생성된 코드를 하나의 풀 리퀘스트에서 검토합니다.
5. 수동 수정 사항을 다시 Markdown에 반영하여 의도와 구현이 일치하도록 동기화합니다.

잠재적 함정과 대응책

• 오래된 Markdown – 최근 커밋에서 참조되지 않은 Markdown 파일을 경고하는 linting 단계를 설정하세요.
• 토큰 비용 – Markdown을 간결하게 유지하세요; 모든 프롬프트의 정확한 녹음이 아니라 고수준 사양으로 취급하세요.
• 비결정적 생성 – LLM 출력이 다를 수 있음을 받아들이세요; 정확한 생성 코드보다는 테스트를 통해 회귀를 포착하는 데 의존하세요.

결론

AI가 코드 생성을 저렴하게 만들면서 가장 가치 있는 자산은 그 코드 뒤에 있는 의도가 됩니다. /src/md 디렉터리에 그 의도를 Markdown으로 저장하면 근접성, 버전 관리, 그리고 인간과 에이전트 모두가 공유할 수 있는 매체를 제공합니다. 정확한 레이아웃은 변화할 수 있지만, 핵심 아이디어—Markdown을 보조 문서가 아닌 소스 코드처럼 취급하는 것—은 에이전트 기반 개발 워크플로우를 위한 현실적인 발전 방향을 제시합니다.