AI 编程 Agent 写出面条式代码？用 Unspaghettit 的行为规范拿回控制权
你的 AI 编程助手是不是也开始「失控」了？一开始它很听话，但随着项目膨胀，每次修改都像在走钢丝——改一行代码就崩三处功能，prompt 里塞满了历史上下文，却仍然记不住关键的约束条件。这不是你的 prompt 写得不够好，而是你的 AI 助缺少一个可执行的规范契约。
Unspaghettit 就是为这个问题而生的开源工具。它让你和 AI 之间共享一个可执行的行为规范（executable specification），通过 MCP 协议将项目意图结构化为可验证的模型，让每一次代码生成都基于明确的规则而非模糊的记忆。
为什么你需要行为规范？
目前主流的 AI 编码工作流是「prompt-in, code-out」：你写好 prompt，LLM 生成代码。但问题在于：
- Prompts 是一次性的，每次对话都会被遗忘
- 项目意图和约束只能靠人工记忆或写在 README 里
- 多人协作时，不同 Agent 对同一功能的理解可能完全不同
- 生成的代码容易偏离设计意图，形成所谓的「prompt spaghetti」
Unspaghettit 提供了一种完全不同的思路：以规范为真相来源（spec as source of truth），AI 和人类都参考同一套结构化规范工作，prompt 变成了一次性的「任务描述」而非核心知识库。
Unspaghettit 的核心概念
规范即代码
Unspaghettit 将产品行为建模为一系列结构化实体：
- Feature（功能）：产品的一个独立能力模块
- Surface（界面）：功能对外的交互入口（CLI 命令、API 端点、UI 组件）
- Action（动作）：用户或系统可执行的具体操作
- State（状态）：系统在某一时刻的快照
- Rule（规则）：约束状态转换的业务逻辑
- Scenario（场景）：一个完整的行为路径，附带预期结果——可直接执行的断言
每个 Scenario 都是一个可执行断言。run_all_scenarios 在模拟器中运行全部场景并报告通过/失败——也就是说，你在写一行代码之前就可以验证规范的一致性。
MCP 原生集成
Unspaghettit 的核心是一个 MCP 服务器，支持在其规范模型上进行创建、读取、编辑和验证。任何支持 MCP 的 AI 工具都可以直接使用：
- Claude Desktop / Claude Code
- Cursor
- Gemini
- Windsurf / Kiro
- Codex
安装完成后，直接对你的 AI 说：
>”Using the Unspaghettit MCP, create a new project. Model the first feature and make it implementation-ready.”
AI 就会通过 MCP 调用在规范的框架下工作。
快速上手
安装
npm install -g unspaghettit cd your-project unspa init unspa dashboard
unspa init 会自动配置 MCP 服务器到你已安装的 AI 客户端。unspa dashboard 在 http://localhost:3000 启动一个可视化面板，你可以在面板中实时观察 AI 对规范的修改。新用户建议先打开 /tutorial 完成从 Project → Feature → Surface → Action → Rule → Simulator 的完整教学。
定义第一个 Feature
安装后，你可以让 AI 帮你建模一个功能。例如，创建一个「用户注册」功能：
Feature: 用户注册
Surface: register API
Action: registerUser
Parameters: email, password, name
State before: { user: null }
State after: { user: { email, name, status: "pending" } }
Rule: email 格式必须合法
Rule: 密码至少 8 位，包含字母和数字
Scenario: 用合法信息注册 →
Given email="test@example.com", password="pass1234"
Result: user.status = "pending" ✓
AI 通过 MCP 工具调用就能完成这些建模。修改规范后，用 run_all_scenarios 验证一致性——如果在模拟器中场景通过，说明你的规范是自洽的。
Code → Spec：反向建模
更实用的场景是已有代码库。你可以让 AI 读现有项目，自动反向建模：
“Read this codebase and model its behavior into Unspaghettit. Show me which modules have gaps.”
AI 会扫描源码，生成 features、actions、scenarios，并用 maturity scoring 功能给每项打分——标出关键问题、缺失的规则、未覆盖的场景。这就像给你的项目照了一次 X 光。
实战场景一：用规范驱动新功能开发
你正在开发一个任务管理系统，需要新增「任务指派」功能。传统做法是写一个长长的 prompt 描述需求，然后让 AI 生成代码。但需求会变，prompt 会旧。
用 Unspaghettit 的流程是：
- 建模：让 AI 通过 MCP 创建
Feature: 任务指派，定义其 Surface、Action、Rule - 验证：运行
run_all_scenarios确认规范本身无误 - 生成类型：执行
generate_types，自动生成 TypeScript 的类型定义文件 - 实现：告诉 AI “implement the next thing”，AI 会从
implementation queue取下一个待实现项 - 审计：
maturity scoring报告实现覆盖率和缺口
整个过程，你的规范文件（纯 JSON 格式，可直接 Git 提交）记录了产品的当前意图，不会因为 AI 的上下文窗口刷新而丢失。
实战场景二：重构旧项目
项目中积累了大量「谁也不敢改」的历史代码？让 Unspaghettit 做一次逆向建模：
unspa init
score_feature 会输出结构化的改进建议——覆盖率最低的 surface、最危险的 rule 缺失。这就把「代码重构」从凭感觉变成了有据可查的工程决策。
团队协作优势
- 本地优先：所有规范文件都是 Git 版本化的 JSON，无需云服务
- 多 Agent 支持：内置 Yjs WebSocket 服务器，多个 LLM 和人可以实时编辑同一规范
- 可审计：
.unspa.json的 behavioral index 记录了每个实体的实现位置，变更历史可以追溯 - 可导出：项目导出为加密文件，支持带密码分享
什么时候该用？
Unspaghettit 最适合以下场景：
- 项目有明确的业务规则和状态转换（而非纯粹的 CRUD）
- 多个 AI Agent 或多人协作同一代码库
- AI 生成的代码频繁偏离预期，需要结构化约束
- 希望将产品意图从「对话记忆」沉淀为可版本化文档
不适合的场景：原型阶段快速验证、纯展示型页面开发、一次性脚本。
写在最后
AI 编码工具越来越强，但「如何告诉 AI 你想要什么」这件事本身还没被工具化。Unspaghettit 提供了一种看起来有点「重」但极其可靠的思路——你有规范，它可执行，AI 知道你在说什么。
如果你也厌倦了在 prompt 里反复描述同一条规则，不妨试试这种「面向规范开发」（Spec-Driven Development）的方式。项目开源（AGPL-3.0），MIT 许可证团队也可以直接 fork 使用。