# Spec-driven development with Claude Code and Cursor Canonical: https://specscore.md/articles/claude-code-specs/ Last updated: 6 November 2026 [Claude Code](https://code.claude.com/docs/en/overview) is an agentic coding tool that reads a codebase, edits files, and runs commands. [Cursor](https://cursor.com/docs/rules) is the editor whose project rules live in `.cursor/rules` as `.mdc` files. [Spec-driven development](https://specscore.md/spec-driven-development/) (SDD) is the practice of writing the specification before the code and treating the specification as the source of truth. A product requirements document (PRD) is the prose that states the problem and the scope before the work is split into tasks. In [SpecScore](https://specscore.md/), a [feature specification](https://specscore.md/feature-specification) is the file for one product capability, a [requirement](https://specscore.md/requirement-specification) (REQ) is a named rule inside that feature, and an [acceptance criterion](https://specscore.md/acceptance-criteria-specification) (AC) is an optional abstract condition that points at one or more of those rules. [Continuous integration](https://specscore.md/validators/) (CI) is an automatic check on every proposed change. The check is a [command-line interface](https://specscore.md/cli/) (CLI) command, `specscore spec lint`, from the CLI in [specscore/specscore-cli](https://github.com/specscore/specscore-cli). Cursor specs, on this page, are that feature file together with the Cursor project rule that tells the agent to lint it. ## What goes in the feature, and what goes in the agent file The feature file holds the obligation. A feature README under `spec/features/` carries the `#### REQ:` rules and the `### AC:` criteria. The filled-in shape, the plan, and the task are the [PRD template in Markdown](https://specscore.md/articles/feature-spec-template/). `specscore spec lint` checks that shape: headings, required sections, index rows, and references. It does not decide whether the product idea is a good one. [Lint specs in CI](https://specscore.md/articles/lint-specs-in-ci/) is the longer account of the command. The agent file holds instructions for one tool. Anthropic’s overview says `CLAUDE.md` is a Markdown file at the project root that Claude Code reads at the start of every session. Cursor’s rules documentation says a project rule is an `.mdc` file in `.cursor/rules`, and that a plain `.md` file in that directory is ignored because it has no frontmatter. Those files tell the agent how to work in the repository. They are not the specification the linter checks. A requirement that exists only in `CLAUDE.md` or only in `.cursor/rules/specscore.mdc` is invisible to `specscore spec lint`. ## What specscore agent setup writes The [CLI README](https://github.com/specscore/specscore-cli/blob/main/README.md) says `specscore agent setup` writes each agent’s instruction file and, where that agent has a skills directory, copies SpecScore skill bundles into it. The command skips an existing file unless you pass `--force`. The contract is the [agent-setup feature](https://github.com/specscore/specscore-cli/blob/main/spec/features/cli/agent/setup/README.md) in [specscore/specscore-cli](https://github.com/specscore/specscore-cli). That contract maps the caller id `claude` to `CLAUDE.md` and `.claude/skills/`, and the caller id `cursor` to `.cursor/rules/specscore.mdc` and `.cursor/skills/`. Run the command inside a project that already has `specscore.yaml`. If that file is missing, the command exits 6 and the message suggests `specscore init`. One invocation that names both agents is `specscore agent setup claude,cursor`. The feature says a comma-separated list is the same as separate arguments. Parent directories are created. Every path is reported as added, modified, or skipped. The generated `CLAUDE.md` includes the project title, CLI examples that pass `--caller claude`, and the install line `/plugin install specscore@specscore`. The Cursor file is Markdown with YAML frontmatter. The frontmatter contains `description` and `alwaysApply: true`. Cursor’s rules table says `alwaysApply: true` means the rule is included in every chat. `--no-skills` writes the instruction files and does not copy skill bundles. The same contract table also names `codex`, `copilot`, `antigravity.google`, `pi.dev`, `opencode`, and `deepseek`. This page follows the two agents in the title. ### Writes the Claude Code and Cursor files. Run it from a project that has specscore.yaml. ```text specscore agent setup claude,cursor ``` ### Paths the contract assigns to claude and cursor. Skill directories are not created when you pass --no-skills. An existing file stays as it is unless you pass --force. ```text CLAUDE.md .claude/skills/ .cursor/rules/specscore.mdc .cursor/skills/ ``` The instruction file points at the feature tree. It does not replace it. After setup, Claude Code still has to read `spec/features/`, and Cursor’s rule still has to point at the same tree. The [feature specification](https://specscore.md/feature-specification) remains the document `specscore spec lint` accepts or rejects. ## Run specscore spec lint in the loop Install the CLI first. The install methods are on the [install page](https://specscore.md/cli/install/). Then keep the feature and the linter in the same loop as the agent. ### Write the feature before the prompt Add the feature README, the features index row, and `specscore.yaml` using the [PRD template](https://specscore.md/articles/feature-spec-template/). Put each obligation under `## Behavior` as `#### REQ: {slug}`. Point acceptance criteria at those ids with `**Requirements:**`. Leave `CLAUDE.md` and `.cursor/rules/` for the next step. ### Lint before the agent edits code Run `specscore spec lint` in the repository. A clean tree prints `0 violations found` and exits 0. The failure report — file, line, severity, rule, message — is in [lint specs in CI](https://specscore.md/articles/lint-specs-in-ci/). Fix the feature until that command is clean. An agent that starts from a feature the linter already rejects will copy the broken shape. ### Point Claude Code and Cursor at the tree Run `specscore agent setup claude,cursor`. Read the added `CLAUDE.md` and `.cursor/rules/specscore.mdc` and confirm they name the spec tree and the CLI, including `--caller`. If either file already existed, the command skips it. Pass `--force` only when you mean to replace that file. ### Ask for a task that names a criterion In the agent session, name the feature and the acceptance criterion the work has to satisfy. A plan task does that with `**Verifies:**` and an acceptance-criterion id. Ask the agent to run `specscore spec lint` again before it finishes, and to change the feature file when the behavior changes. The instruction file tells the agent to run the command. The feature file is what the command checks. ## Skills that surface lint, feature, and task The CLI README’s install lines for the wrapper plugin are `/plugin marketplace add specscore/ai-marketplace` and `/plugin install specscore@specscore`. The plugin repository is [specscore/ai-plugin-specscore](https://github.com/specscore/ai-plugin-specscore), under the [MIT licence](https://github.com/specscore/ai-plugin-specscore/blob/main/LICENSE). Its [skills README](https://github.com/specscore/ai-plugin-specscore/blob/main/skills/README.md) says users invoke `/specscore:`. The shipped wrappers include `/specscore:spec`, which wraps `specscore spec lint`; `/specscore:feature`, which wraps `specscore feature` (`list`, `info`, `tree`, `deps`, `refs`, `new`, and `change-status`); and `/specscore:task`, which wraps `specscore task`. `/specscore:change-status` covers feature and idea status changes. The [CLI Skills](https://specscore.md/ai/cli-skills/) page on this site is that wrapper. `specscore agent setup` copies those skill bundles into `.claude/skills/` and `.cursor/skills/` unless you pass `--no-skills`. The plugin README says Cursor has no remote-install command and loads skills from `.cursor/skills/` in the project or from `~/.cursor/skills/`. The manual copy it shows is `git clone` of [ai-plugin-specscore](https://github.com/specscore/ai-plugin-specscore/blob/main/README.md) and `cp -R` of `skills/*` into `.cursor/skills/`. `specscore agent setup cursor` is the command that does that copy for you, from the marketplace the feature spec names. [SpecStudio Skills](https://specscore.md/ai/specstudio-skills/) is the guided workflow. The repository is [specscore/specstudio-skills](https://github.com/specscore/specstudio-skills), under the [MIT licence](https://github.com/specscore/specstudio-skills/blob/main/LICENSE). Its README’s Claude Code install line is `/plugin install specstudio@specscore`, and it says Claude Code installs the `specscore` plugin as a dependency. The status section names version 0.0.7 and says the `ideate`, `specify`, `plan`, `implement`, `verify`, and `recap` skills are active enough to dogfood. The same README’s inventory table documents `specstudio:ideate` and `specstudio:specify` in detail. Those skills write SpecScore artifacts. They do not replace `specscore spec lint`. ## The same command in CI [dogfood.yml](https://github.com/specscore/specscore/blob/main/.github/workflows/dogfood.yml) in [specscore/specscore](https://github.com/specscore/specscore) sets `SPECSCORE_VERSION` to `v0.39.1` and runs `specscore spec lint` on pull requests and on pushes to main. The workflow excerpt and the text report are in [lint specs in CI](https://specscore.md/articles/lint-specs-in-ci/). A feature that breaks a heading fails that job whether Claude Code or Cursor wrote the file. The agent loop and CI call the same command. The format licence is [CC BY 4.0](https://github.com/specscore/specscore/blob/main/LICENSE) in [specscore/specscore](https://github.com/specscore/specscore). The CLI licence is [Apache-2.0](https://github.com/specscore/specscore-cli/blob/main/LICENSE) in [specscore/specscore-cli](https://github.com/specscore/specscore-cli). Other spec-driven tools publish different checks. The sentences below use only what those projects’ own pages say. The [tools roundup](https://specscore.md/spec-driven-development/tools/) records the same pages as read on 30 October 2026, except the Spec Kit documentation home, which prints 28 September 2026. [OpenSpec](https://github.com/Fission-AI/OpenSpec) documents `openspec validate` in its [CLI reference](https://openspec.dev/docs/cli). That command checks OpenSpec’s change and spec structure. It does not check a SpecScore `### AC:` heading. The [Task Master](https://github.com/eyaltoledano/claude-task-master) README describes parsing a PRD into tasks with `task-master parse-prd`. It does not describe a linter for that PRD. [GitHub Spec Kit](https://github.github.io/spec-kit/) describes an agent workflow whose phases write Markdown artifacts. That documentation home does not describe a command that lints a SpecScore feature README in CI. ## FAQ ### What is Claude Code spec-driven development? It is writing the SpecScore feature before Claude Code writes the code, then keeping `CLAUDE.md` as the instruction file that points at that feature. The feature holds the requirements (REQ) and acceptance criteria (AC). `specscore spec lint` checks the feature. `specscore agent setup claude` writes `CLAUDE.md` in a project that already has `specscore.yaml`. ### Where do Cursor specs go? The product obligation goes in the feature README under `spec/features/`. The Cursor project rule goes in `.cursor/rules/specscore.mdc`. Skill files go in `.cursor/skills/`. `specscore agent setup cursor` writes the rule and, unless you pass `--no-skills`, copies the skill bundles. Cursor’s own documentation is the source for how `.mdc` rules are applied. ### Does CLAUDE.md replace the feature spec? No. `CLAUDE.md` is what Claude Code reads as instructions. The feature README is what `specscore spec lint` checks. The [agent-setup feature](https://github.com/specscore/specscore-cli/blob/main/spec/features/cli/agent/setup/README.md) says the generated file teaches the agent the spec tree and the CLI commands. It does not say the instruction file is the specification. ### What if CLAUDE.md or the Cursor rule already exists? The command skips the existing file and prints a skip line that mentions `--force`. The existing bytes stay. Pass `--force` only when replacement is what you want. The same skip rule applies to a skill file that is already present. ### Which skill runs the linter? In the plugin’s skills README, `/specscore:spec` wraps `specscore spec lint`. You can also run that CLI command yourself, in the agent session or in CI. `/specscore:feature` and `/specscore:task` wrap the feature and task commands. They do not lint by themselves. ### Does the linter grade the prose? No. `specscore spec lint` checks structure. [Lint specs in CI](https://specscore.md/articles/lint-specs-in-ci/) shows the report. A clean structural check is not a product review. ## Sources Agent-setup behavior is the contract in specscore-cli spec/features/cli/agent/setup/README.md on main, read 6 November 2026. Skill names are from ai-plugin-specscore skills/README.md on main, read the same day. SpecStudio’s install line and the version 0.0.7 status list are from specstudio-skills README.md on main, read the same day. Claude Code’s description and the CLAUDE.md sentence are from code.claude.com/docs/en/overview. Cursor project-rule paths are from cursor.com/docs/rules. dogfood.yml in this repository pins SPECSCORE_VERSION to v0.39.1. Competitor pages are the ones linked below; the tools roundup records them as read on 30 October 2026, except the Spec Kit documentation home, which prints 28 September 2026. - [Claude Code — overview (CLAUDE.md)](https://code.claude.com/docs/en/overview) - [Cursor — Rules (project rules are .mdc files)](https://cursor.com/docs/rules) - [specscore-cli — agent-setup feature](https://github.com/specscore/specscore-cli/blob/main/spec/features/cli/agent/setup/README.md) - [specscore-cli — README (agent setup and plugin install)](https://github.com/specscore/specscore-cli/blob/main/README.md) - [specscore/specscore-cli](https://github.com/specscore/specscore-cli) - [specscore-cli — Apache-2.0 licence](https://github.com/specscore/specscore-cli/blob/main/LICENSE) - [specscore/specscore](https://github.com/specscore/specscore) - [specscore/specscore — CC BY 4.0 licence](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 licence](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 copy)](https://github.com/specscore/ai-plugin-specscore/blob/main/README.md) - [specscore/specstudio-skills](https://github.com/specscore/specstudio-skills) - [specstudio-skills — MIT licence](https://github.com/specscore/specstudio-skills/blob/main/LICENSE) - [specstudio-skills — README (version 0.0.7)](https://github.com/specscore/specstudio-skills/blob/main/README.md) - [CLI Skills](https://specscore.md/ai/cli-skills/) - [SpecStudio Skills](https://specscore.md/ai/specstudio-skills/) - [PRD template in Markdown for AI coding](https://specscore.md/articles/feature-spec-template/) - [Lint specs in CI with a spec linter](https://specscore.md/articles/lint-specs-in-ci/) - [Feature specification](https://specscore.md/feature-specification) - [Acceptance criteria specification](https://specscore.md/acceptance-criteria-specification) - [OpenSpec CLI reference — 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 documentation (page date 28 September 2026)](https://github.github.io/spec-kit/) - [Spec-driven development tools](https://specscore.md/spec-driven-development/tools/) ## Related - [PRD template in Markdown for AI coding](https://specscore.md/articles/feature-spec-template/) - [Lint specs in CI with a spec linter](https://specscore.md/articles/lint-specs-in-ci/) - [How to write acceptance criteria AI agents can verify](https://specscore.md/articles/acceptance-criteria/) - [EARS requirements syntax explained, with examples](https://specscore.md/articles/ears-requirements/) - [Spec-driven development](https://specscore.md/spec-driven-development/) - [Spec-driven development tools](https://specscore.md/spec-driven-development/tools/) - [CLI Skills](https://specscore.md/ai/cli-skills/) - [SpecStudio Skills](https://specscore.md/ai/specstudio-skills/) - [CLI](https://specscore.md/cli/) - [Feature specification](https://specscore.md/feature-specification)