Spec-driven development with Claude Code and Cursor

Claude Code is an agentic coding tool that reads a codebase, edits files, and runs commands. Cursor is the editor whose project rules live in .cursor/rules as .mdc files. 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, a feature specification is the file for one product capability, a requirement (REQ) is a named rule inside that feature, and an acceptance criterion (AC) is an optional abstract condition that points at one or more of those rules. Continuous integration (CI) is an automatic check on every proposed change. The check is a command-line interface (CLI) command, specscore spec lint, from the CLI in 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.

Last updated: 6 November 2026

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. 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 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 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 in 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.

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.

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 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. 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. 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. 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, under the MIT licence. Its skills README says users invoke /specscore:<skill-name>. 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 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 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 is the guided workflow. The repository is specscore/specstudio-skills, under the MIT licence. 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 in 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. 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 in specscore/specscore. The CLI licence is Apache-2.0 in specscore/specscore-cli.

Other spec-driven tools publish different checks. The sentences below use only what those projects’ own pages say. The tools roundup records the same pages as read on 30 October 2026, except the Spec Kit documentation home, which prints 28 September 2026.

OpenSpec documents openspec validate in its CLI reference. That command checks OpenSpec’s change and spec structure. It does not check a SpecScore ### AC: heading.

The 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 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 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 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.