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

Canonical: https://specscore.md/ko/articles/spec-management/

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

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

## 명세를 저장하는 곳

명세 관리는 파일이 있을 자리에서 시작합니다. 이 저장소에서 명세는 `spec/` 아래의 Markdown입니다. [spec README](https://github.com/specscore/specscore/blob/main/spec/README.md)가 나열하는 디렉터리는 features, plans, ideas, decisions, lessons입니다. 기능은 `README.md` 하나를 가진 디렉터리입니다. [기능 명세](https://specscore.md/feature-specification)가 그 파일의 계약이고, [PRD 템플릿](https://specscore.md/ko/articles/feature-spec-template/)은 린터가 받아들인 채워진 예입니다.

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

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

## 명세 버전 관리

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

저장소의 [기능 명세](https://github.com/specscore/specscore/blob/main/spec/features/feature/README.md)는 그 자체가 `**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`는 그 규칙이 허용하는 집합 밖의 아이디어 상태를 거부합니다. 목록이 그 명단입니다. 이 페이지는 아이디어의 단어를 다시 적지 않습니다.

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

## 명세 검토

Markdown 명세의 검토는 그것을 바꾸는 풀 리퀘스트입니다. [dogfood.yml](https://github.com/specscore/specscore/blob/main/.github/workflows/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와 본문이 같은 상태를 이름 붙이는지 검사합니다. 리뷰어가 산문에 동의했는지는 기록하지 않습니다. [검증기 페이지](https://specscore.md/ko/validators/)는 그 구조 검사와, 사람이 아직 해야 하는 읽기를 구분합니다. `specscore spec lint`가 보고하는 것의 규칙별 설명은 [CI에서 명세 린터로 명세를 린트하기](https://specscore.md/ko/articles/lint-specs-in-ci/)에 있습니다.

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

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

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

### dogfood.yml의 설치와 린트 단계

```yaml
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에서 명세 린터로 명세를 린트하기](https://specscore.md/ko/articles/lint-specs-in-ci/)에 나와 있습니다.

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

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

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

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

[OpenSpec](https://github.com/Fission-AI/OpenSpec)는 변경을 `openspec/changes/` 바로 아래의 디렉터리로 저장합니다. [openspec validate](https://openspec.dev/docs/cli)는 변경과 명세의 구조적 문제를 검사합니다. 참고 문서는 종료 코드 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](https://github.com/specscore/specscore/blob/main/.github/workflows/dogfood.yml)가 그 풀 리퀘스트에서 `specscore spec lint`를 실행합니다.

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

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

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

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

## 출처

CLI 파일과 lint 목록은 2026년 11월 9일, specscore-cli 태그 v0.39.1(dogfood.yml이 설치하는 버전)과 v0.55.1에서 읽었습니다. 기능과 계획의 요구사항은 아래에 링크한 specscore/specscore의 파일입니다. 경쟁 제품의 페이지는 같은 날 가져왔습니다.

- [specscore/specscore — spec/README.md](https://github.com/specscore/specscore/blob/main/spec/README.md)
- [specscore/specscore — 기능 상태 값](https://github.com/specscore/specscore/blob/main/spec/features/feature/README.md)
- [specscore/specscore — 계획 스냅샷](https://github.com/specscore/specscore/blob/main/spec/features/plan/README.md)
- [specscore/specscore](https://github.com/specscore/specscore)
- [specscore/specscore — CC BY 4.0 라이선스](https://github.com/specscore/specscore/blob/main/LICENSE)
- [specscore/specscore-cli](https://github.com/specscore/specscore-cli)
- [specscore-cli — Apache-2.0 라이선스](https://github.com/specscore/specscore-cli/blob/main/LICENSE)
- [specscore-cli v0.39.1 — internal/cli/spec.go](https://github.com/specscore/specscore-cli/blob/v0.39.1/internal/cli/spec.go)
- [specscore-cli v0.55.1 — internal/cli/spec.go](https://github.com/specscore/specscore-cli/blob/v0.55.1/internal/cli/spec.go)
- [specscore-cli v0.39.1 — lint 규칙 목록](https://github.com/specscore/specscore-cli/blob/v0.39.1/docs/lint-rules.md)
- [specscore-cli v0.55.1 — lint 규칙 목록](https://github.com/specscore/specscore-cli/blob/v0.55.1/docs/lint-rules.md)
- [specscore/specscore — dogfood.yml (CLI v0.39.1)](https://github.com/specscore/specscore/blob/main/.github/workflows/dogfood.yml)
- [SpecScore가 검증하는 것](https://specscore.md/ko/validators/)
- [CI에서 명세 린터로 명세를 린트하기](https://specscore.md/ko/articles/lint-specs-in-ci/)
- [EARS 요구사항 구문을 예와 함께 설명](https://specscore.md/ko/articles/ears-requirements/)
- [AI 에이전트가 검증할 수 있는 인수 기준을 쓰는 법](https://specscore.md/ko/articles/acceptance-criteria/)
- [AI 코딩을 위한 Markdown PRD 템플릿](https://specscore.md/ko/articles/feature-spec-template/)
- [기능 명세](https://specscore.md/feature-specification)
- [계획 명세](https://specscore.md/plan-specification)
- [GitHub Spec Kit — 에이전트형 SDD 참고 (/speckit.analyze)](https://github.github.io/spec-kit/reference/agentic-sdd.html)
- [OpenSpec CLI 참고 — openspec validate와 openspec status](https://openspec.dev/docs/cli)
- [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec)
- [명세 주도 개발 도구](https://specscore.md/ko/spec-driven-development/tools/)

## 관련

- [CI에서 명세 린터로 명세를 린트하기](https://specscore.md/ko/articles/lint-specs-in-ci/)
- [AI 코딩을 위한 Markdown PRD 템플릿](https://specscore.md/ko/articles/feature-spec-template/)
- [AI 에이전트가 검증할 수 있는 인수 기준을 쓰는 법](https://specscore.md/ko/articles/acceptance-criteria/)
- [EARS 요구사항 구문을 예와 함께 설명](https://specscore.md/ko/articles/ears-requirements/)
- [명세 주도 개발](https://specscore.md/ko/spec-driven-development/)
- [명세 주도 개발 도구](https://specscore.md/ko/spec-driven-development/tools/)
- [기능 명세](https://specscore.md/feature-specification)
- [계획 명세](https://specscore.md/plan-specification)
- [CLI](https://specscore.md/ko/cli/)
- [SpecScore가 검증하는 것](https://specscore.md/ko/validators/)
