글

명세 관리: 명세를 코드로 저장하고, 버전을 관리하고, 검토하기

명세 관리는 팀이 소프트웨어 명세를 저장하고, 각 변경을 기록하고, 그 변경을 검토하고, 명세를 최신으로 유지하는 방식입니다. 명세서를 관리하는 일도 같은 일입니다. 명세는 소프트웨어가 무엇을 해야 하는지를 말하는 문서이고, 그것을 관리한다는 것은 그 문서를 찾을 수 있고 믿을 수 있게 두는 일입니다. 명세를 코드로 관리한다는 것은 그 문서가 버전 관리 시스템의 파일이라는 뜻이며, 명세의 변경은 리뷰어가 diff할 수 있는 커밋입니다. 명세 버전 관리는 그 커밋의 이력과, 각 문서에 적힌 상태를 함께 가리킵니다. 명세를 코드와 동기화된 상태로 유지한다는 것은, 명세의 구조를 깨는 제안된 변경이 코드 변경이 거치는 것과 같은 자동 검사에서 실패한다는 뜻입니다. 명세 주도 개발(SDD, spec-driven development)은 코드보다 먼저 명세를 쓰고, 명세를 진실의 원천으로 다루는 방식입니다. 지속적 통합(CI, continuous integration)은 제안된 변경마다 도는 자동 검사입니다. 제품 요구사항 문서(PRD, product requirements document)는 문제와 범위를 적는 산문입니다. Markdown PRD 템플릿은 그 형태의 SpecScore 기능 파일 하나입니다. Easy Approach to Requirements Syntax(EARS)는 요구사항의 문장 패턴입니다. SpecScore에서 요구사항(REQ)은 기능 안의 이름이 있는 규칙이고, 인수 기준(AC, acceptance criterion)은 그 규칙 하나 이상을 가리키는 선택적 추상 조건입니다. 그 검사는 명령줄 인터페이스(CLI, command-line interface) 명령 specscore spec lint이며, CI에서 명세 린터로 명세를 린트하기에 문서화되어 있습니다. 형식은 공개 저장소 specscore/specscore(CC BY 4.0)에 있습니다. CLI는 specscore/specscore-cli(Apache-2.0)에 있습니다.

마지막 업데이트: 2026년 11월 9일

명세를 저장하는 곳

명세 관리는 파일이 있을 자리에서 시작합니다. 이 저장소에서 명세는 spec/ 아래의 Markdown입니다. spec README가 나열하는 디렉터리는 features, plans, ideas, decisions, lessons입니다. 기능은 README.md 하나를 가진 디렉터리입니다. 기능 명세가 그 파일의 계약이고, PRD 템플릿은 린터가 받아들인 채워진 예입니다.

specscore spec lint는 어느 트리를 읽을지 추측하지 않습니다. internal/cli/spec.go는 태그 v0.55.1에 있고, 같은 함수는 태그 v0.39.1에도 있습니다. 그 함수는 작업 디렉터리에서 위로 올라가 specscore.yaml를 찾을 때까지 갑니다. 그 함수의 주석은, 명령이 이 파일을 요구하고, 파일이 없으면 종료 코드 3을 반환하며, specscore init을 실행하라고 알려 준다고 말합니다. 이 저장소의 dogfood 워크플로는 CLI v0.39.1을 설치한 다음 specscore spec lint를 실행하므로, 그것이 린트하는 체크아웃에는 그 설정 파일이 있습니다.

기능 파일 옆에는 인덱스가 있습니다. 규칙 feature-index-row-sync는 v0.39.1과 v0.55.1의 lint 목록에서 오류입니다. 목록의 줄은, 기능 인덱스의 각 행이 그 기능 파일과 일치할 것을 요구한다고 말합니다. 그것은 인덱스가 가리키는 문서와 정렬되어 있다는 뜻입니다. 요구사항의 문장과 소스 파일을 비교하는 일이 아닙니다.

명세 버전 관리

git에 커밋된 파일에 대한 명세 버전 관리는 그 파일들의 커밋 이력입니다. SpecScore는 기능에 두 번째 버전 번호를 더하지 않습니다. 리뷰어가 보는 리비전은 브랜치의 커밋입니다. 문서의 상태 줄은 그 기능이 수명 주기의 어디에 있는지를 말합니다. 그것은 git 해시와는 다른 사실입니다.

