SpecScore vs Plain Markdown
대부분의 팀은 이미 "스펙"을 가지고 있습니다 — docs 폴더의 임시 Markdown, Notion 페이지, 또는 Jira 티켓으로요. 무료이고, 이미 거기에 있으며, 작동합니다. SpecScore는 같은 Markdown에, AI 에이전트가 lint하고, 쿼리하고, 코드까지 추적할 수 있는 구조를 더한 것입니다.
공통점.
기본값이 잘하는 것.
Plain Markdown, Notion, Jira는 진짜 기본값입니다. 그럴 만한 자격이 있습니다.
학습 곡선 제로
스키마도, 필수 필드도, 흐름 속 CLI도 없습니다. 파일을 열고, 입력을 시작하세요. 일회성 노트나 아주 작은 프로젝트라면, 그게 정확히 맞습니다 — 필요 없는 구조는 그저 마찰일 뿐입니다.
이미 설치되어 있음
당신의 팀은 이미 Notion, Confluence, 또는 docs/ 폴더에 있습니다. 도입할 것도, 마이그레이션할 것도 없습니다. 마찰이 가장 적은 옵션은 당신이 이미 사용하고 있는 것입니다.
보편적으로 이식 가능
Plain Markdown은 어디서든 열리고 어떤 도구보다 오래 살아남습니다. SpecScore는 바로 이 속성 위에 만들어졌습니다 — SpecScore가 데이터베이스가 아니라 Markdown인 이유입니다.
기능 비교.
차이는 파일이 아닙니다 — 에이전트가 그것으로 무엇을 할 수 있는가입니다.
| 기능 | Plain Markdown / Notion | SpecScore |
|---|---|---|
| 형식 | 자유 형식 Markdown / 문서 | Markdown + YAML frontmatter (구조화) |
| 요구사항이 사는 곳 | Jira, Notion, Slack, 누군가의 머릿속 | 저장소 안, 코드 옆에 |
| "이 스펙은 완성됐나?" | 사람이 읽고 판단함 | specscore lint — 자동 |
| 모호함 탐지 | 없음 — 막연한 동사가 조용히 출시됨 | 막연한 동사, 누락된 인수 기준, 끊어진 참조를 표시 |
| 요구사항 / 인수 기준 ID | 없음 | 기계 주소 지정 가능 ID (REQ: slug) |
| 라이프사이클 상태 | 암시적, 추적된다 해도 | 강제 적용 — Draft → Approved → Implementing → Stable |
| 코드-스펙 추적성 | 없음 | specscore: 어노테이션 + Verifies: 트레일러 |
| 에이전트 탐색 | 무엇이든 찾으려면 모든 파일을 읽어야 함 | 스펙 그래프를 쿼리 — CLI에서 |
| CI 품질 게이트 | 없음 | specscore lint 린터처럼 0이 아닌 코드로 종료 |
| 학습 곡선 | 없음 | 배울 형식 (점진적) |
| 비용 / 라이선스 | 무료 | 무료, 오픈 소스 |
SpecScore가 더 나아가는 부분.
모호함은 해석되는 게 아니라 잡힙니다
자유 형식 스펙에서는 모든 에이전트 상호작용이 해석으로 시작됩니다 — "로그인이 작동해야 한다"는 맞는 것과 그럴듯하지만 틀린 것 사이의 동전 던지기입니다. SpecScore의 lint는 에이전트가 행동하기 전에 막연한 동사와 누락된 인수 기준을 표시합니다.
$ specscore lint auth/login.md ✗ R1 "should work" — unmeasurable ✗ R1 no acceptance criteria
오해가 더 이상 누적되지 않습니다
한 에이전트가 요구사항을 잘못 읽고, 두 번째가 그 위에 쌓고, 세 번째가 둘 다에 의존합니다 — 그리고 당신은 세 에이전트 뒤에야 알아챕니다. 구조화된 인수 기준은 모든 에이전트에게 동일한 통과/실패 조건을 제공하므로, 해석이 그들 사이에서 흔들리지 않습니다.
코드가 스펙으로 추적됩니다
일반 문서는 그것을 구현하는 코드와의 연결이 없습니다. SpecScore는specscore: 소스 어노테이션과 Verifies:커밋 트레일러를 더합니다 — specscore code refs는 "어떤 코드가 이 요구사항을 구현하는가?"에 결정적으로 답합니다.
티켓 40개 대신 스펙 하나
새 팀원(또는 새 에이전트)은 Jira 티켓 40개와 Slack 스레드에서 의도를 재구성하는 대신, 모든 맥락이 담긴 하나의 기능 스펙을 읽습니다.
에이전트는 다시 읽지 않고 쿼리합니다
docs 폴더에서 "무엇이 진행 중인가?"를 찾으려면 파일을 열어야 합니다. SpecScore에서는 specscore feature list 입니다 — 스펙 그래프가 CLI에서 답하므로, 에이전트가 저장소를 다시 읽느라 컨텍스트를 태우지 않습니다.
품질이 CI에서 강제됩니다
자유 형식 스펙에는 게이트가 없습니다 — 절반만 작성된 것도 완성된 것만큼 쉽게 머지됩니다. specscore lint는 문제가 있으면 0이 아닌 코드로 종료합니다 — ESLint나 go vet이 코드를 지키는 것과 같은 방식으로요.
언제 어떤 것을 사용할까.
Plain Markdown이 괜찮은 경우…
- 일회성 노트, 스파이크, 또는 구조가 필요 없을 만큼 작은 프로젝트인 경우.
- 어떤 AI 에이전트도 그 문서로부터 빌드하지 않고 — 사람이 읽고 그냥 이해하는 경우.
- 누군가 구현할 요구사항이 아니라 거친 아이디어를 포착하는 경우.
SpecScore를 선택하세요…
- AI 에이전트가 스펙으로부터 빌드하는 경우 — 모호함이 틀린 코드가 됩니다.
- 여러 에이전트나 사람이 동일한 요구사항에 의존하는 경우.
- 어떤 코드가 어떤 요구사항을 구현하는지 알아야 하는 경우.
- "이 스펙은 끝났나?"가 회의가 아니라 도구로 답해져야 하는 경우.
- 프로젝트가 충분히 커서 전부 다시 읽는 것이 확장되지 않는 경우.
이미 가진 스펙을 졸업시키세요.
백로그를 변환하거나 도구를 바꾸지 않아도 됩니다. 다음 기능을 골라 SpecScore 스펙을 작성하고 specscore lint를 실행해 보세요 — 당신의 티켓이 놓친 것을 잡아내는지 보세요. 구현할 때specscore: 어노테이션을 추가하세요. 도움이 됐을 때만 다음 스프린트로 확장하세요.
Plain Markdown은 진입로입니다. SpecScore는 그것이 졸업해 도달하는 곳입니다.
피드백
이 비교는 공개적으로 이용 가능한 문서와 소스 코드를 기반으로 합니다. 잘못되었거나 오래된 정보가 있나요? 수정 issue를 열어주세요. SpecScore를 다른 도구와 비교해 주길 원하시나요? 요청해 주세요.