SoloForge

一人干完一个小团队的活。

规则驱动的 AI 工程协作 MCP 工作流系统

SoloForge 把 Claude Code 接入同一套项目规则、知识模板和验证门禁，让 AI 在你的项目里：先理解边界再动手、按能力域推进、产物可追溯、交付有证据。

它是一个契约治理内核——负责分类任务、注入知识、生成验证计划、记录任务状态、提供审查建议和证据链。它不假装替宿主 AI 完成完整工程治理，而是给 AI 套上可审计的约束。

⚠️ 控制权原则：任务状态机、工具调用、副作用权限、验证裁决由本地 TypeScript 内核控制；LLM 只作为认知节点提供结构化 proposal。AI 不能绕过 MCP 篡改 .soloforge/state，非 MCP 来源的变更不能冒充可信交付。

目录

• ✨ 特性
• 📦 安装
• 🚀 快速开始
• 🧠 工作原理
• 📂 项目知识库
• 📐 设计产物目录
• ✅ 验证与交付
• 🛡️ 安全护栏
• 🖥️ CLI 与 MCP 工具
• ❓ 常见问题
• 🛠️ 贡献与本仓库开发
• 📄 许可证

✨ 特性

🎯 任务驱动导航 — sf_task 开任务后提示下一步；架构关键决策通过 confirm_decisions 逐域与用户确认（业务流程/数据/安全/后端/前端/基础设施六域，确认才放行设计）。

📐 设计产物不漂移 — 需求、原型、架构、数据库、API、切片按统一生命周期合同审计。全链路用两位数 ID 绑定（REQ-01 / ARCH-01 / SLICE-01 / AC-01），不能只说"已按设计实现"。

🔒 工程实现契约 — 编码阶段约束 OOD/SOLID、Controller/Handler/Router 入参出参、参数校验、事务、幂等、权限、日志和错误处理。

🔍 抗偷懒与对抗审查 — 禁止空洞章节、占位符（TBD）、无证据 ✅。审查两层：per-artifact（单产物产出后深度审）+ cross-artifact（交付前跨产物一致性），多利益方独立对抗（用户/攻击者/维护者/性能/合规），K 次独立采样取交集（首次 K=3，每轮独立不互参、取多数复现；内容变更后的差量重审降至 K=1 单次独立复核——基于前次 K=3 基线 +「自上次审查以来的内容 diff」聚焦；不追求「零 error 收敛」，但多数复现 error 必须核验并进入修复/误报/接受风险闭环）。

✅ 验证有证据 — SoloForge 生成验证命令但不自己执行。只有真实执行并录入结果才算通过；计划、构造记录、未执行的验证都不触发交付。

🧩 抽象缺失检测 — 自动检测 AM-01~04 反模式（无领域模型、复制无提取、硬编码魔法数字、复杂分支无抽象），触发时强制抽象建模。

🛡️ 不可降级的安全护栏 — 只读保护、写入 scope 保护、状态保护、并发保护、隐私脱敏，全程强制。

🔧 机制化发布门禁 — SoloForge 自身发布前跑 15 phase 门禁，检查机制消费链路、知识治理、配置边界、诊断码注册，防止只靠文档自证。

📦 安装

npm install -g soloforge

前置要求：Node.js >= 18，以及 Claude Code。

🚀 快速开始

# 1. 进入项目根目录
cd /path/to/my-project

# 2. 一键接入（生成 MCP 连接 + 工作流指令 + 知识库骨架）
soloforge init
#    生成 Claude Code 接入文件（.mcp.json + CLAUDE.md + .claude/settings.json）

# 3. 重新打开 AI 工具加载新配置
#    Claude Code: 退出后在项目目录重新启动 claude

接入后，直接对 AI 说自然语言——「下一步」「验证」「设计架构」「查看状态」——AI 会自动选择对应 MCP 工具。

想先看不写盘的预览？跑 soloforge init --dry-run。MCP 连不上？跑 soloforge doctor 诊断控制面与状态可信。

