UmaDev

给 AI 编码底座套一条治理轨道

从一句需求，到 PRD、架构、UI/UX、代码、质量门、交付包——底座写代码，UmaDev 管流程。

简体中文 | 繁體中文 | English

目录

• 简介 · 项目来源 · 它解决什么问题
• 快速体验 · 一个完整例子 · UmaDev 如何工作
• 运行模式 · 流水线设计 · 质量门是什么
• 治理规则是什么 · 知识库是什么 · 交付产物长什么样
• 命令大全 · 配置 · Rust 架构 · 开发

简介

UmaDev 是一个本地运行的确定性壳：它给你已经登录的 AI 编码底座（Claude Code / Codex / OpenCode）套上一条治理轨道，把"AI 写代码"约束成一个可检查、可恢复、可审计的交付流程。它不替代这些底座，也不卖模型 API——脑子始终在底座，UmaDev 只管流程、规则和证据。

1. 把你的需求拆成完整交付流程：先澄清，再调研，再写 PRD、架构、UI/UX，再实现前后端，最后跑质量门和交付。
2. 驱动你已经登录的 AI 编码工具：Claude Code / Codex / OpenCode 负责真实写代码，UmaDev 负责让它们按流程做事——一等支持恰好这三个底座；想覆盖更多模型，是把底座路由到第三方/本地模型，那是底座自己的事，不是 UmaDev 加新驱动。
3. 把交付过程变成可检查、可恢复、可审计：每个阶段有产物，每次工具调用有记录，最后有 quality gate、compliance mapping 和 proof pack。

如果普通 AI 编码工具像一个很强的工程师，那么 UmaDev 更像围着它的一圈流程与审稿岗位——产品经理、架构师、UI/UX 审稿人、技术负责人、QA、交付经理的检查清单，而不是一个能取代工程师的全自动总监。最终判断和代码仍来自底座，UmaDev 负责让这个过程不跑偏、留下证据。

定位与成熟度：UmaDev 仍处于早期、治理优先阶段，最适合在真实项目上验证它的流程与门禁。它把价值押在"轨道"上，而不是声称已经能无人值守地全自动交付。

项目来源

UmaDev 脱胎于原项目 shangyankeji/super-dev。

早期的 super-dev 更像一个 AI 编码治理工具：它主要关注“AI 生成代码时不能写什么”，例如不要用 emoji 当图标、不要硬编码颜色、不要写不安全代码。

现在的 UmaDev 在这之上扩成了一条完整的治理轨道：

• 从单点治理扩展到全流程治理：不只检查代码，而是把从需求到交付的每个阶段都纳入流程和门禁。
• 从零散脚本升级为规范驱动系统：核心是 UMADEV_HOST_SPEC_V1，所有实现都围绕规范。
• 使用 Rust 重写：单二进制、跨平台、启动快、依赖少、适合本地长期运行。
• 从“拦截问题”扩展到“带着底座走完流程”：Claude Code / Codex / OpenCode 是大脑和手，UmaDev 是包在外面的流程与治理轨道。

一句话概括这个演进：

super-dev 关注“AI 不要写烂代码”；UmaDev 关注“AI 如何交付一个完整、可上线、可审计的商业项目”。

它解决什么问题

很多人第一次用 AI 编码工具时都会遇到类似问题：

• AI 一上来就写代码，没有 PRD、没有架构、没有验收标准。
• 前端做完了，后端接口路径对不上。
• UI 看起来像模板，颜色和字体很随意。
• AI 写了占位代码、假数据、TODO，却说“完成了”。
• 修改一次需求后，上下文开始乱，前面约定被忘掉。
• 代码能生成，但没有质量报告、没有证据链，不知道能不能交付。
• 团队有自己的规范和知识库，但每次都要手动复制给 AI。

UmaDev 的目标就是把这些问题系统化解决。

它会强制 AI 走一条更像真实团队的流程：

flowchart LR
    A["一句需求"] --> B["澄清问题"]
    B --> C["调研"]
    C --> D["PRD / 架构 / UIUX"]
    D --> E["执行计划"]
    E --> F["前端实现"]
    F --> G["预览确认"]
    G --> H["后端实现"]
    H --> I["质量门"]
    I --> J["交付包"]

快速体验

1. 安装

推荐用 npm 安装预编译二进制：

npm install -g umadev

npm 只是分发壳。真正运行的是 Rust 编译出的 umadev 二进制。

支持的平台：

• macOS Apple Silicon
• macOS Intel
• Linux x86_64
• Linux ARM64
• Windows x86_64

也可以从源码构建：

git clone https://github.com/umacloud/umadev.git
cd umadev
cargo build --release
./target/release/umadev --version

2. 准备一个 AI 编码底座

UmaDev 推荐驱动你已经登录的 CLI：

# 三选一即可
npm install -g @anthropic-ai/claude-code
npm install -g @openai/codex
npm install -g opencode-ai

然后按这些工具自己的方式登录。

