OpenSpec을 사용하는 공개 저장소 87곳과 변경 사항 1,725건을 분석한 결과, 프로젝트가 커질수록 요구사항의 원자성과 구현 세부사항 배제 측면에서 점수가 낮아졌다. 문법 검사를 통과해도 요구사항의 품질을 보장하지는 않았으며, 완료한 작업을 명세에 반영하는 openspec archive를 건너뛰는 사례도 흔했다.
문법 통과가 명세 품질을 뜻하지는 않는다
40개 프로젝트를 비교한 무작위 표본에서 37곳은 거의 모든 요구사항에 SHALL 또는 MUST와 시나리오가 있었다. 하지만 읽기 평가 점수와 자동 검사 점수의 상관관계는 거의 없었다(ρ = −0.02). 자동 검사는 형식을 확인하지만, 요구사항이 명확하고 검증 가능하며 한 가지 의무만 담았는지는 별도로 살펴야 한다.
프로젝트 크기는 품질 점수와 음의 상관관계를 보였다(ρ = −0.53). 규모가 커질수록 요구사항 하나에 여러 의무가 묶이거나 파일 경로, 내부 클래스, 함수 서명이 들어가는 경향이 나타났다. 크기 효과는 인기 프로젝트 표본에서도 확인됐다(ρ = −0.52). 반면 명확성과 테스트 가능성은 규모에 따라 크게 달라지지 않았다.
무작위 표본의 프로젝트에서는 요구사항 하나가 정확히 하나의 의무를 담은 비율이 중앙값 55%였고, 실패 상황을 다룬 시나리오가 있는 요구사항은 35%였다. 변경 제안만 작성하고 주 명세를 관리하지 않는 프로젝트에서는 단일 의무를 담은 비율이 85%였다. 다만 두 집단은 서로 다른 프로젝트이므로, 이 차이는 작성 뒤 명세가 편집되면서 요구사항이 복잡해진다는 설명을 뒷받침하는 정황이지 전후 비교 결과는 아니다.
완료한 변경 사항도 명세에 남지 않는 경우
주 명세가 있는 프로젝트 65곳에서 열린 변경 사항을 살펴보니, 작업 목록의 모든 항목을 완료 표시했지만 보관 처리하지 않은 변경이 있었다. 이런 변경은 openspec/changes/에 남고, 주 명세에는 반영되지 않는다. OpenSpec 저장소 자체도 열린 변경 30건 가운데 23건의 작업 항목이 모두 완료 표시됐지만 보관되지 않은 상태였다. 완료 표시가 곧 방치나 출시를 뜻하는 것은 아니며, 팀이 검토나 출시 시점에 보관할 수도 있다. 다만 보관 전까지 주 명세와 이를 읽는 도구는 변경 전 동작을 가리킨다.
변경 제안만 관리하는 프로젝트 25곳에서는 활성 변경에 ADDED 요구사항 1,581개, MODIFIED 76개, REMOVED 4개가 있었고 RENAMED는 없었다. 변경을 보관하지 않으면 제안들이 서로 조정되지 않아 실제 시스템의 명세가 열린 변경 사항 전체에 흩어질 수 있다.
인기와 별점은 품질을 예측하지 못했다
GitHub 별 수와 명세 품질 점수의 상관관계는 무작위 표본에서 ρ = −0.03, 별이 많은 25개 프로젝트에서 ρ = −0.20이었다. 인기 프로젝트가 무작위 표본보다 높은 점수를 얻은 비율은 59%였지만, 차이는 통계적으로 우연의 범위 안에 있었다(Mann–Whitney z = 1.09). OpenSpec 유지 관리자가 사례로 든 OpenSpec 자체 저장소는 40곳 중 3위였지만, 커뮤니티에서 언급된 다른 프로젝트들은 무작위 표본보다 낫지 않았다.
형식상 구조 제목도 중요하다. studyzy/imewlconverter와 hawk86104/three-vue-tres는 요구사항 제목을 중국어로 바꿨다. 산문은 어떤 언어로 써도 되지만 제목은 OpenSpec이 해석하는 문법이므로, 검증기는 두 저장소의 명세를 모두 거부했다. 따라서 연구진은 두 프로젝트의 점수를 매기지 않고 별 수 기준 다음 두 프로젝트를 대신 포함했다.
팀이 적용할 수 있는 점검 항목
요구사항마다 의무 하나만 두고, 파일 경로와 함수 서명 같은 구현 세부사항은 design.md나 코드에 둔다. 각 요구사항에는 잘못된 입력, 오류 또는 거부 상황을 다루는 시나리오도 포함한다. 기능을 만들 때 Purpose를 작성하고, 산문 언어와 관계없이 OpenSpec의 구조 제목은 영어로 유지한다.
작업이 끝나면 openspec archive를 완료 절차에 포함해 변경 사항을 주 명세에 반영한다. 주 명세 안에 ## ADDED Requirements 같은 변경 제목을 남기면 OpenSpec이 해당 요구사항을 읽지 못할 수도 있다. 연구에서는 전체 2,444개 명세 파일 가운데 866개가 보관 과정에서 생성되는 TBD - created by archiving change …를 Purpose로 그대로 두고 있었다.
연구 범위와 한계
이번 결과는 공개 저장소의 상관관계 분석이며 실험 결과는 아니다. 기본 브랜치의 2026년 10월 15일 시점 스냅샷을 사용했다. 40개 프로젝트의 요구사항 797개를 이름을 가린 뒤 무작위로 골라 언어 모델이 평가했고, 두 차례 평가의 99.9% 이상이 1점 이내에서 일치했다. 세 번째 모델 평가에서는 상위 5개 중 같은 프로젝트 5곳, 하위 5개 중 4곳이 다시 선정됐다. 언어에 따라 달라지는 자동 검사는 영어와 중국어만 지원해 프랑스어와 독일어 프로젝트에는 적용하지 않았다.
연구를 진행한 Loft는 OpenSpec 프로젝트를 가져오는 명세 도구를 만든다. 연구진은 Loft의 자체 검사를 순위 산정에서 제외했다고 밝혔으며, 연구 방법을 점수 산정 전에 기록하고 파일럿 이후 변경 사항과 이유를 남겼다고 설명했다. Loft 2.1은 2026년 10월 15일 출시됐으며, OpenSpec의 주 명세를 Loft 형식으로 변환하는 기능을 제공한다.
댓글 (0)
로그인하면 이 기사에 내 생각을 남길 수 있어요