init 只做接入，不写 intent.yaml——项目规划、配置推断都留给 AI 连上 MCP 后通过对话完成。技术栈和构建命令由 package.json / pom.xml / go.mod 等项目文件自动探测，大多数项目无需手动配置。

🧠 工作原理

SoloForge 把工程交付拆成 4 个能力域，AI 在每个域内通过 8 个 MCP 工具 推进：

┌─────────────────────────────────────────────────────────┐
│                    4 能力域（domain）                     │
├──────────┬──────────┬──────────┬─────────────────────────┤
│  design  │  build   │  verify  │        operate          │
│ 设计      │ 构建      │ 验证      │ 运营                    │
│ 需求/原型  │ 编码/实现 │ 审查/测试  │ 交付/回滚/诊断          │
│ 架构/DB   │          │ 验收      │                         │
│ API/切片  │          │          │                         │
└──────────┴──────────┴──────────┴─────────────────────────┘
        AI 在域内循环：observe → 按 ordered_plan 推进（verify→act→wait）

核心循环：sf_task 开任务 → sf_work action=observe 看当前域状态（返回 ordered_plan：verify→act→wait 有序推进计划，先补欠验证不跳步、再 act 新产物、阻塞最后）→（有疑问时 action=deliberate 条件研讨）→ sf_work action=act 拿到受可做性门禁约束的执行 prompt（①同域依赖阻塞拒 ②跨域缺上游拒 ③有未验证产物拒不并行 ④verified 产物须有对抗审查且 error finding 已闭环；重写修复/演进放行）→ sf_work action=verify 跑域内门禁 → sf_work action=adversarial_review 对抗审查（per-artifact 深审单产物 / cross-artifact 跨产物一致性，首次 K=3 独立采样取交集，内容变更后差量重审 K=1（基于前次基线 + diff 聚焦）；多数复现 error 必须核验并标记 fixed / false_positive / accepted_risk；所有域所有产物 per-artifact 不可省，act 门禁④强制）→ 通过则推进下一域。

AI（认知节点）                          SoloForge 内核（控制权）
  │                                        │
  │── sf_work action=act ──────────────▶── │ 读取知识 + 应用门禁
  │                                        │ 生成结构化执行 prompt
  │◀────────── 返回受约束的 prompt ──────── │
  │                                        │
  │   AI 按 prompt 写产物文件               │
  │                                        │
  │── sf_work action=verify ───────────▶── │ 校验产物 + 验证证据
  │◀────────── 返回裁决 + 下一步 ──────────  │

两个增强 action（让 AI 先想清楚、再被独立挑刺）：

• deliberate（对话框交互式研讨）：act 之前，AI 在对话框与你逐点头脑风暴 + 第一性原理收敛（有疑问来回讨论、无疑问一行确认跳过），收敛后总结留痕到 docs/研讨记录/。研讨记录不计入产物，避免产物类型爆炸。
• adversarial_review（对抗审查）：verify 之后、交付前，per-artifact 深审单产物 + cross-artifact 跨产物一致性，多利益方（用户/攻击者/维护者/性能/合规）独立对抗，K 次独立采样取交集（首次 K=3，每轮独立不互参、取多数复现；内容变更后差量重审 K=1——基于前次 K=3 基线与「自上次审查以来的内容 diff」单次独立复核；不追求「零 error 收敛」，但多数复现 error 必须核验闭环）。

控制权边界：LLM 提供建议和结构化 proposal，但任务状态机、工具调用、副作用权限、验证裁决由内核裁决。这是 SoloForge 区别于"纯 prompt 工程"的根本。

📂 项目知识库

SoloForge 执行任务时自动从 .soloforge/knowledge/ 读取匹配的知识文件注入 AI prompt。你可以往里面添加自己的规则。soloforge init 会在 .soloforge/knowledge/ 下生成空骨架目录（domain/、procedures/、checklists/ 等）和一份说明文件——它不预置任何内置规则（避免与 templates/ 重复），你直接往对应子目录加 .md 规则即可。

