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:
- The same project maintains different versions of rules in different tools.
- Requirements are already stated, but the AI still misses key scenarios during implementation.
- Mid-task, switching sessions forces you to re-explain progress.
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:
- Development spans multiple sessions; progress and decisions often need re-explaining.
- Multiple people and tools are involved; project knowledge is scattered.
- You want to unify task state, context loading, and work logs.
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:
- Config consistency: each tool gets the same version of the rules.
- Result compliance: final code passes tests, static checks, and human review.
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.
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.