저장소의 기능 명세는 그 자체가 **Status:** Stable입니다. 제목 바로 다음에 **Status:** 줄을 요구하고, 값은 Draft, In Review, Approved, Implementing, Stable, Amending, Rejected, 또는 Deprecated 중 하나여야 합니다. 규칙 status-mirror는 위에서 이름을 든 두 목록 모두에서, 상태를 가진 산출물의 frontmatter status:가 그 본문 줄과 일치할 것을 요구하고, 상태가 없는 유형에는 status:를 금지합니다. 두 복사본을 일치시키는 것은 여덟 값 밖의 단어를 거부하는 것과 같지 않습니다. 두 목록의 줄 모두, 그 집합 밖의 기능 상태를 거부하는 규칙을 설명하지 않으므로, 이 페이지는 그런 규칙이 있다고 주장하지 않습니다.

계획은 다른 집합을 씁니다. 규칙 P-006는 두 목록 모두에서, 단일 파일 계획의 본문 **Status:**가 Draft, In Review, Approved, Executing, Blocked, Implemented, Failed, Rejected, Withdrawn, Superseded, 또는 Deprecated 중 하나일 것을 요구합니다. 규칙 idea-status-values는 그 규칙이 허용하는 집합 밖의 아이디어 상태를 거부합니다. 목록이 그 명단입니다. 이 페이지는 아이디어의 단어를 다시 적지 않습니다.

계획 명세는 열이 Date, Git Hash, Action, Comment인 선택적 ## Snapshots 표도 설명합니다. 각 스냅샷은 그 시점의 계획 상태를 가리키는 git 커밋 해시를 참조한다고 말합니다. 이 페이지를 위해 확인한 두 lint 목록은 그 해시를 해석하는 규칙을 이름 붙이지 않으므로, 이 페이지는 린터가 커밋의 존재를 검사한다고 주장하지 않습니다. 해시는 사람이 git에서 따라갈 수 있는 포인터입니다. 공개된 계획 명세는 그 문서의 형식 페이지입니다.

명세 검토

Markdown 명세의 검토는 그것을 바꾸는 풀 리퀘스트입니다. dogfood.yml는 pull_request와 main으로의 push에서 실행됩니다. 작업은 저장소를 체크아웃하고, SPECSCORE_VERSION을 v0.39.1로 두어 CLI를 설치하고, 추가 플래그 없이 specscore spec lint를 실행합니다. 그 프로세스가 0이 아닌 값으로 끝나면 GitHub Actions는 그 단계를 실패로 둡니다. 워크플로의 권한은 contents: read입니다.

기능 상태 In Review는 기능이 검토를 위해 나와 있음을 뜻합니다. 그 단어를 쓰는 것은 Markdown 파일을 고치는 일입니다. 풀 리퀘스트는 사람이 diff를 읽는 곳입니다. status-mirror는 frontmatter와 본문이 같은 상태를 이름 붙이는지 검사합니다. 리뷰어가 산문에 동의했는지는 기록하지 않습니다. 검증기 페이지는 그 구조 검사와, 사람이 아직 해야 하는 읽기를 구분합니다. specscore spec lint가 보고하는 것의 규칙별 설명은 CI에서 명세 린터로 명세를 린트하기에 있습니다.

명세를 코드와 동기화된 상태로 유지하기

이 사이트에서 명세를 코드와 동기화된 상태로 유지한다는 것은, 명세가 프로젝트와 같은 저장소에 있고, 명세 트리가 형식을 위반하면 CI가 풀 리퀘스트를 실패시킨다는 뜻입니다. 풀 리퀘스트는 같은 diff 안에서 기능 파일과 코드를 바꿀 수 있습니다. 규칙 feature-index-row-sync는 인덱스 행을, 그것이 이름 붙인 기능 파일과 정렬된 상태로 둡니다. 소스 파일을 읽고 코드가 요구사항을 구현하는지는 정하지 않습니다.

아래 발췌는 dogfood.yml의 설치와 린트 단계입니다. 워크플로 파일은 권한, 동시성 그룹, 핀이 latest가 아닌 이유에 대한 주석도 설정합니다. 그 줄은 여기서 빠집니다. 명령은 그 파일이 실행하는 것입니다.

dogfood.yml의 설치와 린트 단계
name: Dogfood lint

on:
  push:
    branches: [main]
  pull_request:

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
      - name: Install specscore CLI (pinned)
        env:
          SPECSCORE_VERSION: v0.39.1
        run: |
          curl -fsSL https://specscore.md/install/get-cli | \
            SPECSCORE_INSTALL_DIR="$HOME/.local/bin" sh
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
          specscore --version
      - name: Lint spec tree
        run: specscore spec lint

그 파일의 주석은, 떠 있는 latest 핀이 저장소 아래의 관문을 바꾼다고 말합니다. 풀 리퀘스트와, 그것이 가리키는 main 브랜치는 서로 다른 규칙을 볼 수 있습니다. 핀은 v0.39.1입니다. 작업은 --fix를 넘기지 않습니다. 깨끗한 실행과 실패하는 실행은, file:line [severity] rule: message 줄을 포함하여, CI에서 명세 린터로 명세를 린트하기에 나와 있습니다.