文件格式

必须用 .md（.yaml 不支持正文注入）。每个文件由 YAML frontmatter 和 Markdown 正文组成，正文才是注入 prompt 的内容。

最小示例

---
name: 支付规则
triggers: ["支付", "结算", "退款", "payment", "refund"]
domain: [backend]
products: ["*"]
---

## 业务规则
1. 退款金额不得超过原支付金额
2. 跨境支付需走外汇审批流程

frontmatter 字段

| 字段 | 必填 | 说明 | |------|------|------| | triggers | 是 | 触发关键词数组，任务意图匹配时才选中 | | verification_layer | 是 | 校验层：L0/L1（确定性探针，需配 probe+probe_path）/ L2（LLM 审查注入，默认）/ L3（人工确认）。缺失即被拒绝，不默认 L2 | | domain | 否 | 适用能力域：design / build / verify / operate，可多选 | | routes | 否 | 执行路由（如 code_change），hard rule 必填 | | enforcement.level | 否 | 强制级别（如 hard_rule），进入强执行审计 | | lifecycle_stages | 否 | 生命周期阶段，与 triggers 至少填一个，否则 hard rule fail-closed | | scope / products / type / tech_stack | 否 | 作用域 / 产品线 / 分类 / 技术栈过滤 |

字段统一：frontmatter 用 type / triggers / domain，已废弃的 asset_kind / when / primary_triggers / stages 不得出现（由架构测试守护）。

校验层（verification_layer）

规则按"可机械化程度"分四层，决定它怎么被校验：

| 层 | 机制 | 适用 | |----|------|------| | L0 | 确定性探针（builtin 正则 / semgrep）经 ODA 门禁执行 | 事务内禁 RPC、空 catch、分层调用等可模式化硬规则 | | L1 | 可执行策略（rego / property 测试） | 金额用 BigDecimal、数据流约束 | | L2 | 注入审查 prompt，LLM 按清单审（默认） | 业务约定、缓存策略等语义规则 | | L3 | 人工确认（must_confirm 硬停） | 架构选型、支付通道等关键决策 |

L0/L1 需旁挂探针文件（probe + probe_path），依赖缺失会硬失败（doctor 预检 + 运行时 fail，不降级）。详见 docs/项目规则分层写法指南.md。

目录约定

.soloforge/knowledge/
  domain/                → 业务领域规则
  procedures/            → 自定义流程
  checklists/            → 验收清单
  review_rules/          → 审查规则
  patterns/              → 可复用模式（core/ temp/）
  rules/ artifacts/      → 阶段规则 / 产物模板
  drafts/                → sf_knowledge action=add 默认输出

⚠️ 不要和内置模板同名（如 procedures/功能开发流程.md 会被当篡改拒绝）；已有文件不会被覆盖；triggers 决定命中率，写宽些（含中英文同义词）。

自定义软/硬下限

除了上面的知识注入（verification_layer），你还可以在 .soloforge/knowledge/ 放带 kind 的 md，SoloForge 自动按 kind 做成软/硬下限：

| kind | 自动成为 | 怎么用 | |------|---------|--------| | guidance | 软下限（注入 prompt）| frontmatter 加 kind: guidance + triggers，triggers 匹配 intent 时注入 | | enforced | 硬下限（门禁阻断）| frontmatter 加 kind: enforced + gate + checks，按 check.gate 聚合执行 | | artifact | 产物模板 | frontmatter 加 kind: artifact + artifact_contract 块（domain/artifact_kind/path_pattern/gate/required），并入 contract（AI 可选 target 产出）|

内置优先：同 id/kind 用户资产不覆盖内置。全局级放 ~/.soloforge/patterns/。详见 docs/frontmatter字段字典.md 用户自定义资产节。

📐 设计产物目录

SoloForge 用固定的 docs/ + 工程目录 + deploy/ 结构管理产物，每个产物有明确位置、上下游依赖和 scope 条件（由 task.scope 决定是否产出）。条件产物仅在勾选对应 scope 维度时产出，未勾选则跳过。

