specforge

specforge

specforge 是一款用于规范驱动开发的本地工具。它会在工作区中维护一个 specs/ 树：每项功能都有一个带编号的 目录，其中包含规范、章程、计划、任务列表、 研究笔记、澄清和契约；specforge 会创建并维护这些文件。它还可以创建 git 分支，并运行格式化、lint、测试和安全审计检查。 一个二进制文件同时提供命令行界面和 stdio MCP 服务；这里没有任何内容会连接网络服务。

工作区根目录取自 SPECFORGE_ROOT 环境变量，默认为当前工作目录。“当前功能”是大多数工具操作的对象， 即 specs/ 下编号最高的目录；如果尚无功能， 需要当前功能的工具会报错。

安装

npx @reneturcios/specforge specify_start --project-name "My Feature"

或者运行容器映像：

docker run -i ghcr.io/cloudcorprecords/specforge

容器默认启动 MCP 服务（见下文）。传入 CLI 参数即可将其用作 CLI。

CLI

子命令与 MCP 工具名称相对应：

export SPECFORGE_ROOT=/path/to/workspace

specforge specify_start --project-name "Widget API" --agent claude
specforge specify_describe --description "As a user I can create widgets."
specforge constitution_create --principles "Ship small,Test first" --constraints "Node 20"
specforge clarify_add --question "Which database?" --context storage
specforge clarify_resolve --clarification-id CLARIFY-001 --resolution Postgres
specforge spec_validate
specforge research_append --content "Evaluated two libraries; picked the smaller one."
specforge plan_create --constraints-text "Must ship by Friday."
specforge spec_refine --section Requirements --changes "- Must be fast"
specforge artifacts_analyze --artifacts spec,plan,tasks,contracts
specforge tasks_generate --scope backend
specforge tasks_tick --task-id T-001
specforge tasks_tick_range --task-ids T-002,T-003
specforge tasks_filter --preset actionable --limit 5
specforge tasks_search --query widget --fuzzy true
specforge tasks_visualize --format mermaid
specforge tasks_stats --include-charts true
specforge git_create_branch --branch-name feature/widgets
specforge quality_format
specforge quality_lint --fix true
specforge quality_test --coverage true
specforge quality_security_audit

specforge --version

结果以 JSON 格式输出。退出码：成功时为 0；工具失败时为 1（例如没有当前功能，或底层 git/质量检查命令以非零状态退出）；用法错误时为 2。

MCP 服务

一个二进制文件提供两种用法。mcp 子命令会启动 stdio MCP 服务：

npx -y @reneturcios/specforge mcp

MCP 客户端配置：

{
  "mcpServers": {
    "specforge": {
      "command": "npx",
      "args": ["-y", "@reneturcios/specforge", "mcp"],
      "env": { "SPECFORGE_ROOT": "/path/to/workspace" }
    }
  }
}

工具

工具	输入	功能
specify_start	projectName（必填）、agent	创建下一个编号的功能目录，其中包含规格模板、contracts/ 和 research.md。
specify_describe	description（必填）	将描述写入当前功能规格的用户故事部分。
constitution_create	principles（必填）、constraints、preferences	为当前功能编写 constitution.md。
clarify_add	question（必填）、context	将澄清项（CLARIFY-NNN，resolution 为 null）追加到 clarifications.json。
clarify_resolve	clarificationId、resolution（均为必填）	设置澄清项的解决方案。
spec_validate	checks（可选对象）	检查规格是否存在且完整；返回各项检查结果。
research_append	content（必填）	追加内容到 research.md。
plan_create	constraintsText（必填）	根据约束编写 plan.md。
spec_refine	section、changes（均为必填）	替换或添加 spec.md 中的指定章节。
artifacts_analyze	artifacts（必填数组）	报告指定构件是否存在及其大小。
tasks_generate	scope（可选）	根据规格生成 tasks.md，内容为编号复选框列表。
tasks_tick	taskId（必填）	将任务 T-NNN 标记为已完成。
tasks_tick_range	taskIds（必填数组）	将多个任务标记为已完成；报告缺失的 ID。
tasks_filter	preset、limit（可选）	列出任务；默认预设为可执行的（未勾选）任务。
tasks_search	query（必填）、fuzzy	搜索任务文本；模糊匹配也会接受子序列。
tasks_visualize	format（可选）	将任务列表渲染为 text（默认）或 mermaid。
tasks_stats	groupBy、includeCharts（可选）	统计已完成和待处理的任务，可选择附带文本图表。
git_create_branch	branchName（必填）	在工作区运行 git checkout -b <branchName>。
quality_format	fix（可选）	运行 Prettier 检查；如果设置 fix，则运行 --write。
quality_lint	fix（可选）	运行 ESLint；如果设置 fix，则运行 --fix。
quality_test	coverage（可选）	运行 npm test，可选择启用覆盖率。
quality_security_audit	fix（可选）	运行 npm audit；如果设置 fix，则运行 npm audit fix。

如果底层命令不可用或以非零状态退出，Git 和质量工具会返回错误结果；只有命令成功运行时，它们才会报告成功。

注意：原项目的说明文字还提到了 clarify_list 和 artifacts_read，但它们并未出现在文档的工具表中，因此不属于此重建版本。

开发

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, temp dirs and a fake executor, no network
npm run dev     # run the CLI from source via tsx

许可证

MIT — 参见 LICENSE。