더는 코드를 설명하지 않는 명세의 문장은 그 발견 중 하나가 아닙니다. specscore spec lint가 검증하는 것은 구조입니다. 필수 파일과 절, 인덱스 행, 제목의 형태, 그리고 규칙이 이름 붙이는 참조입니다. 구현이 요구사항과 일치하는지는 채점하지 않습니다. 그 한계가 검증기 페이지의 요점입니다. 산문을 참으로 유지하는 일은 여전히 diff의 검토입니다.

다른 명세 주도 도구가 명세를 검사하는 방식

아래 문단은 2026년 11월 9일에 가져온 페이지를 씁니다. 그 도구들 자신의 검사를 설명합니다. 제품이 몇 개 있는지는 말하지 않고, 시장에 순위를 매기지도 않습니다. 도구 정리가 더 긴 비교입니다.

GitHub Spec Kit 에이전트형 SDD 참고는 /speckit.analyze를 spec.md, plan.md, tasks.md에 걸친 읽기 전용 검사로 설명합니다. 충돌, 빈틈, 모호함을 보고하고, 파일을 편집하지 않으며, 구현 전에 에이전트 안에서 실행합니다. 같은 페이지의 명령 목록은 SpecScore 트리에 대해 specscore spec lint를 실행하는 CI 작업을 설명하지 않습니다.

OpenSpec는 변경을 openspec/changes/ 바로 아래의 디렉터리로 저장합니다. openspec validate는 변경과 명세의 구조적 문제를 검사합니다. 참고 문서는 종료 코드 0이 검증한 항목이 모두 통과했음을 뜻하고, 종료 코드 1은 항목이 실패했거나, 보고 요청이 유효하지 않거나, 설정을 읽을 수 없거나, 실행이 실패했음을 뜻한다고 말합니다. 그 검사는 OpenSpec의 형태이며, 요구사항 블록과 시나리오 블록을 포함하고, SpecScore의 ### AC: 제목이 아닙니다. 다른 명령 openspec status에 대해, 같은 참고 문서는 변경 하나를 불러오지 못하는 배치도 여전히 1로 끝나며, “so CI doesn’t accept an incomplete report as successful.”라고 말합니다. 그 문장은 openspec status에 대한 것이고, openspec validate에 대한 것이 아닙니다.

자주 묻는 질문

명세 관리란 무엇입니까?

명세 관리는 소프트웨어 명세를 저장하고, 각 변경을 기록하고, 그 변경을 검토하고, 명세를 최신으로 유지하는 일입니다. SpecScore에서 파일은 git 저장소의 Markdown이고, specscore spec lint는 CI 작업이 실패할 수 있는 구조 검사입니다.

명세서 관리란 무엇입니까?

명세서 관리는 같은 실천입니다. 명세는 소프트웨어가 무엇을 해야 하는지를 말하는 문서입니다. 그것을 관리한다는 것은, 문서에 알려진 자리, 이력, 검토, 그리고 구조가 아직도 형식과 일치하는지에 대한 검사가 있다는 뜻입니다.

명세를 코드로 관리하는 것은 어떻게 동작합니까?

명세는 spec/ 아래의 Markdown 파일 트리에, 저장소 루트의 specscore.yaml를 더한 것입니다. 변경은 커밋입니다. 풀 리퀘스트가 diff를 검토합니다. dogfood.yml가 그 풀 리퀘스트에서 specscore spec lint를 실행합니다.

명세 버전 관리는 어떻게 동작합니까?

git 이력이 파일의 버전 이력입니다. 기능은 또한 기능 명세가 요구하는 여덟 값 중 하나를 **Status:**에 담습니다. 계획은 Git Hash가 그 계획 상태의 커밋인 ## Snapshots 행을 기록할 수 있습니다. 여기서 인용한 린터 목록은 그 해시를 해석하는 규칙을 설명하지 않습니다.

명세를 코드와 동기화된 상태로 유지하려면 어떻게 합니까?

명세를 저장소에 두고, specscore spec lint가 구조 위반을 보고하면, 기능 파일과 일치하지 않는 인덱스 행을 포함하여, 풀 리퀘스트를 실패시키십시오. 명령은 코드가 요구사항을 구현하는지를 정하지 않습니다. 코드에서 벗어난 문장은 여전히 사람이 diff를 읽어야 합니다.

명세를 저장소에 두세요.

번역 오류를 발견했거나 이 페이지를 개선할 아이디어가 있나요?