docs/
├── context/              需求分析.md（需求文档）· 原型素材（html/图片/源码包）
├── analyze/              {端}/pages/{页}-原型说明.md（多端多页：端级 + 页级两层）
├── architecture/         01-架构设计文档.md · 02-开发切片计划.md
├── design/               01-数据库设计文档.md（+ schema.sql）· 02-API接口规格文档.md
├── build/                测试计划.md
├── audits/               02-代码审查报告.md · 03-测试报告.md · 04-发布说明.md
├── existing-system/      现有系统分析（brownfield 老系统改造专属）
└── api/                  openapi.yaml（API 规格 companion）
工程目录/                  代码（如 backend/、frontend/{端}/、shared/；单工程可为 src/）
deploy/                   部署配置.md · docker-compose.yml · nginx.conf（存在前端端时）

| 域 | 产物 | 路径 | scope 条件 | 依赖 | |----|------|------|-----------|------| | design | 需求分析 | docs/context/需求分析.md | — | — | | design | 原型说明 | docs/analyze/{端}/pages/{页}-原型说明.md | scope:frontend | 需求 + 原型素材 | | design | 架构设计 | docs/architecture/01-架构设计文档.md | — | 需求 + 原型{frontend} | | design | 数据库设计 | docs/design/01-数据库设计文档.md | scope:persistence | 架构 | | design | API 规格 | docs/design/02-API接口规格文档.md | scope:api | 架构 + 数据库{persistence} | | design | 开发切片计划 | docs/architecture/02-开发切片计划.md | — | 架构 + 数据库{persistence} + API{api} | | build | 代码 | src/ 或多工程目录（如 backend/、frontend/{端}/、shared/）| — | design 域上游 | | build | 测试计划 | docs/build/测试计划.md | scope:code | design 域上游 | | verify | 代码审查报告 | docs/audits/02-代码审查报告.md | — | code + design 域上游 | | verify | 测试报告 | docs/audits/03-测试报告.md | scope:code | code + 测试计划{code} | | operate | 部署配置 | deploy/部署配置.md | — | 审查报告 + code + 测试报告{code} | | operate | 发布说明 | docs/audits/04-发布说明.md | — | 部署配置 |

task.scope（布尔集 {frontend, persistence, api, code}）在任务启动后第零步通过 sf_work action=deliberate target=scope 与用户研讨确定；勾选的维度决定哪些条件产物产出。域内验证时按路径查上游产物，缺失返回 missing_upstream 并提示模板。

SoloForge 怎么区分前端、后端、共享库

SoloForge 会先找明确声明，再从设计文档里推断，最后才用项目文件兜底：

1. 你在 intent.yaml 的 projects 里声明了工程目录时，SoloForge 直接以它为准。每个工程可以标 kind: frontend-end | backend | shared，以及 deployable: true | false。
2. 从 0 到 1 做新系统时，架构文档会写清楚：§6.3 的前端端模块表表示各前端工程，FE-shared 表示共享库；§6.2 的后端工程目录表示后端工程。
3. 老系统或已有代码库里，如果没有 intent.yaml，SoloForge 会优先读已有设计文档；还不够时再按目录名、技术栈文件和源码根做保守推断。

这个区分会影响三件事：AI 能写哪些目录、每个工程是否必须有自己的 src/ 和 .gitignore、部署时哪些工程要有 Dockerfile。shared 是共享库，不单独部署；frontend-end 和 backend 默认是可部署工程。

部署约定是：deploy/ 只放编排文件和反代配置；每个可部署工程的 Dockerfile 放在自己的工程目录里，例如 backend/Dockerfile、frontend/admin-portal/Dockerfile。有前端端时需要 deploy/nginx.conf；纯后端项目不需要 nginx。

✅ 验证与交付