UmaDev 不保存你的 Claude / Codex / OpenCode 登录信息。它只是把任务作为非交互命令发给它们。

3. 初始化项目

cd your-project
umadev init

这一步会写入一些项目配置：

umadev.yaml              # 声明这是一个 UmaDev 管理的项目
.umadevrc               # 项目级配置
.umadev/rules.toml      # 治理规则配置
CLAUDE.md               # 给 Claude Code 看的项目说明
.gitignore              # 忽略 UmaDev 运行产物
knowledge/              # 项目内知识库和设计系统种子

4. 启动

umadev

第一次打开会让你选择：

1. 界面语言。
2. 使用哪个底座：Claude Code、Codex 或 OpenCode（你已经登录的那个）。

之后直接输入需求：

做一个面向独立开发者的 SaaS 订阅管理后台，包含登录、订阅计划、账单记录和管理员仪表盘。

UmaDev 会开始组织完整流程。

5. 预览和交付

前端阶段完成后：

/preview

交付阶段完成后：

/deploy

最终交付证据会在：

output/
release/
.umadev/audit/

其中最重要的是：

release/proof-pack-<project>-<time>.zip
release/scorecard-<project>-<time>.html

这两个文件就是给团队、客户或审计方看的交付证明。

一个完整例子

假设你在一个空项目里运行：

umadev init
umadev

然后输入：

做一个课程预约小程序，用户可以查看课程、选择时间、预约、取消预约，管理员可以管理课程和预约记录。

UmaDev 会做这些事：

1. 理清需求：补全目标平台、是否需要支付、管理员后台复杂度等合理默认假设（自动模式下自动推进、不打断你；手动模式可逐条确认）。
2. 联网调研：当底座具备联网能力时，搜索同类小程序 / 预约系统的竞品功能、定价、设计趋势和真实用户评价；同时检索内置知识库里的预约系统、后台 CRUD、权限、表单校验等规范。两者合并产出调研报告 output/<slug>-research.md。
3. 生成 PRD，明确用户角色、功能范围、EARS 可测验收标准。
4. 生成架构文档，定义数据模型、API、鉴权、部署方式。
5. 生成 UI/UX 文档，定义设计方向、颜色 token、字体、组件状态、图标库。
6. 拆成执行计划和任务（每个任务回链到需求 FR 编号）。
7. 驱动底座实现前端。
8. 暂停让你预览。
9. 驱动底座实现后端和集成。
10. 跑质量门：文档、契约、构建、设计、安全、交付文件全部检查。
11. 生成交付包和成绩单。

整个过程不是“AI 聊完就算完成”，而是会留下真实文件。

UmaDev 如何工作

整体架构可以理解成四层：

flowchart TB
    User["用户<br/>输入需求 / 审核 / 预览 / 部署"] --> UI["UmaDev TUI / CLI<br/>聊天界面 + 命令入口"]

    UI --> Director["umadev-agent<br/>流程引擎：阶段、gate、状态、质量门"]

    Director --> Spec["umadev-spec<br/>UMADEV_HOST_SPEC_V1"]
    Director --> Knowledge["umadev-knowledge<br/>本地知识库检索：BM25 + 向量"]
    Director --> Governance["umadev-governance<br/>112 条治理规则 + 审计"]
    Director --> Contract["umadev-contract<br/>OpenAPI 契约校验"]

    Director --> Runtime["umadev-runtime<br/>统一 Runtime 接口"]
    Runtime --> Host["umadev-host<br/>驱动底座 Claude / Codex / OpenCode<br/>实现代码 · 联网调研竞品"]
    Runtime --> Offline["离线模板<br/>内部 CI / 无底座兜底"]

    Host --> Workspace["项目工作区<br/>源码 / output / release"]
    Offline --> Workspace

    Governance --> Evidence[".umadev/audit<br/>审计日志"]
    Contract --> Quality["quality gate"]
    Evidence --> Quality
    Quality --> Release["proof pack<br/>scorecard"]

更简单地说：

• TUI/CLI：你和 UmaDev 交流的地方。
• Agent Runner：决定现在该做哪个阶段、什么时候暂停、什么时候继续。
• Research（第 1 阶段）：先让底座联网调研同类产品 / 竞品 / 趋势 / 真实评价，叠加本地知识库，产出 research.md——不是上来就写代码。
• Runtime / 底座：把任务交给你登录的底座（Claude Code / Codex / OpenCode）——底座用它自己的登录和模型，既负责写真实代码，也负责联网调研竞品；UmaDev 不注入、不覆盖任何模型或 key。
• Governance/Quality：检查 AI 写出来的东西是否符合规范。
• Knowledge：把工程标准、设计系统、领域知识（本地 BM25 + 向量检索）注入给底座。
• Evidence：把过程记录下来，最后打包交付。

运行模式

模式 A：驱动本机 AI 编码 CLI

这是推荐模式。

特点：

• UmaDev 不需要你的模型 API key。
• 继续使用你原来 CLI 的账号、订阅和配置。
• 底座负责真实读写文件和运行命令。
• UmaDev 负责流程、规则、质量门和证据链。

