명세 기반 개발(Spec-driven development): Markdown의 부상

평범한 근무일마다 에디터를 열면 탭 대부분이 .md 파일입니다.

5년 전만 해도 이런 사실을 인정하는 것은 이상하게 들렸을 겁니다. 작업은 .java, .ts, .php 등에서 이루어졌습니다. Markdown은 README나 가끔 아무도 보지 않는 문서용이었죠. 하지만 이제는 Markdown이 결정이 내려지는 곳이고, 구현 파일은 제가 타이핑하기보다는 읽어보는 경우가 점점 많아졌습니다.

이러한 변화에는 이름이 있습니다. 명세 기반 개발(Spec-driven development)은 에이전트가 충분히 명확한 설명만으로도 작동하는 구현체를 만들어낼 수 있다는 관찰에서 시작됩니다. 이 경우, 그 '설명' 자체가 버전 관리하고, 검토하고, 논쟁할 가치가 있는 것이 됩니다. 당신은 명세를 작성합니다. 그리고 에이전트가 그것으로부터 구축합니다. 무언가 다른 것이 필요할 때, 출력물에 손으로 패치하는 대신 명세만 변경하여 재생성하면 되므로 두 가지가 분리되는 것을 막을 수 있습니다.

GitHub는 제가 감히 말하기 어려울 정도로 이 점을 직접적으로 보여줍니다. 그들의 관련 게시글 제목은 [

실제로 표준에 대한 싸움이 있었는데, 그 내용은 파일 이름에 관한 것이었습니다. AGENTS.md 대 CLAUDE.md 대 .cursorrules 그리고 나머지들이었습니다. 이 논쟁은 충분히 오래 지속되었고 중요했기 때문에, 이제 Linux Foundation 프로젝트가 최종 결과를 관리하고 있습니다.

확장자(extension)는 애초에 의제에 오르지 않았습니다. 전 세계의 모든 CI 시스템이 이미 파싱할 수 있는 YAML을 아무도 제안하지 않았고, 스키마와 검증기 및 편집기 지원을 갖추어 에이전트가 읽기도 전에 누락된 필드를 알려줄 수 있는 JSON도 아무도 제안하지 않았습니다. 또한 기계와 인간이 문서에 대해 합의해야 할 필요가 있을 때마다 이 산업이 해왔던, 작고 간결한 DSL(Domain Specific Language)을 구축한 사람도 없었습니다.

마크다운(Markdown)은 투표를 하기도 전에 승리했습니다.

이는 좋은 이유가 있었기 때문이며, 그 이유에 대해 정확하게 설명할 가치가 있습니다. 마크다운은 사람이 diff에서 편안하게 읽을 수 있고, 모델이 파서도, 스키마도, 의식적인 절차(ceremony)도 없이 네이티브로 읽을 수 있는 유일한 형식입니다. 여기에 표를 넣거나, 단락을 넣거나, 번호가 매겨진 목록을 넣거나, 아직 아무도 해결하지 못한 엣지 케이스에 대한 세 문장의 주저함을 넣을 수도 있습니다. 이러한 유연성이 바로 이것이 1년 반 만에 도구 체인(toolchain)의 모든 구석으로 퍼져나간 이유입니다.

이것은 또한 전체 문제입니다.

우리가 가져온 것

소스 코드에서 두 가지가 전달되었는데, 둘 다 좋습니다.

명세는 저장소에 존재합니다. 버전 관리가 되며, diff가 가능하고, 누가 무엇을 언제 변경했는지 볼 수 있습니다. 이것만으로도 명세 기반 개발(spec-driven development)은 제가 이전에 근무했던 모든 요구사항 프로세스보다 앞서 나갑니다.

그리고 명세는 검토됩니다. 풀 리퀘스트(pull requests)로 도착하고, 사람들이 이에 대해 댓글을 달며, 무언가를 구축하기 전에 잘못된 것은 논쟁할 수 있습니다. 논쟁을 더 일찍 진행하는 것이 이 움직임이 주장하는 가치의 대부분이며, 그 주장은 타당합니다.

여기서 상속이 멈춥니다.

우리가 남겨둔 것

소스 코드에 요구하는 다른 모든 것은 부재합니다.

타입이 없습니다. '성공 기준(Success Criteria)'이라는 섹션에 기준과 유사한 내용이 포함되어 있는지 아무것도 확인하지 않습니다. 비워두거나 의미 없는 문장으로 채워도 모든 다운스트림 도구는 문서를 받아들이고 진행합니다.

컴파일러가 없습니다. 에이전트가 스펙을 읽기 전에, 요구사항 4가 요구사항 9와 모순된다거나 수용 기준(acceptance criteria)이 기능적 요구사항(functional requirements)에서 언급하지 않은 동작을 설명한다고 알려주는 것은 아무것도 없습니다. .ts 파일에서는 명백한 모순이 빨간 밑줄로 표시됩니다. 하지만 .md 파일에서는 유효한 마크다운이며, 가장 먼저 알아차리는 것은 두 가지 중 하나를 자신 있게 구축하는 에이전트입니다.

테스트가 없습니다. 생태계가 만들어낸 가장 가까운 것이 lint-spec.prompt.md인데, 이는 모델에게 스펙을 읽고 명확성과 완전성을 기준으로 평가하도록 요청합니다. 이것은 비결정론적(non-deterministic) 검사이며, 문서를 소비할 시스템과 같은 종류의 시스템에 의해, 정의된 구조가 없는 입력으로 실행됩니다. 아무것도 없기보다는 낫지만 테스트는 아닙니다.

존재하는 도구들은 대부분 이 격차를 확인시켜 줄 뿐입니다. markdownlint는 스타일을 검사하는데, 이는 의미라기보다는 형식(formatting)에 관한 것입니다. OpenSpec은 validate 명령어를 제공하며, 이 도구들에 대한 2026년 비교는 이를 명확하게 설명합니다. 즉, 행동(behaviour)보다는 구조를 확인하므로, 스펙은 강제된 계약(enforced contract)이라기보다는 관습(convention)입니다. 같은 비교는 코드와 스펙 간의 검증이 대부분의 도구들이 선택 사항으로 취급하는 단계라고 언급합니다.

관습, 그리고 강제된 계약이 아닌 것. 이것이 전체 계층에 대한 공정한 설명이며, 이 계층에서 이제 결정이 이루어지고 있습니다.

명백한 반론

마크다운의 느슨함은 특징(feature)이며, 경직성 때문에 아무도 전에 스펙을 작성하지 않았습니다. 지난 40년간 요구사항을 기계로 검사 가능하게 만들려는 모든 시도는 너무 지루해서 팀들이 조용히 사용을 중단하게 만든 형식을 만들어냈고, 이것이 UML, 무거운 RUP 문서, 대부분의 IEEE 830의 실제 역사입니다.

그것은 사실이며 저는 그것을 포기할 수 없습니다.

더 엄격한 형식이라면 핵심을 놓칠 것입니다. 산문(prose)의 모든 부분을 유지하면서도, 에이전트가 문서를 읽고 필수 섹션이 비어 있거나, 두 가지 요구사항이 동시에 성립할 수 없거나, 승인 기준(acceptance criterion)이 파일의 다른 어떤 내용에서도 언급되지 않은 동작을 명명하는 경우를 미리 발견하지 못하게 하는 것은 가능합니다. 이 모든 것을 위해 영어 문장 하나를 포기할 필요는 없습니다.

엄격함은 형식 때문이라기보다는 더 지루한 이유 때문에 부족합니다. 저희가 가장 중요한 텍스트를 새로운 곳으로 옮긴 데는 약 18개월이 걸렸지만, 아직 아무것도 구축하지 못했습니다.

이해관계가 바뀐 이유

마크다운(markdown)이 README용이었을 때, 일관성 없는 문서는 혼란스러운 독자 한 명에게 비용을 청구하는 정도였습니다. 피해 범위는 사람 한 명과 10분 정도였습니다.

하지만 같은 문서가 이제는 그것을 문자 그대로 읽고, 당신이 남긴 모든 간극을 자체적인 판단으로 채우며, 몇 분 안에 수천 줄의 결과물을 내보내는 시스템의 입력값이 되었습니다. 두 가지 방식으로 해석될 수 있는 문장도 더 이상 누군가가 질문하기를 기다리지 않습니다. 모델이 가장 그럴듯하다고 판단한 읽기 방식에 의해 조용히 해결되며, 그 결과는 완성된 작업처럼 도착합니다.

저희는 일관성 없는 소스 코드를 커밋하는 것을 거부하는 도구를 만드는 데 40년을 보냈고, 이제 가장 중요한 결정들을 무엇이든 타이핑하면 유효한 형식으로 옮겼습니다.

파트 2에서는 부재(absence)가 허용하는 특정한 한 가지 것에 대해 다룰 것이며, 이는 보이는 것보다 더 큰 문제입니다. 바로 주류 명세 형식(mainstream spec format)의 모든 곳에 존재하는 간극이며, 이로 인해 그 작성자 외에는 아무도 결과를 검증할 수 없게 만듭니다.