SoloForge

AI 编程助手的项目工作流配置器。SoloForge 帮你把 Claude Code、Codex App、Trae IDE 接入同一套项目规则、知识模板和验证习惯，让 AI 在你的项目里更少误判、更少乱写、更容易交付可检查的结果。

适合谁

• 你已经在用 Claude Code、Codex App 或 Trae IDE 写代码。
• 你希望每个项目都有稳定的 AI 工作流规则，而不是每次从零解释。
• 你希望 AI 修改代码前先理解项目边界，生成产物时不要误改源码。
• 你希望配置可以自动推断，但不要在低置信度时乱写项目配置。

最短成功路径

# 1. 全局安装
npm install -g soloforge

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

# 3. 预检：查看 SoloForge 会识别出什么，不写入配置
soloforge init --auto --dry-run

# 4. 初始化项目
soloforge init --auto

# 5. 重新打开你的 AI 工具，让它加载新配置
# Claude Code: 退出后在项目目录重新启动 claude
# Codex App: 重新打开项目目录
# Trae IDE: 重新打开项目目录

# 6. 检查状态
soloforge validate
soloforge status

如果 init --auto 提示置信度不足，改用：

soloforge init --interactive

初始化方式

所有命令默认作用于当前目录。推荐先 cd 到项目根目录再执行。

soloforge init --auto --dry-run      # 只预览，不写入 config.yaml
soloforge init --auto                # 高置信度时生成项目配置和适配器文件
soloforge init                       # 生成目录、知识模板和适配器文件，不写 config.yaml
soloforge init --interactive         # 手动确认项目配置
soloforge init --adapter claude      # 只生成 Claude Code 配置
soloforge init --adapter codex       # 只生成 Codex App 配置
soloforge init --adapter trae        # 只生成 Trae IDE 配置
soloforge init --adapter all         # 同时生成所有适配器配置

config.yaml 是可选文件。没有它时，SoloForge 会根据 package.json、pom.xml、go.mod 等文件在运行时推断项目类型；只有高置信度或你手动确认时，才会把配置写入 .soloforge/config.yaml。

生成文件

| 位置 | 用途 | |------|------| | .soloforge/knowledge/ | 项目知识模板和规则 | | .soloforge/config.yaml | 可选项目配置，仅在高置信度或手动确认后生成 | | .claude/settings.json / CLAUDE.md / .mcp.json | Claude Code 配置 | | .codex/config.toml / .codex/hooks.json / AGENTS.md | Codex App 配置 | | .trae/mcp.json / .trae/rules/project_rules.md | Trae IDE 配置 |

SoloForge 不会覆盖已有知识文件。重新运行 soloforge init 可刷新适配器配置。

日常命令

soloforge validate          # 检查项目配置和知识文件
soloforge status            # 查看当前项目状态和配置来源
soloforge version           # 查看版本

更新 SoloForge 后，建议重新生成适配器配置：

npm update -g soloforge
cd /path/to/my-project
soloforge init

使用时你会看到什么

接入成功后，AI 助手会在合适的时候调用 SoloForge 来理解任务、生成执行上下文、给出验证建议和记录任务状态。对你来说，主要变化是：

• 写代码类任务会更明确 scope、验收项和验证命令。
• 生成文档、提取说明、分析日志等产物型任务会默认输出到 .soloforge/output/，不会默认修改 src/。
• 遇到缺少路径、源码包、日志等必需输入时，会先澄清，而不是猜着执行。
• 敏感信息、危险命令和高风险交付动作会更保守，需要你确认。

产物输出

文档、分析报告、源码包提取结果等非代码产物默认写入：

.soloforge/output/

例如让 AI “从 /tmp/prototype.zip 抓取原型说明”，SoloForge 会把它作为只读外部材料处理，要求产物写入 .soloforge/output/**，而不是修改项目源码。

Cursor 说明

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

soloforge init

示例：

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

保存后重载 Cursor 窗口。

常见问题

soloforge init --auto 没有生成 config.yaml

这是正常行为。SoloForge 只有在项目指纹足够明确时才会自动写配置。你可以继续使用运行时推断，也可以执行 soloforge init --interactive 手动确认。

AI 工具没有调用 SoloForge

先检查对应配置文件是否生成，然后重启或重载 AI 工具：

• Claude Code: .mcp.json、.claude/settings.json、CLAUDE.md
• Codex App: .codex/config.toml、.codex/hooks.json、AGENTS.md
• Trae IDE: .trae/mcp.json、.trae/rules/project_rules.md

想重新生成配置

soloforge init

该命令会刷新适配器配置，不会覆盖已有 .soloforge/config.yaml 和知识文件。

想清理项目中的 SoloForge 文件

全局卸载只会移除命令：

npm uninstall -g soloforge

项目内文件需要手动删除：

.soloforge/
.mcp.json
.claude/
CLAUDE.md
.codex/
AGENTS.md
.trae/

删除 CLAUDE.md 或 AGENTS.md 前请确认没有手写内容。

本仓库开发

npm install
npm run build
npm test

技术要求

• Node.js >= 18
• TypeScript / ESM
• 支持的 AI 编程工具（Claude Code / Codex App / Trae IDE）

许可证

MIT