核心用法
Soulforge 是一款专为高信噪比自主编码循环设计的 CLI 工具，核心定位为「操作手册」而非通用文档。它提供三种首选工作流：
- feature-dev：端到端功能交付，从需求分析到 PR 创建
- bugfix：诊断优先的精准修复模式
- review-loop：对现有 PR 进行审查-修复闭环迭代
关键使用范式包括：必须在隔离工作树中运行（<repo>/worktrees/ 为默认基准），禁止在主代码库直接执行；通过 --callback-exec 接收异步状态回调；采用结构化完成机制（soulforge complete）替代旧的 approve/reject 模型。
典型命令模式强调显式约束——需指定工作目录、通过回调接入通知渠道（如 Slack）、并用自然语言精确限定 scope 与禁止事项。
显著优点
严格隔离与安全性：强制工作树隔离 + 主分支运行拦截，杜绝污染生产代码的风险；脏工作树拒绝启动、越界工作目录需显式覆盖，形成多层防护。
高质量信号设计：审查门控（review gate）机制强制在关键节点进行人工质量确认，配合「FIX vs SEPARATE」的严格分流策略，有效遏制范围蔓延。
异步友好架构：回调驱动模式适配长时运行场景，支持 CI/CD 集成与团队通知管道对接。
迭代可控：通过 .soulforge-progress.md 状态文件支持跨运行断点续传，max_loops 限制后的 fresh run 机制防止无限循环。
潜在局限
学习曲线陡峭：需理解工作树 Git 模型、回调模板变量、checkpoint 状态机等多层抽象，新手易将本 skill 误作通用文档而非执行手册。
人工门控依赖：review gate 要求操作者具备严格的 scope 纪律，「while we're here」式漂移仍可能人为引入。
工具链耦合：依赖 soulforge 二进制、codex、gh 等外部工具，环境配置成本较高。
长时运行摩擦：重构类任务的自然耗时可能被误判为异常，需要操作者心态调整（质量控于门控，而非打断执行）。
适合人群
- 需高频交付功能分支的中大型开发团队
- 已建立 PR 审查文化、追求自动化与质量平衡的技术组织
- 熟悉 Git 工作树、CLI 工作流的高级开发者与 DevOps 工程师
- 需要异步追踪长时任务状态的项目管理者
常规风险
范围管理失控：重复 review-fix 循环中若未严格执行 SEPARATE 策略，易导致 PR 膨胀。
状态文件冲突：多成员共享 .soulforge-progress.md 可能引发并发覆盖。
回调配置错误：模板变量拼写或 exec 字符串转义问题可能导致静默通知失败。
隔离失效：--workdir 显式覆盖或 bare+worktree 边缘场景若配置不当，可能突破主分支保护。
max_loops 边界：达到循环上限后若未正确触发 fresh run，可能造成 PR 悬停。