知道何时过时的工程决策。

框定问题。公平比较选项。将决策记录为契约。知道何时需要重新审视。

支持：Claude Code, Cursor, Gemini CLI, Codex CLI, Codex App, Air

---

安装

curl -fsSL https://raw.githubusercontent.com/m0n0x41d/quint-code/main/install.sh | bash

然后在您的项目中，运行 init 并带上您所用工具的标志（flag）：

# Claude Code (default if no flag)
quint-code init

# Cursor
quint-code init --cursor

# Gemini CLI
quint-code init --gemini

# Codex CLI / Codex App
quint-code init --codex

# JetBrains Air
quint-code init --air

# All tools at once
quint-code init --all

各工具的初始化操作

二进制文件相同 —— 仅 MCP（Model Context Protocol）配置位置不同：

工具	MCP 配置	命令	技能
Claude Code	.mcp.json (project root)	~/.claude/commands/	~/.claude/skills/q-reason/
Cursor	.cursor/mcp.json	~/.cursor/commands/	~/.cursor/skills/q-reason/
Gemini CLI	~/.gemini/settings.json	~/.gemini/commands/	—
Codex CLI	.codex/config.toml	~/.codex/prompts/	~/.agents/skills/q-reason/
Air	.codex/config.toml	project skills/	project skills/q-reason/

Cursor 重要提示： 初始化后，打开 Cursor 设置 → MCP → 找到 quint-code → 启用开关。Cursor 默认会禁用 MCP 服务器。

注意： Cursor 也会从 ~/.claude/commands/ 读取 Claude Code 命令 —— 因此即使没有 --cursor，斜杠命令也能工作。但必须设置 MCP 配置 (.cursor/mcp.json) 才能让工具连接。

已有项目？在初始化后运行 /q-onboard —— 代理（Agent）会扫描您的代码库以捕获值得记录的现有决策。

第一次使用？ 让代理解释其工作原理：

/q-reason explain how to work with quint-code effectively — what commands exist, when to use each one, and what's the recommended workflow

该代理完全了解所有 Quint 工具，并将结合您的项目上下文引导您使用它们。

---

工作原理

一个命令：/q-reason

描述您的问题。代理会框定它、生成替代方案、公平比较它们并记录决策 —— 所有这些都在一个命令中完成。它会自动选择合适的深度。

或者手动驱动每一步

/q-frame  → /q-char  → /q-explore → /q-compare → /q-decide
  what's      what       genuinely     fair         engineering
  broken?     matters?   different     comparison   contract
                         options

即时微决策

当代理在对话中注意到决策时，会自动捕获它们。没有理由 —— 就没有记录。与活跃决策的冲突会被标记。90 天后自动过期。

当决策过时

/q-status 显示哪些已过期以及需要注意的内容。/q-refresh 管理所有工件（Artifact）类型的生命周期 —— 豁免、重新打开、取代或弃用。

---

有何不同

• 决策是实时的 —— 它们拥有计算得出的信任分数（R_eff），会随着证据老化而降低。过期的基准测试会降低整体分数。
• 比较是诚实的 —— 强制执行对等性，交叉检查维度，警告不对称评分。反古德哈特效应（Anti-Goodhart）：将维度标记为“观察”，以防止优化错误的指标。
• 跨会话记忆 —— 当您框定问题时，工具会浮现相关的过往决策。当您探索时，它会检查是否存在类似的变体。
• 闭环 —— 失败的测量建议重新打开。证据衰减触发审查。定期刷新提示确保没有任何内容静默过时。
• 决策即契约 —— FPF E.9 格式：问题框架、决策（不变量 + DO/DON'T）、理由、后果。新工程师六个月后阅读它也能完全理解。

---

6 个工具

工具	功能
quint_note	带验证和自动过期的微决策
quint_problem	框定问题，定义带有角色的比较维度
quint_solution	探索变体并进行多样性检查，进行对等比较
quint_decision	FPF E.9 决策契约，影响测量，证据
quint_refresh	所有工件的生命周期管理
quint_query	搜索，状态仪表板，文件到决策查找

---

基于第一性原理框架

FPF（第一性原理框架） by Anatoly Levenchuk —— 一种严谨的、跨学科的思维架构。

/q-reason 为您的 AI 代理提供了一个用于工程决策的 FPF 原生操作系统：解决方案前的问题框定，比较前的特征化，对等性执行，带有一致性惩罚的证据，最弱环节保证，以及当证据老化或测量失败时自我闭合的双纽线循环（lemniscate cycle）。

quint-code fpf search 让您访问 FPF 规范中的 4243 个索引章节 —— 代理可按需查找任何概念。

---

了解更多

查看 文档 以获取有关决策模式、DRR 格式、计算功能和生命周期管理的详细指南。

要求

• Go 1.24+（用于从源代码构建）
• 任何支持 MCP 的 AI 工具

许可证

MIT

quint-code 快速上手指南

quint-code 是一个基于第一性原理框架（FPF）的 AI 工程决策助手。它能帮助你在开发过程中记录决策契约、对比选项，并自动管理决策的生命周期（如过期提醒）。它通过 MCP 协议集成到各类 AI 编程工具中。

环境准备

在使用之前，请确保满足以下条件：

• AI 工具支持：你需要一个支持 MCP（Model Context Protocol）的 AI 编程工具。官方支持的包括：
  • Claude Code
  • Cursor
  • Gemini CLI
  • Codex CLI / Codex App
  • JetBrains Air
• 网络环境：安装脚本依赖 GitHub Raw 资源，请确保网络可访问 raw.githubusercontent.com。
• 系统要求：Linux 或 macOS 终端环境（Windows 用户建议使用 WSL）。
• Go 语言：仅当你需要从源码编译时必需（Go 1.24+），预编译二进制文件无需此依赖。

安装步骤

1. 安装二进制文件

在终端中运行以下命令进行安装：

curl -fsSL https://raw.githubusercontent.com/m0n0x41d/quint-code/main/install.sh | bash

2. 初始化项目

进入你的项目目录，根据你使用的 AI 工具运行对应的初始化命令。

通用初始化（默认适配 Claude Code）：

quint-code init

指定工具初始化：

# Cursor
quint-code init --cursor

# Gemini CLI
quint-code init --gemini

# Codex CLI / Codex App
quint-code init --codex

# JetBrains Air
quint-code init --air

# 同时为所有工具初始化
quint-code init --all

⚠️ 重要提示（针对 Cursor 用户）： 初始化后，打开 Cursor 设置 → MCP → 找到 quint-code → 启用开关。Cursor 默认会禁用新添加的 MCP 服务器。

3. 现有项目接入（可选）

如果是已有项目，初始化后可运行以下命令让 Agent 扫描代码库中值得记录的既有决策：

/q-onboard

基本使用

核心指令：一键推理

最简便的使用方式是直接调用 /q-reason。Agent 会自动完成问题构建、方案生成、公平对比及决策记录。

示例：

/q-reason 如何在微服务架构中处理分布式事务？

分步手动控制

如果你希望更精细地控制流程，可以按顺序执行以下步骤：

指令	作用
/q-frame	定义问题框架
/q-char	明确关键要素
/q-explore	探索不同选项
/q-compare	公平对比方案
/q-decide	记录最终决策契约

查看状态与生命周期

• 查看决策状态（检查是否有过期或需关注的决策）：

  /q-status
  

• 管理生命周期（更新、作废或重新打开决策）：

  /q-refresh
  

新手引导

如果你是第一次使用，可以让 Agent 为你解释工作流程：

/q-reason explain how to work with quint-code effectively — what commands exist, when to use each one, and what's the recommended workflow