底座自带模型 —— UmaDev 不接外部 API

UmaDev 不自带模型，也不接第三方 API —— 底座用它自己的模型（你订阅登录的，或你给底座自己配的第三方 / 本地模型）。选底座时 UmaDev 会读出并显示它当前用的模型和思考强度（/status 也能看），但绝不覆盖：运行时默认不传 --model，底座用它自己的；想换就改底座自己的配置，或用 /model <id> 临时覆盖这一会话。

UmaDev 读取的来源：claude 的 ~/.claude/settings.json（model / effortLevel）、codex 的 ~/.codex/config.toml（model / model_reasoning_effort）、opencode 的 opencode.json（model，思考强度内置在模型变体里）。

模式 B：离线模板（内部兜底，不是产品）

/offline

离线模式不会调用任何模型，也不会访问网络。它不是一个让你选的产品形态——产品永远是"驱动你登录的底座"。离线模板只是没有底座可用时的确定性兜底，适合：

• 快速看文件结构。
• CI smoke test。
• 演示 UmaDev 的流程。

离线产物只是模板（带 TODO 占位），不代表模型完成了真实开发；真实交付必须走底座。第一次启动的底座选择器也只列这三个底座，不会把离线当成一个选项。

流水线设计

规范主链是 9 个阶段：

flowchart LR
    R["research<br/>调研"] --> D["docs<br/>PRD / 架构 / UIUX"]
    D --> G1["docs_confirm<br/>文档确认"]
    G1 --> S["spec<br/>执行计划"]
    S --> F["frontend<br/>前端"]
    F --> G2["preview_confirm<br/>预览确认"]
    G2 --> B["backend<br/>后端"]
    B --> Q["quality<br/>质量门"]
    Q --> L["delivery<br/>交付"]

当前产品实现还在主链前增加了一个 clarify 微阶段：

flowchart LR
    C["clarify<br/>澄清需求"] --> R["research<br/>调研"]
    R --> D["docs"]
    D --> Rest["...后续 7 个规范阶段"]

所以你可能先看到 UmaDev 生成：

output/<slug>-clarify.md

你可以回答澄清问题，也可以输入 c 跳过。

小任务有轻量路径：9 阶段是面向"完整商业级交付"的主链，不是每个需求都得全程走完。用 /kind（全栈 / 仅前端 / 仅后端 / bugfix / 重构）声明任务类型后，UmaDev 会据此裁剪阶段——bugfix、小改动不会强行拉你走 PRD/架构/UIUX 全套。

每个阶段会产出什么

质量门是什么

质量门可以理解成 UmaDev 的“交付前验收”。

它不是简单看文件在不在，而是会检查：

• PRD 有没有目标、范围、验收标准。
• 架构文档有没有 API、数据模型、错误处理、鉴权。
• UI/UX 文档有没有设计 token、字体、图标库、组件状态、暗黑模式。
• 前端调用的 API 和后端契约是否一致。
• 是否存在 emoji 图标、硬编码颜色、AI 模板痕迹。
• 是否有构建、测试、lint、typecheck 结果。
• 是否生成 Dockerfile、CI、migration、.env.example。
• 是否泄露 API key、密码、连接串。
• 是否有审计日志和合规映射。

输出文件：

output/<slug>-quality-gate.json
output/<slug>-quality-gate.md

默认通过线是 90 分，可以在 .umadevrc 调整：

[quality]
threshold = 90
skip_checks = []

治理规则是什么

UmaDev 最早来自治理工具，这部分仍然是核心能力。

这些规则是一条治理基线，不是绝对真理——每条都可以在 .umadev/rules.toml 里禁用、按路径排除或调参（见下文）。它们的作用是给底座的产出兜底，而不是替你做最终的工程判断。

规范层有 25 条 clause，实现层目前有 112 条规则，覆盖：

• UI 质量：不用 emoji 当图标，不写硬编码色，不产出模板感 UI。
• 安全：不写密钥，不写危险命令，不写 SQL 注入、SSRF、XXE 等危险代码。
• 前端质量：不用随意 any、裸 fetch、缺少 a11y、缺少 ErrorBoundary 等。
• 后端质量：鉴权、限流、日志、事务、输入校验、错误处理。
• 多语言危险模式：Rust unwrap、Go panic、Python bare except、Java System.exit 等。

治理入口有四个：

flowchart LR
    A["Claude Code hook<br/>写入前拦截"] --> G["umadev-governance"]
    B["umadev ci<br/>提交前/CI 扫描"] --> G
    C["MCP server<br/>给其他 AI 工具调用"] --> G
    D["quality gate<br/>交付前补扫"] --> G

项目可以通过 .umadev/rules.toml 调整：

[disabled]
clauses = []

[exclusions]
paths = ["src/legacy/**", "**/*.test.ts"]

[extra]
blocked_domains = ["internal-bad-proxy.corp"]