⚛️ Nucleus

研发流程纪律插件 · 适用于 Claude Code / Codex

Nucleus 是一个安装在 AI coding agent 内部的工作流插件。它不替你写更多代码，而是确保 AI 在你的代码仓库里每一步的产出都是结构可验证的、边界可审计的、可追溯的。

📌 目录

• 产品说明
• 安装与使用
• Skill 全景
• 竞品分析
• 底层剖析
• 维护说明

🧭 产品说明

它解决什么问题

使用 AI 做工程开发时，有一类问题比"AI 写错代码"更难处理：

AI 写完了，但你不知道它做了什么、基于什么决策、产物算不算数。

Nucleus 的答案：把"产物可信度"作为工作流的一等公民。

• ✅ 每个 Skill 有结构化的 JSON Schema 输入输出契约
• ✅ 写入边界在运行时强制检查，违规直接阻断
• ✅ 人工审查请求发出前，必须经过独立预审子代理
• ✅ 失败策略是 ALERT_AND_BLOCK，不静默降级

目标用户

🚀 安装与使用

前置检查

在安装 Nucleus 之前，请确认以下条件：

• 已安装 Claude Code 或 Codex
• 目标代码仓库根目录存在 AGENTS.md（Nucleus 以此作为最高事实源）
• 目标仓库已初始化 git 仓库

⚠️ 注意：AGENTS.md 是 Nucleus 运行的前置必要条件，缺失时 safe_repo_root() 会直接报错阻断。

安装步骤

Claude Code

# Step 1: 添加 Marketplace
/plugin marketplace add [email protected]:protect-my-hair/nucleus-marketplace.git

# Step 2: 安装插件
/plugin install Nucleus@nucleus-marketplace

# Step 3: 更新（后续）
/plugin marketplace update && /plugin update Nucleus@nucleus-marketplace

Codex

codex plugin marketplace add [email protected]:protect-my-hair/nucleus-marketplace.git
codex plugin add Nucleus@nucleus-marketplace

安装完成后，Claude Code 会话启动时 SessionStart hook 自动注入 using-nucleus 入口纪律，无需手动加载。

典型工作流：从需求到交付

以"为现有产品新增 CSV 导出特性"为例，完整走一遍核心链路：

🔒 每个 ✋ 节点前，Nucleus 都会强制运行 subagentPreReview——独立子代理预审，通过后才允许请求人工确认。

完成后，目标仓库的产物结构：

.nucleus/
├── context/
│   └── wfr-20260716-a1b2c3.json       # 任务上下文（需求、特性定义）
└── runs/
    └── wfr-20260716-a1b2c3/
        ├── result.json                  # 最终结果包（Nucleus.result.v1 schema）
        ├── asset-boundary-gate.json     # 写入边界审计记录
        ├── architecture/                # 架构影响评估（如有）
        └── tests/                       # 测试执行报告

🗂️ Skill 全景

Nucleus 共提供 26 个 Skill，覆盖研发全链路：

核心链路 Skill

辅助 Skill

⚖️ 竞品分析

市场上与 Nucleus 同类的插件主要有 Superpowers（Prime Radiant）和 Trellis。三者都在解决"AI coding agent 怎么做好工程开发"这个问题，但出发点根本不同。

设计理念

Superpowers 和 Trellis 共同的盲点：它们都假设"只要流程走对了，产出就是可信的"。

Nucleus 填补的正是这个盲点——流程走对了，不代表每一步的产物是结构正确的、边界合法的、review 前经过了独立验证的。Nucleus 在"怎么做"之上，额外管"做出来的东西算不算数"。

功能横向对比

选型建议

🔬 底层剖析

1️⃣ workflowRunId：一次任务的唯一标识

每次开发任务开始时，nucleus-context 生成唯一的 workflowRunId，所有后续 Skill 都绑定这个 ID。这不只是命名约定——每个 Skill 执行前都会校验前置产物是否存在，缺失则阻断。

# paths.py — 所有产物路径都通过 workflowRunId 锁定
def relative_run_path(workflow_run_id: str, filename: str) -> str:
    run_id.validate_run_or_diagnostic_id(workflow_run_id)
    return f".nucleus/runs/{workflow_run_id}/{filename}"

2️⃣ asset_boundary.py：运行时写入边界强制

Superpowers 和 Trellis 靠 Markdown 约定写入边界（"不要写到这个目录"）。Nucleus 在运行时强制执行：

# asset_boundary.py
LEGACY_PREFIXES = (".autocode/", ".claude/notepads/", "docs/bugfix/")

def _path_violation(path: str, allow_requirement_write: bool):
    for prefix in LEGACY_PREFIXES:
        if canonical.startswith(prefix):
            return "LEGACY_PATH_RISK", f"命中 legacy risk path: {canonical}"
    if canonical.startswith("docs/requirement/") and not allow_requirement_write:
        return "COMMAND_POLICY_VIOLATION", f"普通 workflow 未授权写 docs/requirement/**"

3️⃣ subagentPreReview：独立于主链路的预审门

Superpowers 的 reviewer 在主链路内派发，reviewer 和 implementer 共享同一条上下文链路，存在自我验证的偏差风险。

Nucleus 的 subagentPreReview 是完全独立的强制门：

# using-nucleus SKILL.md — HARD-GATE
任何人工审查 / 人工评审 / 人工复核请求发给用户或 PMS 前，
必须先按目标 workflow 的 subagentPreReview 调度独立 reviewer 子代理；
未预审不得询问"是否评审通过"。

✅ 你收到的每一次"请审查"请求，都已经经过一轮独立预审，不是 AI 自说自话通过的。

4️⃣ JSON Schema 数据契约

Nucleus 是三个产品中唯一做到结构化数据契约的——Superpowers 和 Trellis 的产物都是 Markdown，靠约定不靠校验。

result.json 的 status 字段只接受枚举值：

自动化系统和 PMS 集成可直接消费 .nucleus/runs/<workflowRunId>/result.json，无需解析人类文字。

5️⃣ ALERT_AND_BLOCK：失败不降级

Trellis 的 trellis_config.py 遇到配置缺失时静默返回 {}，让工作流继续。Nucleus 的策略相反：

# policy-pack.md
关键输入、写入权限、测试、review、provider health、session binding
或 result package 缺失时，默认 ALERT_AND_BLOCK。
不静默降级，不跳过关键产物，不用自然语言总结替代 result package。

一个停住的工作流比一个"看起来完成但有缺口"的工作流更有价值。工程团队可以处理明确的阻断，但很难发现悄悄降级的产物。

🔧 维护说明

# 构建前分发检查（只读）
python3 scripts/doctor.py --host all

# 构建 marketplace
bash build-marketplace.sh

运行结果阅读顺序

⚠️ summary.md 不能替代 result.json 中的机器字段，两者职责不同。

📄 License

MIT © protect-my-hair