PolyArch/humanize · 上手攻略

  • 仓库：PolyArch/humanize
  • 链接：https://github.com/PolyArch/humanize
  • 分类：AI 编程工作流 · Claude Code 插件
  • 作者：Tom
  • 更新：2026-08-12

是什么

Humanize 是一个 Claude Code 插件，提供RLCR 双循环迭代开发模式——Claude 负责实现，OpenAI Codex 负责独立审查，人类始终是最终决策者。通过持续反馈循环，将 AI 生成代码的质量问题在迭代中早期捕获，而非等到最终 review。

核心哲学来自 Richard Sutton 的"Bitter Lesson"：通用方法（在本例中是反馈循环）终将碾压只依赖知识的方案。Humanize 的结构化 plan 系统确保人类在执行前真正理解计划，而非"许愿式编程"（wishful coding）。

当前版本：1.16.0，基于 GAAC（GitHub-as-a-Context）项目衍生，2026 年 4 月被 ThoughtWorks Technology Radar 第 34 期将 Claude Code plugin marketplace 列入 Trial 环。

解决什么问题

AI 辅助编程的常见陷阱：给 Claude 一个模糊指令 → 等 40 轮 RLCR 循环跑完 → 发现产出的根本不是你要的东西。Humanize 通过Plan Understanding Quiz 在循环开始前强制确认你真正理解计划，而非只看到标题就跳过。

另一个痛点：Claude 单独工作时，代码质量依赖模型自身能力，缺乏独立审视。Codex 作为第二个 AI 从不同角度审查代码，弥补盲区。

快速安装

前置依赖

工具 用途 验证命令
codex CLI Codex review 引擎 codex --version
jq JSON 处理 jq --version
git 版本控制 git --version

安装步骤

# 启动 Claude Code
claude

# 添加 PolyArch 插件市场
/plugin marketplace add PolyArch/humanize

# 安装 humanize 插件
/plugin install humanize@PolyArch

本地开发分支（实验功能）：

git clone https://github.com/PolyArch/humanize.git
cd humanize && git checkout dev
claude --plugin-dir /path/to/humanize

安装成功后可见命令：

/humanize:start-rlcr-loop
/humanize:gen-plan
/humanize:refine-plan
/humanize:ask-codex

监控脚本（可选，推荐）

# 添加到 .bashrc 或 .zshrc
source ~/.claude/plugins/cache/PolyArch/humanize/<VERSION>/scripts/humanize.sh

# 在另一个终端运行
humanize monitor rlcr   # 监控 RLCR 循环
humanize monitor skill  # 监控所有 skill 调用
humanize monitor codex  # 仅 Codex 调用

核心用法

标准 RLCR 工作流

第一步：生成想法草案（可选）

/humanize:gen-idea "为编辑器添加撤销/重做功能"
# 输出到 .humanize/ideas/ 目录
# --n 参数控制探索方向数量，默认 6

第二步：从草案生成结构化计划

/humanize:gen-plan --input draft.md --output docs/plan.md
# --discussion: 迭代式 Claude/Codex 收敛轮次（推荐）
# --direct: 直接跳过收敛讨论
# --auto-start-rlcr-if-converged: 计划收敛后自动启动 RLCR

第三步（可选）：根据 review 意见精炼计划

/humanize:refine-plan --input docs/plan.md
# 读取 plan 中 reviewers 的 CMT:...ENDCMT 注释标注

第四步：启动 RLCR 循环

/humanize:start-rlcr-loop docs/plan.md

RLCR 循环的两个阶段：

  1. 实现阶段：Claude 执行 plan → Codex review 摘要 → 循环直到 COMPLETE
  2. 审查阶段：Codex 用 [P0-9] 严重等级标记检查代码质量问题 → 问题反馈回实现阶段

关键参数

参数 默认值 说明
--max 42 最大迭代轮次
--codex-model gpt-5.5:high fallback Codex 模型和推理努力值
--codex-timeout 5400 秒 每次 Codex review 超时
--full-review-round 5 全对齐检查轮次间隔（N-1, 2N-1...）
--base-branch auto-detect 代码审查基准分支
--push-every-round local commits 每轮强制 git push
--skip-impl false 跳过实现，直接进入 review
--agent-teams false 启用 Agent Teams 并行开发模式

Plan Understanding Quiz

Humanize 在循环开始前会问你两个选择题，测试你是否真正理解 plan 的技术细节。Quiz 是顾问性的，不是门槛——答错可以强制继续，但这正是整个系统的价值所在：2 秒摩擦比 40 轮循环浪费更划算。

跳过 quiz：

/humanize:start-rlcr-loop docs/plan.md --skip-quiz

完全自动化（跳过 quiz + Claude 直接回答 Codex 的开放问题）：

/humanize:start-rlcr-loop docs/plan.md --yolo

Gemini 咨询（需要 Gemini CLI）

/humanize:ask-gemini "What are the latest best practices for X?"

典型适用场景

  • 研究代码实现：论文方法复现、实验代码开发，plan 系统保证理解无误
  • 复杂 PRD 执行：产品功能开发，多轮迭代捕获架构问题
  • 代码质量高要求项目：Codex 独立审查减少 Claude 盲区
  • 多人协作过渡期：Agent Teams 模式并行拆分任务

不适合：小于 100 行的简单脚本（循环开销大于收益）、一次性数据分析（不需要迭代）

坑与注意

⚠️ 双重 API 成本：运行 RLCR 需要同时付费给 Anthropic（Claude）和 OpenAI（Codex），成本约单次完整循环的 2 倍。

⚠️ Codex 需要代码库访问权限：Codex review --base 模式需要完整代码库上下文，启动时注意确认授权范围。

⚠️ Quiz 的摩擦是设计意图：部分用户觉得 quiz 烦人而用 --yolo 跳过——这恰恰是 Humanize 最高价值的部分，跳过它等于放弃了核心保护机制。

⚠️ 监控脚本需要独立终端：humanize monitor 必须在 Claude Code 之外的另一个终端运行，不支持在同一个会话内。

⚠️ --agent-teams 是实验性功能：需要设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1，生产环境慎用。

⚠️ --push-every-round 可能污染 git 历史：默认本地提交，建议定期 rebase 整理后再推送。

⚠️ Plan Understanding Quiz 答错后继续的风险：如果 plan 本身有架构缺陷但你选择继续，RLCR 会放大这个错误——它是循环，不是修正带。

与同类对比

特性 Humanize ast-grep（静态分析） pr-reviewer 机器人
核心机制 RLCR 双循环 规则匹配 AST PR 提交触发
Review 来源 Codex（独立 AI） 规则引擎 第三方 AI 服务
Plan 系统 ✅ 内置 ❌ 无 ❌ 无
Quiz 理解确认 ✅ 强制 ❌ 无 ❌ 无
迭代次数 最多 42 轮 一次性 一次性
API 成本 双 Provider 免费规则 第三方定价
学习曲线 高（四工具链） 低 中

Humanize 填补的空白是：需要对 plan 本身有深刻理解、且愿意为迭代质量承担双倍成本的高级开发者场景。

一句话推荐结论

如果你的 AI 辅助开发已经进入"需要认真对待代码质量"的阶段，且愿意承担 Claude + Codex 双 API 成本，Humanize 的 RLCR 循环 + Plan Understanding Quiz 是目前最完整的质量保障方案；反之，单次 review 工具（如 ast-grep）更轻量实用。