跪拜 Guibai
← Back to the summary

OpenSpec, Spec Kit, Harness: A Clear Framework for Choosing AI Development Tools

OpenSpec, Spec Kit, and Harness: Clarify the Relationships Before Choosing AI Development Tools

After using Codex, Cursor, and Claude Code together, teams quickly run into three types of problems:

These problems are related but need different solutions. Rulesync, Spec Kit, OpenSpec, Trellis, and the frequently mentioned Harness each address a different part of the chain.

The first step in tool selection is to put each back in its place.

1. Distinguish first: specs, spec tools, and Harness

A "project constitution" usually records long-term engineering principles, such as architecture boundaries, dependency management, and testing requirements. A feature-specific spec describes the behavior, edge conditions, and acceptance criteria to be implemented this time.

Spec Kit and OpenSpec are tools that help teams organize these matters and drive development. Harness is a broader engineering concept: how a model obtains context, invokes tools, saves progress, and runs verification.

In this table:

Concept or tool Primary role
Project constitution, engineering specs Clarify principles the project follows long-term
Spec Clarify concrete requirements and acceptance criteria
Spec Kit, OpenSpec Organize specs, plans, tasks, and development flows
Harness Provide context, tools, state, and feedback for AI tasks
Trellis Provide a team-level Harness and project knowledge management
Rulesync, Ruler Distribute unified rules or config to different AI tools

So OpenSpec and Spec Kit are comparable; Harness is the concept for understanding execution, and Trellis is a concrete implementation in that direction.

Real products overlap in capabilities. This table emphasizes the responsibilities most worth focusing on during selection, not a strict software layering.

Anthropic's research on long-running agents treats environment initialization, progress logging, incremental development, and verification as important parts of Harness design. Harness practice explanation

2. Walk through a development requirement to see how they cooperate

Suppose a team plans to add "automatic reconnection after disconnect" to a voice chat room.

This breaks into four stages:

Stage Problem to solve Example
Engineering specs What principles to follow during development? Reuse existing RTC wrapper, don't call low-level SDK directly in the page
Requirement spec How should the feature behave? Show reconnecting status after disconnect; allow exit after timeout; avoid joining the room twice
Execution and verification How to keep completing the task? Read relevant code, implement items one by one, run checks, log scenarios not yet done
Cross-tool config How to get same rules after switching tools? Generate or load each tool's project instructions from a unified source

Spec Kit or OpenSpec help the team organize requirements, designs, and tasks.

Harness provides the support needed during execution. For example, the next session can find the task progress; after changes, existing tests can be invoked and results retained.

Rulesync or Ruler handle cross-tool config consistency.

Clear specs reduce misunderstanding; a complete execution mechanism helps tasks keep moving; unified config ensures different tools get consistent requirements. The three can work together, but that doesn't mean every project must install three extra frameworks.

3. Spec Kit and OpenSpec: how to choose

Both support spec-driven development. The more meaningful comparison is how they organize work.

Spec Kit suits teams that want to explicitly establish project principles and development steps.

It provides a flow from project constitution and requirement specs to planning, tasks, and implementation. The team can review artifacts before entering the next stage, gradually clarifying what to do, how to do it, and how to split work. Spec Kit official description

OpenSpec suits teams that organize work around specific changes.

It places proposals, requirements, design, and tasks in a single change, then archives them when done, and explicitly emphasizes support for existing projects. For products that continuously add features, fix bugs, and adjust existing behavior, this organization is worth evaluating. OpenSpec official description

Here is a first-round guideline based on preference:

Team cares more about Evaluate first
Clear project principles, a shared spec and planning process Spec Kit
Driving development around versioned changes OpenSpec
A phased, step-by-step review workflow Spec Kit
Centralizing the reason, design, and tasks of a single change OpenSpec

These are workflow-based suggestions. Both support new and existing projects and are actively expanding. Don't split them simply as "new projects use one, old projects use the other."

Better: run the same real requirement through both, and compare document maintenance cost, team comprehension, and how smoothly you can change requirements.

4. With OpenSpec or Spec Kit, do you still need Trellis?

Depends on what the team is missing.

If existing AI coding tools already support normal development and the team can clearly record requirements, progress, and test results, you can start with the chosen spec process.

When problems go further, Trellis becomes worth considering:

Trellis stores specs, tasks, and logs in the repository and organizes AI workflows through platform adapters. It covers shared specs, project knowledge, and execution. Trellis architecture description

But introducing Trellis means the team must maintain its way of working.

If you adopt Trellis and OpenSpec together, clarify in advance: where requirements live, which instance is the source of truth for task state, and which files get updated after a task finishes. That is design work for a combined setup; you can't assume they coordinate automatically once installed.

5. If you only need to sync "constitution constraints", start with a more direct solution

For the need "the same set of engineering rules usable in Codex, Cursor, and Claude Code", I'd first evaluate Rulesync.

It generates different tools' configs from a unified source and can also import existing configs. Coverage includes rules, skills, MCP, and more. Rulesync official description

Ruler is another option: centrally maintain Markdown rules, then distribute to supported tools. Its core idea is straightforward. Ruler official description

Here you must separate two goals:

Sync tools mainly help with the first. Even if rules are distributed correctly, you still need to verify the actual code.

For teams already using OpenSpec or Spec Kit, you can keep their development flow and add only the config-sync capability you need. In a combination, assign a single managing tool for each generated file to avoid overwrites.

6. Choose based on the current problem, not by installing everything at once

For a first-round selection for a team, I'd use this table:

Most pressing problem Suggested starting point
Engineering rules inconsistent across multiple AI tools Rulesync; also compare Ruler
Steps from requirement to implementation unclear Spec Kit
Existing product iterates constantly, hard to track changes OpenSpec
Context and progress don't persist across sessions and members Trellis
Rules are complete but delivery quality is still unstable First add testing, review, and verification

These are adaptation judgments based on official documents; they still need validation on actual clients and projects.

For a pilot, pick one project and one real requirement, then observe three outcomes: whether the team repeats less explanation, whether rules load correctly, and whether there is clear verification evidence before delivery.

Whether to add more tools next round depends on those three results.

Comments

Top 1 from juejin.cn, machine-translated. The original thread is authoritative.

组合搭配函数

I totally agree with this approach of picking based on pain points; installing everything at once is just digging a pit for yourself. In a previous project I stacked several different workflows, and the states ended up conflicting every day, and in the end we had to manually patch things up — it was really troublesome.