• 验证计划 ≠ 验证结果 — SoloForge 生成验证命令但不执行。只有真实执行并录入结果才算通过。
• 未验证不交付 — 交付前必须真实执行的验证结果。计划、构造记录、未执行的验证都不触发交付。
• 证据必须完整 — 每条验证结果含结构化执行证据（证据 ID、证据等级 E0-E3、时间戳）且覆盖全部 changed_files。
• 交付需显式触发 — 交付就绪检查只判断"能不能交付"，不自动 commit/push/建 PR。验收接受必须有可审计的用户确认，不能由 AI 自标已接受。

失败处理：确定性失败不无限重试（升级人工）；可修复失败有重试上限（超限升级人工）；scope 不足请求扩大不越权；错误信息自动脱敏。

🛡️ 安全护栏

运行时强制护栏（不降级、不关闭；误判可通过配置覆盖解除）：

| 护栏 | 作用 | |------|------| | 只读保护 | 分析/文档类任务不能改源码 | | 写入 scope 保护 | 代码修改只能在声明的 scope 路径内 | | 状态保护 | 已失败任务不能直接标完成 | | 并发保护（advisory） | 写前 CAS 归属校验（diff_ownership），检测并发写入冲突并标记需确认 | | 隐私保护 | 密钥、凭证、个人信息存储前脱敏 |

🖥️ CLI 与 MCP 工具

CLI 命令（仅接入与诊断）

soloforge                                # 启动 MCP server（默认）
soloforge mcp                            # 启动 MCP server
soloforge init [--adapter] [--dry-run] [--force]   # 一键接入（仅新项目首次）
soloforge doctor [--json]                # 诊断控制面/状态可信/恢复路径
soloforge --version | --help

MCP 工具（AI 通过 MCP 自动调用，共 8 个）

| 工具 | action | 职责 | |------|--------|------| | sf_task | start / query / cancel / confirm_decisions / reset | 任务生命周期：启动、查下一步、取消、逐域确认架构决策、解锁重试锁定任务 | | sf_work | observe / deliberate / act / verify / verify_slice / adversarial_review | 能力域工作（需传 domain）：看状态、产出前条件研讨、拿执行 prompt、跑域内验证、切片级验证、对抗审查（per-artifact / cross-artifact，首次 K=3、内容变更差量重审 K=1 独立采样取交集） | | sf_knowledge | audit / add / update | 知识库：审计规则可消费性、新增、更新 | | sf_gate | —（参数 domain + gate_name + artifact_path） | 独立门禁审查（OOD/SOLID、抽象缺失、风险模式等） | | sf_waiver | waive / list / remove | 门禁豁免逃生通道：对误报门禁申请豁免、列出活跃豁免、移除（NON_WAIVABLE 硬规则不可豁免） | | sf_scaffold | —（参数 task_id） | 脚手架生成（不匹配技术栈时不 fallback） | | sf_analyze | —（参数 view） | 上下文引擎视图：file_impact / reference_trace / dependency_graph / change_impact / coverage_gap / knowledge_ref | | sf_doctor | —（参数 check_type） | MCP 诊断：check_type = state / gates / scope / full |

工具契约：每个工具有对应 invocation contract，启动时覆盖预检——已注册必须有契约，契约必须有实现，避免工具与门禁各说各话。

❓ 常见问题

设计行为。init 只做接入，不推断项目规划。intent.yaml 是 AI 连上 MCP 后通过对话补充的可选偏好文件。技术栈由项目文件自动探测。

检查配置文件是否生成，重启 AI 工具：

• Claude Code：.mcp.json / .claude/settings.json / CLAUDE.md

再跑 soloforge doctor 按恢复路径处理。不建议手动删 .soloforge/state。

soloforge doctor    # 查看缺失项与恢复路径

旧项目优先用 doctor 和 MCP 工具维护；只有新项目首次接入才跑 soloforge init。

Cursor 暂无内置适配器。先 soloforge init 生成 .mcp.json，再手动复制到 .cursor/mcp.json：

