# Claude Code와 Cursor로 하는 명세 주도 개발

Canonical: https://specscore.md/ko/articles/claude-code-specs/

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

[Claude Code](https://code.claude.com/docs/en/overview)는 코드베이스를 읽고, 파일을 고치고, 명령을 실행하는 에이전트형 코딩 도구입니다. [Cursor](https://cursor.com/docs/rules)는 프로젝트 규칙이 `.cursor/rules`에 `.mdc` 파일로 있는 편집기입니다. [명세 주도 개발](https://specscore.md/ko/spec-driven-development/)(SDD, spec-driven development)은 코드보다 먼저 명세를 쓰고, 명세를 진실의 원천으로 다루는 방식입니다. 제품 요구사항 문서(PRD, product requirements document)는 일을 작업으로 나누기 전에 문제와 범위를 적는 산문입니다. [SpecScore](https://specscore.md/)에서 [기능 명세](https://specscore.md/feature-specification)는 제품의 한 능력을 위한 파일이고, [요구사항](https://specscore.md/requirement-specification)(REQ, requirement)은 그 기능 안의 이름이 있는 규칙이며, [인수 기준](https://specscore.md/acceptance-criteria-specification)(AC, acceptance criterion)은 그 규칙 하나 이상을 가리키는 선택적 추상 조건입니다. [지속적 통합](https://specscore.md/ko/validators/)(CI, continuous integration)은 제안된 변경마다 도는 자동 검사입니다. 그 검사는 [명령줄 인터페이스](https://specscore.md/ko/cli/)(CLI, command-line interface) 명령 `specscore spec lint`이며, CLI는 [specscore/specscore-cli](https://github.com/specscore/specscore-cli)에 있습니다. 이 페이지에서 Cursor 명세는, 그 기능 파일과, 에이전트에게 그것을 린트하라고 알리는 Cursor 프로젝트 규칙을 합친 것입니다.

## 기능에 들어가는 것과 에이전트 파일에 들어가는 것

기능 파일이 의무를 담습니다. `spec/features/` 아래의 기능 README는 `#### REQ:` 규칙과 `### AC:` 기준을 실습니다. 채워 넣은 형태, 계획, 작업이 [Markdown PRD 템플릿](https://specscore.md/ko/articles/feature-spec-template/)입니다. `specscore spec lint`는 그 형태를 검사합니다. 제목, 필수 절, 인덱스 행, 참조입니다. 제품 생각이 좋은지는 정하지 않습니다. [CI에서 명세 린터로 명세를 린트하기](https://specscore.md/ko/articles/lint-specs-in-ci/)가 그 명령에 대한 더 긴 설명입니다.

에이전트 파일은 하나의 도구를 위한 지시를 담습니다. Anthropic의 개요는 `CLAUDE.md`가 프로젝트 루트의 Markdown 파일이며, Claude Code가 매 세션 시작 때 읽는다고 말합니다. Cursor의 규칙 문서는 프로젝트 규칙이 `.mdc` 파일이고 `.cursor/rules`에 있으며, 그 디렉터리의 평범한 `.md` 파일은 frontmatter가 없어서 무시된다고 말합니다. 그 파일들은 저장소에서 어떻게 일할지 에이전트에게 알립니다. 린터가 검사하는 명세는 아닙니다. `CLAUDE.md`에만, 또는 `.cursor/rules/specscore.mdc`에만 있는 요구사항은 `specscore spec lint`에 보이지 않습니다.

## specscore agent setup이 쓰는 것

[CLI README](https://github.com/specscore/specscore-cli/blob/main/README.md)는 `specscore agent setup`이 각 에이전트의 지시 파일을 쓰고, 그 에이전트에 스킬 디렉터리가 있으면 SpecScore 스킬 번들을 그 안으로 복사한다고 말합니다. 명령은 `--force`를 넘기지 않는 한 기존 파일을 건너뜁니다. 계약은 [agent-setup 기능](https://github.com/specscore/specscore-cli/blob/main/spec/features/cli/agent/setup/README.md)이며, [specscore/specscore-cli](https://github.com/specscore/specscore-cli)에 있습니다.

그 계약은 호출자 id `claude`를 `CLAUDE.md`와 `.claude/skills/`에, 호출자 id `cursor`를 `.cursor/rules/specscore.mdc`와 `.cursor/skills/`에 대응시킵니다. 이미 `specscore.yaml`이 있는 프로젝트 안에서 명령을 실행합니다. 그 파일이 없으면 명령은 6으로 끝나고, 메시지는 `specscore init`을 제안합니다. 두 에이전트를 모두 이름 붙이는 한 번의 호출은 `specscore agent setup claude,cursor`입니다. 기능은 쉼표로 구분한 목록이 따로 준 인자와 같다고 말합니다. 부모 디렉터리는 만들어집니다. 모든 경로는 추가, 수정 또는 건너뜀으로 보고됩니다.

생성된 `CLAUDE.md`에는 프로젝트 제목, `--caller claude`를 넘기는 CLI 예, 설치 줄 `/plugin install specscore@specscore`가 들어 있습니다. Cursor 파일은 YAML frontmatter가 있는 Markdown입니다. frontmatter에는 `description`과 `alwaysApply: true`가 들어 있습니다. Cursor의 규칙 표는 `alwaysApply: true`가 규칙을 모든 채팅에 포함한다는 뜻이라고 말합니다. `--no-skills`는 지시 파일을 쓰고 스킬 번들은 복사하지 않습니다. 같은 계약 표는 `codex`, `copilot`, `antigravity.google`, `pi.dev`, `opencode`, `deepseek`도 이름 붙입니다. 이 페이지는 제목에 있는 두 에이전트를 다룹니다.

### Claude Code와 Cursor 파일을 씁니다. specscore.yaml이 있는 프로젝트에서 실행합니다.

```text
specscore agent setup claude,cursor
```

### 계약이 claude와 cursor에 할당하는 경로. --no-skills를 넘기면 스킬 디렉터리는 만들어지지 않습니다. 기존 파일은 --force를 넘기지 않는 한 그대로 남습니다.

```text
CLAUDE.md
.claude/skills/
.cursor/rules/specscore.mdc
.cursor/skills/
```

지시 파일은 기능 트리를 가리킵니다. 그것을 대체하지는 않습니다. 설정 후에도 Claude Code는 `spec/features/`를 읽어야 하고, Cursor의 규칙도 같은 트리를 가리켜야 합니다. [기능 명세](https://specscore.md/feature-specification)는 `specscore spec lint`가 받아들이거나 거부하는 문서로 남습니다.

## 루프 안에서 specscore spec lint 실행하기

먼저 CLI를 설치합니다. 설치 방법은 [설치 페이지](https://specscore.md/ko/cli/install/)에 있습니다. 그다음 기능과 린터를 에이전트와 같은 루프에 둡니다.

### 프롬프트 전에 기능 쓰기

[PRD 템플릿](https://specscore.md/ko/articles/feature-spec-template/)을 써서 기능 README, 기능 인덱스 행, `specscore.yaml`을 추가합니다. 각 의무는 `## Behavior` 아래에 `#### REQ: {slug}`로 둡니다. 인수 기준은 `**Requirements:**`로 그 id를 가리킵니다. `CLAUDE.md`와 `.cursor/rules/`는 다음 단계에 남깁니다.

### 에이전트가 코드를 고치기 전에 린트하기

저장소에서 `specscore spec lint`를 실행합니다. 깨끗한 트리는 `0 violations found`를 출력하고 종료 코드 0입니다. 실패 보고 — 파일, 줄, 심각도, 규칙, 메시지 — 는 [CI에서 명세 린터로 명세를 린트하기](https://specscore.md/ko/articles/lint-specs-in-ci/)에 있습니다. 그 명령이 깨끗해질 때까지 기능을 고칩니다. 린터가 이미 거부한 기능에서 시작하는 에이전트는 깨진 형태를 베낍니다.

### Claude Code와 Cursor를 트리로 향하게 하기

`specscore agent setup claude,cursor`를 실행합니다. 추가된 `CLAUDE.md`와 `.cursor/rules/specscore.mdc`를 읽고, 그것들이 명세 트리와 CLI를 이름 붙이는지, `--caller`를 포함하는지 확인합니다. 어느 한쪽 파일이 이미 있었다면, 명령은 그것을 건너뜁니다. `--force`는 그 파일을 바꾸려는 뜻일 때만 넘깁니다.

### 기준의 이름을 대는 작업 요청하기

에이전트 세션에서는, 일이 만족해야 하는 기능과 인수 기준의 이름을 댑니다. 계획의 작업은 `**Verifies:**`와 인수 기준 id로 그렇게 합니다. 끝나기 전에 `specscore spec lint`를 다시 실행하고, 행동이 바뀌면 기능 파일을 바꾸라고 에이전트에게 요청합니다. 지시 파일은 에이전트에게 명령을 실행하라고 알립니다. 명령이 검사하는 것은 기능 파일입니다.

## lint, feature, task를 드러내는 스킬

래퍼 플러그인에 대해 CLI README의 설치 줄은 `/plugin marketplace add specscore/ai-marketplace`와 `/plugin install specscore@specscore`입니다. 플러그인 저장소는 [specscore/ai-plugin-specscore](https://github.com/specscore/ai-plugin-specscore)이며, [MIT 라이선스](https://github.com/specscore/ai-plugin-specscore/blob/main/LICENSE) 아래에 있습니다. 그 [skills README](https://github.com/specscore/ai-plugin-specscore/blob/main/skills/README.md)는 사용자가 `/specscore:<skill-name>`를 호출한다고 말합니다. 함께 제공되는 래퍼에는 `/specscore:spec`이 있고, 그것은 `specscore spec lint`를 감쌉니다. `/specscore:feature`는 `specscore feature`(`list`, `info`, `tree`, `deps`, `refs`, `new`, `change-status`)를 감쌉니다. `/specscore:task`는 `specscore task`를 감쌉니다. `/specscore:change-status`는 기능과 아이디어의 상태 변경을 다룹니다. 이 사이트의 [CLI Skills](https://specscore.md/ko/ai/cli-skills/) 페이지가 그 래퍼입니다. `specscore agent setup`은 그 스킬 번들을 `.claude/skills/`와 `.cursor/skills/`로 복사합니다. 다만 `--no-skills`를 넘기면 복사하지 않습니다.

플러그인 README는 Cursor에 원격 설치 명령이 없고, 스킬을 프로젝트의 `.cursor/skills/`에서, 또는 `~/.cursor/skills/`에서 불러온다고 말합니다. 거기에 나오는 수동 복사는 `git clone`으로 [ai-plugin-specscore](https://github.com/specscore/ai-plugin-specscore/blob/main/README.md)를 받고, `cp -R`로 `skills/*`를 `.cursor/skills/`로 넣는 것입니다. `specscore agent setup cursor`는 기능 명세가 이름을 붙인 마켓플레이스에서 그 복사를 대신 해 주는 명령입니다.

[SpecStudio Skills](https://specscore.md/ko/ai/specstudio-skills/)는 안내형 워크플로입니다. 저장소는 [specscore/specstudio-skills](https://github.com/specscore/specstudio-skills)이며, [MIT 라이선스](https://github.com/specscore/specstudio-skills/blob/main/LICENSE) 아래에 있습니다. 그 README의 Claude Code 설치 줄은 `/plugin install specstudio@specscore`이고, Claude Code가 `specscore` 플러그인을 의존성으로 설치한다고 말합니다. 상태 절은 버전 0.0.7을 이름 붙이고, `ideate`, `specify`, `plan`, `implement`, `verify`, `recap` 스킬이 dogfood할 수 있을 만큼 활성이라고 말합니다. 같은 README의 목록 표는 `specstudio:ideate`와 `specstudio:specify`를 자세히 문서화합니다. 그 스킬들은 SpecScore 산출물을 씁니다. `specscore spec lint`를 대체하지는 않습니다.

## CI에서도 같은 명령

[dogfood.yml](https://github.com/specscore/specscore/blob/main/.github/workflows/dogfood.yml)는 [specscore/specscore](https://github.com/specscore/specscore)에서 `SPECSCORE_VERSION`을 `v0.39.1`로 두고, pull request와 main으로의 push에서 `specscore spec lint`를 실행합니다. 워크플로 발췌와 텍스트 보고는 [CI에서 명세 린터로 명세를 린트하기](https://specscore.md/ko/articles/lint-specs-in-ci/)에 있습니다. 제목을 깨뜨린 기능은 파일을 쓴 것이 Claude Code든 Cursor든 그 작업을 실패하게 합니다. 에이전트 루프와 CI는 같은 명령을 호출합니다.

형식의 라이선스는 [CC BY 4.0](https://github.com/specscore/specscore/blob/main/LICENSE)이며, [specscore/specscore](https://github.com/specscore/specscore)에 있습니다. CLI의 라이선스는 [Apache-2.0](https://github.com/specscore/specscore-cli/blob/main/LICENSE)이며, [specscore/specscore-cli](https://github.com/specscore/specscore-cli)에 있습니다.

다른 명세 주도 도구는 서로 다른 검사를 공개합니다. 아래 문장은 그 프로젝트 자신의 페이지가 말하는 것만 사용합니다. [도구 정리](https://specscore.md/ko/spec-driven-development/tools/)는 같은 페이지를 2026년 10월 30일에 읽은 것으로 기록합니다. 다만 Spec Kit 문서 홈은 2026년 9월 28일을 인쇄합니다.

[OpenSpec](https://github.com/Fission-AI/OpenSpec)는 `openspec validate`를 자신의 [CLI 참고](https://openspec.dev/docs/cli)에 문서화합니다. 그 명령은 OpenSpec의 변경과 명세 구조를 검사합니다. SpecScore의 `### AC:` 제목은 검사하지 않습니다.

[Task Master](https://github.com/eyaltoledano/claude-task-master) README는 `task-master parse-prd`로 PRD를 작업으로 파싱한다고 설명합니다. 그 PRD를 위한 린터는 설명하지 않습니다.

[GitHub Spec Kit](https://github.github.io/spec-kit/)는 단계가 Markdown 산출물을 쓰는 에이전트 워크플로를 설명합니다. 그 문서 홈은 CI에서 SpecScore 기능 README를 린트하는 명령을 설명하지 않습니다.

## 자주 묻는 질문

### Claude Code 명세 주도 개발이란 무엇입니까?

Claude Code가 코드를 쓰기 전에 SpecScore 기능을 쓰고, 그다음 `CLAUDE.md`를 그 기능을 가리키는 지시 파일로 유지하는 것입니다. 기능은 요구사항(REQ)과 인수 기준(AC)을 담습니다. `specscore spec lint`가 기능을 검사합니다. `specscore agent setup claude`는 `CLAUDE.md`를, 이미 `specscore.yaml`이 있는 프로젝트에 씁니다.

### Cursor 명세는 어디에 둡니까?

제품의 의무는 `spec/features/` 아래의 기능 README에 들어갑니다. Cursor 프로젝트 규칙은 `.cursor/rules/specscore.mdc`에 들어갑니다. 스킬 파일은 `.cursor/skills/`에 들어갑니다. `specscore agent setup cursor`는 규칙을 쓰고, `--no-skills`를 넘기지 않는 한 스킬 번들을 복사합니다. `.mdc` 규칙이 어떻게 적용되는지의 출처는 Cursor 자신의 문서입니다.

### CLAUDE.md가 기능 명세를 대체합니까?

아닙니다. `CLAUDE.md`는 Claude Code가 지시로 읽는 파일입니다. 기능 README는 `specscore spec lint`가 검사하는 파일입니다. [agent-setup 기능](https://github.com/specscore/specscore-cli/blob/main/spec/features/cli/agent/setup/README.md)는 생성된 파일이 에이전트에게 명세 트리와 CLI 명령을 가르친다고 말합니다. 지시 파일이 명세라고는 말하지 않습니다.

### CLAUDE.md나 Cursor 규칙이 이미 있으면 어떻게 됩니까?

명령은 기존 파일을 건너뛰고, `--force`를 언급하는 건너뛰기 줄을 출력합니다. 기존 바이트는 그대로 남습니다. `--force`는 교체가 원하는 것일 때만 넘깁니다. 같은 건너뛰기 규칙은 이미 있는 스킬 파일에도 적용됩니다.

### 어느 스킬이 린터를 실행합니까?

플러그인의 skills README에서 `/specscore:spec`는 `specscore spec lint`를 감쌉니다. 그 CLI 명령은 에이전트 세션에서나 CI에서나 직접 실행할 수도 있습니다. `/specscore:feature`와 `/specscore:task`는 기능과 작업 명령을 감쌉니다. 그것들 자체가 린트하지는 않습니다.

### 린터는 산문을 채점합니까?

아닙니다. `specscore spec lint`는 구조를 검사합니다. [CI에서 명세 린터로 명세를 린트하기](https://specscore.md/ko/articles/lint-specs-in-ci/)가 보고를 보여 줍니다. 깨끗한 구조 검사는 제품 검토가 아닙니다.

## 출처

agent-setup 동작은 main의 specscore-cli spec/features/cli/agent/setup/README.md에 있는 계약이며, 2026년 11월 6일에 읽었습니다. 스킬 이름은 main의 ai-plugin-specscore skills/README.md에서 왔으며, 같은 날에 읽었습니다. SpecStudio의 설치 줄과 버전 0.0.7 상태 목록은 main의 specstudio-skills README.md에서 왔으며, 같은 날에 읽었습니다. Claude Code의 설명과 CLAUDE.md 문장은 code.claude.com/docs/en/overview에서 왔습니다. Cursor 프로젝트 규칙 경로는 cursor.com/docs/rules에서 왔습니다. 이 저장소의 dogfood.yml은 SPECSCORE_VERSION을 v0.39.1에 고정합니다. 경쟁 페이지는 아래에 링크된 것입니다. 도구 정리는 그것들을 2026년 10월 30일에 읽은 것으로 기록합니다. 다만 Spec Kit 문서 홈은 2026년 9월 28일을 인쇄합니다.

- [Claude Code — 개요 (CLAUDE.md)](https://code.claude.com/docs/en/overview)
- [Cursor — 규칙 (프로젝트 규칙은 .mdc 파일)](https://cursor.com/docs/rules)
- [specscore-cli — agent-setup 기능](https://github.com/specscore/specscore-cli/blob/main/spec/features/cli/agent/setup/README.md)
- [specscore-cli — README (agent setup과 플러그인 설치)](https://github.com/specscore/specscore-cli/blob/main/README.md)
- [specscore/specscore-cli](https://github.com/specscore/specscore-cli)
- [specscore-cli — Apache-2.0 라이선스](https://github.com/specscore/specscore-cli/blob/main/LICENSE)
- [specscore/specscore](https://github.com/specscore/specscore)
- [specscore/specscore — CC BY 4.0 라이선스](https://github.com/specscore/specscore/blob/main/LICENSE)
- [specscore/specscore — dogfood.yml (CLI v0.39.1)](https://github.com/specscore/specscore/blob/main/.github/workflows/dogfood.yml)
- [specscore/ai-plugin-specscore](https://github.com/specscore/ai-plugin-specscore)
- [ai-plugin-specscore — MIT 라이선스](https://github.com/specscore/ai-plugin-specscore/blob/main/LICENSE)
- [ai-plugin-specscore — skills README](https://github.com/specscore/ai-plugin-specscore/blob/main/skills/README.md)
- [ai-plugin-specscore — README (Cursor로 복사)](https://github.com/specscore/ai-plugin-specscore/blob/main/README.md)
- [specscore/specstudio-skills](https://github.com/specscore/specstudio-skills)
- [specstudio-skills — MIT 라이선스](https://github.com/specscore/specstudio-skills/blob/main/LICENSE)
- [specstudio-skills — README (버전 0.0.7)](https://github.com/specscore/specstudio-skills/blob/main/README.md)
- [CLI Skills](https://specscore.md/ko/ai/cli-skills/)
- [SpecStudio Skills](https://specscore.md/ko/ai/specstudio-skills/)
- [AI 코딩을 위한 Markdown PRD 템플릿](https://specscore.md/ko/articles/feature-spec-template/)
- [CI에서 명세 린터로 명세를 린트하기](https://specscore.md/ko/articles/lint-specs-in-ci/)
- [기능 명세](https://specscore.md/feature-specification)
- [인수 기준 명세](https://specscore.md/acceptance-criteria-specification)
- [OpenSpec CLI 참고 — openspec validate](https://openspec.dev/docs/cli)
- [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec)
- [eyaltoledano/claude-task-master](https://github.com/eyaltoledano/claude-task-master)
- [GitHub Spec Kit 문서 (페이지 날짜 2026년 9월 28일)](https://github.github.io/spec-kit/)
- [명세 주도 개발 도구](https://specscore.md/ko/spec-driven-development/tools/)

## 관련

- [AI 코딩을 위한 Markdown PRD 템플릿](https://specscore.md/ko/articles/feature-spec-template/)
- [CI에서 명세 린터로 명세를 린트하기](https://specscore.md/ko/articles/lint-specs-in-ci/)
- [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/)
- [CLI Skills](https://specscore.md/ko/ai/cli-skills/)
- [SpecStudio Skills](https://specscore.md/ko/ai/specstudio-skills/)
- [CLI](https://specscore.md/ko/cli/)
- [기능 명세](https://specscore.md/feature-specification)