XP-Gate

AI 写 100 行代码只需 5 秒，但判断这 100 行对不对仍然要人工花 30 分钟。XP-Gate 把这 30 分钟压缩回秒级。

Three machine-driven feedback loops bringing Extreme Programming speed to the AI era. (English docs: see skills/*/SKILL.md)

目录

1. 为什么是极限编程
2. 三个反馈环
3. 快速开始
4. Sprint Flow 全流程（反馈环 1–3 的工作流实现）
5. 质量门禁详解（反馈环 1）
6. Delphi 多专家评审（反馈环 2·第一步）
7. 语言支持
8. AI 技能集成
9. 配置说明
10. 贡献指南

为什么是极限编程

1999 年，Kent Beck 在《Extreme Programming Explained》中描述了 12 个极限编程实践。这本书的核心洞见不是"结对编程"或"持续集成"这些具体做法，而是一个更根本的观察：

软件开发中最大的成本不是写代码，而是返工。返工的根本原因不是程序员不够聪明，而是反馈太慢。

传统的反馈周期以天为单位（写完代码 → Code Review → QA 测试 → 返工）。极限编程试图把反馈压缩到分钟级 — 每次改动都有单元测试告知对错，每轮迭代都有客户验证方向。

AI 辅助编程把这个问题彻底改变了。AI 写完一段代码的速度是秒级，但反馈速度仍然以人审阅代码的速度运行 — 分钟级甚至小时级。反馈循环的瓶颈从"写代码"转移到了"判断代码对不对"。

XP-Gate 解决的就是这个问题：在 AI 生成代码的速度和人类验证代码的速度之间，构建三个机器驱动的反馈环。

三个反馈环

极限编程认为反馈是质量的根本来源。XP-Gate 用三个层层递进的反馈环把这个理念自动化：

┌──────────────────────────────────────────────────────────────────┐
│                        三个反馈环                                  │
├──────────────┬──────────────────────┬────────────────────────────┤
│   环 1        │   环 2               │   环 3                      │
│   代码层      │   需求层              │   迭代层                    │
├──────────────┼──────────────────────┼────────────────────────────┤
│ 代码          │ 需求 ↔ 测试           │ 规划 ↔ 复盘                  │
│ ↔ 测试        │                      │                            │
│ ↔ 静态检查    │                      │                            │
├──────────────┼──────────────────────┼────────────────────────────┤
│ 确定性        │ 确定性 + Delphi 评审  │ 数据驱动的                    │
│ 秒级反馈      │ 分钟级反馈 (2 次提交)  │ 迭代级反馈 (每 Sprint)        │
│ 约 90% 闭合   │ 约 80% 闭合           │ 约 55% 闭合                  │
└──────────────┴──────────────────────┴────────────────────────────┘

环 1：代码层 — "这行代码写得对吗？"

提交代码时自动触发，秒级反馈。纯确定性规则，零 AI 参与。

• Gate 1: Lint — 代码风格一致
• Gate 2: 重复代码 — 不重复造轮子
• Gate 3: 圈复杂度 — 逻辑不过度复杂
• Gate 4: Clean Code + SOLID — 14 条确定性规则
• Gate 5: 单元测试 + 覆盖率 + 文件配对 — 测试写了且写对了
• Gate 6: 架构合规 — 不破坏分层
• Gate 7: IaC 安全扫描 — 基础设施即代码的漏洞
• Gate 8: 密钥扫描 — 不泄露密钥
• Gate 9: 构建完整性 — TypeScript 编译、打包、import 检查
• Gate 10: SAST 安全扫描 — 代码层安全漏洞
• Gate 11: Sprint Flow — 流程合规
• Gate 12: 文件卫生 — 冲突标记、语法检查（警告级）
• Gate 13: 编译器严格检查 — C/C++/Java 开启更严格的编译告警（仅改动文件）

这个环闭合了约 90%。目标：100%。

环 2：需求层 — "这段代码做对了吗？"

需求写成测试，测试约束代码。分两步：

第一步（AI 参与）：Delphi 多专家匿名评审

3 位专家使用三个 distinct trimmed executable model IDs，匿名评审需求和设计，必须 ≥90% 一致才能通过。模型 provider、厂商、gateway 和国籍均不受限制，一个 provider 和 token plan 也可以服务三个角色。这一步在写代码之前完成，回答"需求是否合理"。基于 RAND 公司 1950 年代开发的 Delphi 方法论，消除锚定效应和单一视角盲区。

第二步（确定性）：test-alignment 引擎

提交时自动运行，纯 TypeScript 代码：parse specification.yaml → parse @test REQ-XXX 注解 → 交叉验证每个需求是否有对应的测试，每个验收条件是否有断言。回答"测试是否真的覆盖了需求"。

为什么必须有第二步？ Delphi 评审保证需求的质量，但无法保证代码真的实现了需求。AI 可能误读 spec，可能漏写断言，可能让测试通过但语义不对。test-alignment 引擎用确定性代码捕捉这个断层。

这个环闭合了约 80%。剩余 20% 缺口：parseTestFiles() 中 template literal 测试名称和 .each() 变体的正则匹配，见 src/npm-package/lib/__tests__/test-alignment.test.ts。

环 3：迭代层 — "我们是不是在越做越好？"

一个 Sprint 产生的数据驱动下一个 Sprint 的决策。

• Boy Scout Rule：每次修改，警告数不能增加。这是环 3 的微观实现 — 代码质量只进不退。
• retro 数据：每个 Sprint 结束时的复盘数据（rework rate, evidence skip 次数, 质量趋势）自动注入下一个 Sprint 的初始化参数。
• evidence_schema_version=2：新 Sprint 默认启用严格证据验证，让环 2 的输出真正约束环 3。

这个环闭合了约 55%。剩余缺口：环 3 的数据产量够了，但自动驱动下一个 Sprint 的机制还不完善。

以上就是三个反馈环的理念。下面来看这些理念如何在真实开发流程中落地实现。

快速开始

XP-Gate 由 两个互补的发行渠道 组成：

第一步：安装 npm 包（必需 — Git Hooks + 全流程基础设施）

前置条件：Node.js ≥18.x、Git ≥2.38、bash（Linux/macOS 自带，Windows 需 Git Bash）。

npm install -g @boyingliu01/xp-gate
cd your-project
xp-gate init

npm 包提供：

• Git Hooks（pre-commit 12 道门禁 + pre-push 8 道门禁）— 每次提交/推送自动执行
• CLI 管理命令（doctor, baseline, audit, check-alignment 等 20+ 子命令）
• Skill 安装器（xp-gate install-skill 从包内 skills/<name>/ 全量复制，无需网络）

第二步：安装 IDE 插件（推荐 — AI 对话内质量工具 + 技能自动加载）

Qoder 插件：xp-gate init 自动检测并部署 Delphi 评审所需的 3 个 Custom Agent，直接消耗 Qoder Credits，无需外部 API。

OpenCode 插件：

{ "plugin": ["@boyingliu01/opencode-plugin"] }

Claude Code 插件：

/plugin install boyingliu01/xp-gate

IDE 插件提供 AI 对话内的质量工具（gate-check、gate-principles、gate-arch）和技能自动加载。不提供 Git Hooks（AI 平台限制）。

npm 包 = git enforcement，IDE 插件 = IDE 集成。两者互补，缺一不可。

xp-gate CLI 命令速查

遗留安装路径（仓库直接克隆 — 适用于开发者或无法使用 npm 的环境）

git clone https://github.com/boyingliu01/xp-gate.git && cd xp-gate
bash githooks/install.sh
bash githooks/verify.sh

Sprint Flow 全流程

极限编程的迭代周期映射到 AI 驱动的 6 阶段流水线：

Phase 1       Phase 2       Phase 3       Phase 4       Phase 5       Phase 6
PREP     →    DESIGN   →    BUILD    →    VERIFY   →    SHIP     →    CLOSE
   │             │             │             │             │             │
   ▼             ▼             ▼             ▼             ▼             ▼
worktree      grill-with    ralph-loop    code-walk     PR + merge     UAT +
+ sizing      -docs → R1    + TDD         + QA + retro  + deploy       cleanup
              → batch-      + test-align  + learn       + canary
              grill-me
              → R2 delphi
              (HARD-GATE)

v0.18.0+：Phase 2 DESIGN 使用 grill-with-docs（需求梳理）→ batch-grill-me（批量决策）→ delphi-review 多轮评审。旧版文档中提及的 brainstorming/autoplan 是 v0.17.x 及之前的 Phase 2 流程。

使用方式

# 启动完整 Sprint
/sprint-flow "开发用户登录功能，支持 OAuth2"

# 指定技术栈
/sprint-flow "开发用户登录" --type web-nextjs --lang typescript

# 查看当前 Sprint 进度
xp-gate sprint-status --watch

质量门禁详解

每次 git commit 自动执行 13 道门禁 (Gate 0-12)，每次 git push 自动执行 8 道门禁：

Pre-commit（13 道门禁）

Gate 12 (File Hygiene) 仅对冲突标记和 YAML/JSON 语法错误阻断提交；其他问题（trailing whitespace, 缺少 EOF 换行）仅警告，不阻断。

Pre-push（8 道门禁）

Pre-push 大小限制已移除：AI 工作流产生大体积累积推送，文件数量不是质量信号。预推送门禁强制执行突变、模拟和代码走查，但不限制推送大小。

设计原则：工具不可用 = SKIP，不阻断。 某语言的工具装不上，该语言的检查自动跳过，不影响其他语言。唯一例外：Gate 8 密钥扫描自 #499 起 fail-closed——gitleaks 缺失或异常退出直接阻断（安全门禁不能在无法运行时报成功）。
--no-verify 严格禁止。 绕过门禁等于放弃反馈环。

Delphi 多专家评审

作为环 2 的第一步，Delphi 评审在写代码之前就验证需求和设计。基于 RAND 公司 1950 年代开发的 Delphi 方法论：

为什么是 Delphi？

传统 AI 评审是 n=1 — 一个模型对一段信息做出判断。但单个模型有系统性盲区：DeepSeek 对某些领域偏保守，Kimi 可能过度乐观，Qwen 可能在特定场景误判。

Delphi 方法论解决这个问题的核心设计：

• 匿名性：3 位专家互不知晓对方的判断，消除锚定效应
• 迭代性：多轮评审直到共识，每轮能看到上一轮的统计结果但不知道谁说了什么
• 统计共识：≥90% 一致才算通过，不靠多数票

三种模式

requirements 模式通过 delphi-review --mode requirements 触发，输出 requirements-reviewed.json，并由 Phase 2→3 硬闸门验证。R2 design 评审在设计生成后独立执行，产生设计评审证据，不替代 R1 需求证据。

与 test-alignment 的关系

Delphi 评审回答**"需求写得好不好"，test-alignment 引擎回答"代码有没有按需求实现"**。两者是互补的，不是互相替代的：

specification.yaml
       │
       ├── Delphi Review ──► "需求质量、完整性、可行性"
       │
       └── test-alignment ──► "测试是否覆盖每个需求、每个验收条件"

模型选择（强制三个 distinct executable models）

模型配置通过 .delphi-config.json 管理。architecture、technical、feasibility 三个专家必须成功执行，且 requested_model trimmed 后互不相同。Provider、vendor、gateway 和模型国籍均不受限制。provider: local fallback 不能计数，local hosted endpoint 可以作为普通 callable provider。具体模型名称以你的 provider API 文档为准，配置示例见下方配置说明。

语言支持

XP-Gate 支持 12 种语言 + IaC，通过适配器自动检测和路由：

* 所有编程语言统一使用 lizard 进行圈复杂度分析。

AI 技能集成

XP-Gate 内置 12 个专业 AI 技能，另在 Sprint Flow 中集成了多个外部技能。以下按 Sprint Flow 阶段排列：

内置技能通过 xp-gate install-skill <name> 安装。外部技能由 Sprint Flow 工作流自动调用，无需单独安装。

配置说明

.principlesrc（原则检查配置）

在项目根目录创建，Gate 4 读取此文件：

{
  "long-function-threshold": 50,
  "god-class-threshold": 15,
  "deep-nesting-threshold": 4,
  "max-parameters": 4,
  "complexity-threshold": 10,
  "magic-numbers-whitelist": [0, 1, -1, 2, 10, 100, 1000, 60, 24, 7, 30, 365, 256, 1024],
  "coverage-threshold": 80,
  "max-exports": 10
}

架构检查的规则源（#447 起的口径）

xp-gate arch（Gate 6 独立运行）与 pre-commit 的 Gate 6 使用同一套规则源：本地钉住的
@archlinter/cli（xp-gate 依赖中的 ^0.16.0）内置检测器，不再读取 architecture.yaml：

• 判定语义：项目根存在 .architecture-baseline.json 时走 baseline 棘轮（只拦相对基线新增的
  high/critical 级发现，与 Gate 6 pre-commit 的 archlint diff .architecture-baseline.json --fail-on high
  完全一致）；不存在时走零容忍（任何 high/critical 级发现即拦）。
• 版本纪律：解析顺序为「xp-gate 自身依赖 → 项目本地 node_modules → PATH → npx --no-install」，
  绝不 npx -y（拉最新版会造成「本机能跑、别人不能跑」的漂移，见 #447 REQ-4）。
• 反空转：测试套件用真实 archlint 植入一个 high 级违规（大段重复代码）→ 断言非零退出；
  干净树 → 0。「返回 0」被证明是真实扫描的结果，而非硬编码通过。

architecture.yaml 与 .archlint.yaml 的分叉

即：architecture.yaml 的规则内容不会传给 archlint——两条路径的规则源分叉就此固定。
如确需自带配置，用 opt-in 的 xp-gate arch --use-config <file>（--config 为 deprecated 别名）：
文件将原样传给 archlint --config，schema 版本责任由用户自行承担（archlint 会拒绝 pre-0.16 结构）。

历史规则清单（ARCH-001 至 ARCH-014 的语义说明）保留在仓库根目录 architecture.yaml 的
rules: 块（不是注释）中，仅作规划参考——这 14 条编号当前无实现，
全仓 grep -rn "ARCH-0" src/ 除一组无关测试标签外零命中。详见 #685 / #687。

.delphi-config.json（Delphi 评审配置）

在项目根目录创建，定义评审专家和共识参数。模型名称以你的服务商 API 文档为准：

{
  "active_profile": "default",
  "profiles": {
    "default": {
      "providers": {
        "bailian-tp": {
          "base_url": "https://coding.dashscope.aliyuncs.com/v1",
          "api_key": "${BAILIAN_API_KEY}"
        }
      },
      "experts": {
        "architecture": { "provider": "bailian-tp", "model": "qwen3-coder-plus" },
        "technical": { "provider": "bailian-tp", "model": "deepseek-v3.2" },
        "feasibility": { "provider": "bailian-tp", "model": "kimi-k2.5" }
      }
    }
  },
  "consensus": {
    "threshold_percent": 90,
    "max_review_rounds": 5
  }
}

配置示例使用一个 provider 和 token plan，但三个 distinct 模型 ID。将 BAILIAN_API_KEY 设置为你的 API key；不要把密钥写入配置文件或提交到版本控制。

.xp-gate-mypy-scope（Python mypy 类型检查面声明，可选）

Python 项目的默认 mypy 范围是存在且含 .py 文件的 src/ 与 scripts/；两者皆无时 Gate 1 的类型检查会 SKIP（不会假 BLOCK）。如果仓库的类型检查面是其他布局（如 engine/、lib/），在项目根目录创建 .xp-gate-mypy-scope，每行一个目录：

engine
tools/generate
# 以 # 开头的行为注释；行内注释也支持

声明的目录同样要求存在且含 .py 文件（缺失或为空会被 WARN 并跳过，不会硬 BLOCK）。

贡献指南

开发设置

npm install
bash githooks/install.sh --force
bash githooks/verify.sh

提交规范

• 所有提交必须通过 pre-commit 门禁
• 禁止 --no-verify
• 禁止 as any、@ts-ignore、空 catch 块
• 修改文件的警告数持平或下降（童子军规则）
• Pre-push 大小限制已移除 — AI 工作流产生大体积累积推送，数量不是质量信号

测试规范

/**
 * @test REQ-XXX 功能名称
 * @intent 验证特定行为
 * @covers AC-XXX-01, AC-XXX-02
 */
describe('Feature', () => {
  it('should do X when Y', () => { ... });
});

许可证

MIT License. Copyright (c) 2024-2026 XP-Gate Contributors.

相关链接

• 三个反馈环设计文档 — 反馈环 2 重构的完整设计
• Sprint Flow 详细文档
• Delphi 评审规范
• 测试对齐验证
• 质量门禁守则