{
  "mcpServers": {
    "soloforge": {
      "command": "soloforge",
      "args": ["mcp"],
      "env": { "SOLOFORGE_PROJECT": "/absolute/path/to/my-project" }
    }
  }
}

保存后重载 Cursor 窗口。

全局卸载：npm uninstall -g soloforge。项目内文件手动删：.soloforge/ / .mcp.json / .claude/ / CLAUDE.md / redocly.yaml（删 CLAUDE.md 前确认无手写内容）。

🛠️ 贡献与本仓库开发

日常开发

npm install
npm run build        # clean build（rm -rf dist + tsc + chmod +x dist/index.js）
npm test             # 全量 vitest 测试

常用脚本

| 脚本 | 用途 | |------|------| | npm run build | clean build | | npm run dev | tsc --watch 增量编译 | | npm run clean | 清理 dist/ | | npm test | 全量测试 | | npm run test:e2e | 端到端测试（需 E2E=1） | | npm run typecheck | tsc --noEmit | | npm run typecheck:tests | 测试文件类型检查 | | npm run lint | eslint（仅 src/） | | npm run lint:all | eslint 全项目零警告 | | npm run check:comments | 中文注释防回归 | | npm run check:schema-enum | Schema 枚举一致性 | | npm run check:runtime-recovery | 运行时态自救闭环校验 | | npm run validate-release | 15 phase 发布门禁 |

发布前验收

维护者发布前必须依次执行，全绿才能进 Release Candidate：

npm run build && npm run lint:all       # 1. 编译 + 类型 + lint
npm test                                # 2. 全量测试
npm run check:comments                  # 3. 中文注释防回归
npm run check:schema-enum               # 4. 枚举一致性
npm run check:runtime-recovery          # 5. 运行态自救
npm run validate-release                # 6. 15 phase 发布门禁（全 PASS / 0 hard_fail）
npx madge --circular --extensions ts src/   # 7. 循环依赖检查

# 8. 用户项目可用性抽查
REPO_DIR=$(pwd); TMPDIR=$(mktemp -d) && cd "$TMPDIR"
node "$REPO_DIR/dist/index.js" init
node "$REPO_DIR/dist/index.js" doctor   # exit code 都必须为 0
cd "$REPO_DIR"

1. dist 旧产物风险 · 2. 主链路真实消费 · 3. 依赖漏洞扫描 · 4. TypeScript 编译检查 · 5. 关键问题消费验证 · 6. MCP 控制面可信与受控生成链路 · 7. 模板卫生与项目知识消费 · 8. 工作流导航契约行为验证 · 9. npm pack 验证 · 10. 资产防膨胀审计 · 11. 发布问题场景矩阵 · 12. 候选版本排序与回滚路径验证 · 13. 代码质量门禁 · 14. 架构边界回归 · 15. 模板消费覆盖率

另有入口预检「运行时态自救闭环」（check:runtime-recovery）在 15 phase 之前执行，不属于 15 phase 之一。

代码质量基线：tsc 零错误 ｜ 全量测试零失败 ｜ eslint 零警告 ｜ 零循环依赖 ｜ 中文注释零回归 ｜ noUnusedLocals + noUnusedParameters 已启用。

文档导航

| 你想做什么 | 看哪个文档 | 类型 | |-----------|-----------|------| | 5 分钟跑起来 | 本 README 的「快速开始」 | 快速入门 | | 学怎么完成一次完整交付 | docs/SoloForge-开发者操作手册.md | How-to（做）| | 贡献一个模板资产 | templates/shared/模版贡献指南.md | How-to（做）| | 理解为什么这样设计 | docs/SoloForge-设计文档.md | Explanation（懂）| | 查代码必须遵守什么规则 | docs/SoloForge-架构范式契约.md | Reference（查）| | 发布前要验收什么 | docs/正式发布门槛.md | Reference（查）|

原则：想做事看 How-to，想理解看 Explanation，查规则看 Reference。一个文档只承担一种主要职能，避免既教操作又讲原理导致的混乱。

📄 许可证

MIT © SoloForge Team