navori
深入了解

navori 的内部能力
逐层解析。

navori 是一个具有 明确主张的 harness，面向已经在生产环境运行、存在旧依赖及未完成迁移的真实代码。它把 Claude Code 组织成遵守标准、共享记忆与跨仓库规范的团队。下面逐层解释它为何适合作为基础。

还不熟悉这些术语： harness, 技能或 SDD? 先查看简明术语表 ↓

开始之前

简明术语表

点击术语，用一句话理解含义。

Harness

围绕 AI 助手的规则、智能体和自动化体系，让它按照团队期望工作，而非自行其是。

智能体 / 子智能体

负责特定角色（探索、编写、审查）的助手。主智能体把工作分配给专门的子智能体。

技能

完成具体任务的可复用指南，例如如何创建接口、如何验证完成；智能体按需加载。

钩子

在固定时机触发的自动化，如每次提交前运行测试，无需人为记住。

质量关卡

判定变更完成前必须通过的命令，如 lint 与测试。

SDD

规格驱动开发：规则写在代码旁并随版本管理，可用一条命令更新，而非仅存于个人脑中。

预设

按技术栈打包的配置，如 Vite + React、NestJS 或 monorepo。navori 检测技术栈并选择对应预设。

Engram

持久记忆，保存决策与经验，使助手能在下次会话恢复。

受管理块

CLAUDE.md 中标记为 managed by navori 的片段，可更新而不覆盖周围的自定义内容。

legacyPaths

你标记的旧代码目录，智能体会谨慎处理，不强加新规则。

01 · 编排

一支智能体团队， 协作完成任务。

主智能体 直接承担 orchestrator 角色 ，作为会话中心拆分任务。子智能体并行工作，只返回结论。每个角色都有严格职责与合适的模型。

点击卡片，了解每个角色的职责 ↓

编排者

opus

由主智能体直接承担这个角色，而非另建子智能体。它读取任务，决定如何拆分，并行启动执行者，最后将结果整合为一致的解决方案。使用能力最强的模型（opus），因为它的职责是推理与决策，而非阅读文件。

角色与模型：时间及 token 效率

haiku 发布与文档

publisher · scribe

机械任务使用快速、低成本模型。

sonnet 阅读、编写与审计

scout · implementer · reviewer · auditor

平衡质量和成本。

opus 决策与设计

orchestrator · architect

把强能力用在需要判断之处。

全部可在 config.models中配置。让强模型负责决策，让轻模型快速探索。架构师使用最高推理强度（xhigh），只参与二级和三级任务，因此成本有界。级别由 classify确定，而非模型自行判断。

复杂任务中的 orchestrator 
orchestrator › splits the ticket into 3 subtasks
  ├─ scout       → map the module        (own context · sonnet)
  ├─ scout       → how is it validated?  (own context · sonnet)
  └─ implementer → applies the change   → quality gate ✓  (sonnet)
       └─ reviewer → approves against CLAUDE.md          (sonnet)
orchestrator › synthesizes and delegates the commit → publisher  (haiku)

派工前先按风险确定计划级别

orchestrator 使用 navori plan classify ，按可验证信号计算 0–10 复杂度分数，选择对应级别，而非凭聊天中的笼统描述。

级别 适用情况 产物
0 复杂度 ≤ 3，最多一个非平凡文件，且没有关键区域的最低级别要求。 无需独立计划；classify 确认可直接执行的豁免。
1 常见情况，大多数计划任务属于此级别。 简单工作计划（plan-simple 技能）：目标、带命令与期望输出的 A<n> 标准、范围外事项、文件、进度和决策。
2 复杂度 ≥ 8，或涉及关键区域、资金/凭据/个人信息、多仓库、新依赖、共享契约或迁移。 高级工作计划（plan-advanced 技能）；架构师探索并推荐选项，用户先选择，再形成结论。
3 用户已接受规格。 specs/<feature>/{requirements,design,tasks}.md；架构师编写 design.md，不另建工作计划。

由 PreToolUse 钩子限制派发 implementer ，任务必须携带通过 navori plan check的工作计划，或由 classify 确认的零级豁免。连续两次审查拒绝（CHANGES_REQUESTED）后，第三次派发前必须补充更高级别产物；二级或三级则直接交由用户决定，而非继续尝试。

02 · 真实环境

面向生产， 立足真实代码。

多数工具假设仓库干净且从零开始。navori 关注团队现实：生产代码、旧依赖与进行中的迁移。通过 init 选择工作环境，从而决定智能体如何工作。

init 时选择项目模式

选择全新项目（快速推进）、生产项目（防止回归）或旧系统迁移（维护新旧兼容），从而决定智能体工作方式。

智能体遵守 legacyPaths

标记旧代码目录后，orchestrator、implementer 和 reviewer 会遵守差异化规则，不对无权改动的旧代码强加新约定。

迁移前先审计

面对结构迁移，如旧后端到新后端、单体到微服务，先分析根因、影响区域与兼容性，再编写代码。

理解迁移的技能

verify-before-done、debug-failure 与 review-diff 能识别新旧代码共存时的不一致状态，减少半完成迁移中代价最高的错误。

navori init — 项目模式 
? What terrain are you on?
    greenfield   — new code, move fast
  › production   — in production, guard regressions
    migration    — legacy migration, watch
                   legacy↔new compatibility

→ legacyPaths: [ "src/old-api", "legacy/" ]
  the orchestrator, implementer, and reviewer
  treat those paths with different rules.
03 · 效率

减少 token 从设计开始。

编排也管理上下文成本。繁重工作在独立窗口和独立模型中执行，只返回必要结论，主线程因此保持清晰。

各子智能体上下文隔离

每个子智能体在独立窗口运行，只返回结论。orchestrator 的线程不会堆满读取的文件。

按角色分配模型

阅读和探索使用轻模型，决策与审查使用强模型，避免让高成本模型承担文件阅读。

按片段阅读

Scout 只读相关片段，不读取全部文件。它负责定位，而非复制整库。

按需加载技能

技能目录用索引引用，只有任务需要时才加载完整内容。

精简受管理块

规范排序与去重保持 CLAUDE.md 简洁，避免复制与逐会话累积的噪声。

对比

没有 harness

单线程读取整份文件，将全部内容堆入上下文，逐轮携带直到窗口耗尽。

使用 navori

子智能体并行探索并返回结论，orchestrator 基于摘要推理。Engram 把需要长期记住的内容保存在上下文窗口外。

04 · 记忆

Engram： 持久保存记忆。

LLM 上下文是临时的，会话关闭后就会遗忘。navori 默认启用 Engram，使决策、已查明根因的错误与约定可跨会话保存、找回，并在上下文压缩后继续存在。

  • 会话结束和上下文压缩之后仍然保留。
  • mem_save 保存决策、已查明根因的错误和约定；mem_search 在启动时找回。
  • 协议注入 orchestrator，主动保存，无需提醒。
  • navori 默认始终启用。无需重复解释上周的上下文。
今天的会话 · 下周的会话 
# today — after fixing a bug
mem_save "The 360 report breaks if languages[] is empty.
          Root cause: missing guard in report.py. Fix: default []."

# next week — new session, context at zero
mem_search "360 report languages"
→ recalls the decision, the root cause, and the fix.
  You don't re-explain it.
05 · 组织扩展

一个工作区， 覆盖所有仓库。

管理十五个仓库时，无需维护十五套标准。工作区提供跨仓库层，统一定义组织质量关卡、基础分支与约定，由各仓库继承。团队切换项目时仍采用同一工作方式。

  • 跨仓库配置位于 ~/.navori/workspaces/<org>.json，不属于某个单独仓库。
  • 组织级默认值：质量关卡、基础分支和共享约定。
  • 任务以可版本管理的文件保存在工作区内。
  • workspace render 一次将标准应用到所有已注册仓库。
组织标准应用到每个仓库 
$ navori workspace init acme
$ navori workspace set-default acme \
    --branch-base main --commits conventional-es
$ navori workspace add-repo acme ./web-app
$ navori workspace add-repo acme ./api-core
  … 13 more repos

$ navori workspace render acme
✓ 15 repos rendered with the same standard
06 · 保护机制

用标准和关卡 保护工作成果。

拥有写入权限的智能体需要约束。navori 将简单性、严格类型、安全与质量关卡作为 harness 的必要组成，并与其余配置一同版本管理。

简单优先

写代码前先问：是否最简单，六个月后是否可读，是否沿用现有模式？避免以后无人理解的技巧。

禁止 any

使用 unknown、类型收窄与显式类型。唯一例外为带原因的 // justified any: <reason>，只作最后手段，不作便捷捷径。

防御性钩子

guard-destructive 拦截危险命令；quality-gate 在每次提交前运行 lint 与测试。

deny / ask 权限

敏感操作被阻止，或需要明确确认。使用多层防御，而非单一屏障。

07 · 差异

为什么选 navori， 它与通用脚手架有何不同。

给 AI 助手指令有很多方式，但很少能长期适应真实团队及有历史的仓库。以下能力展示 navori 的不同之处。

无需复制 .claude/

版本化事实来源与幂等渲染，让跨仓库配置可以扩展并持续更新，避免手动复制目录。

持续维护而非静态模板

检测真实技术栈，包括 Mantine、Redux、NestJS 和 pnpm monorepo，组合适合的预设。标准通过版本管理和一条更新命令持续维护。

重视生产与旧系统

很多工具假设仓库从零开始；navori 关注真实运行的代码、旧依赖和进行中的迁移。

功能齐备且相互连接

持久记忆、安全与重复关卡、多智能体编排、跨仓库标准均已连通，无需照着 README 手动拼装。

08 · 团队协作

加入一个 已经使用 navori 的仓库。

每个仓库只需提交一次配置，团队随后遵循它。无需手写 harness，也无需在项目间复制 .claude/ 。以下是每位成员加入项目时运行的命令。

准备前置条件

需要 Node.js 22.12+、Claude Code，以及使用持久记忆时的 engram 可执行文件。第三步的 doctor 会准确说明缺少什么。 

node --version   # v22.12 or higher
# Claude Code installed on your machine

克隆并重建 harness

仓库已有唯一事实来源 navori.config.json。一条命令就能为全队一致地重建所有已配置引擎，重复运行也不会产生变化。 

$ git clone <repo> && cd <repo>
$ npx navori render --apply

✓ configured engines rebuilt from the config

使用 doctor 验证

doctor 确认一切已更新；若缺少 engram 等工具，会给出准确安装命令，无需猜测。 

$ npx navori doctor

◇ All good — nothing pending.
⇡ engram — missing from PATH:
   brew install gentleman-programming/tap/engram \
     && claude plugin install engram

正常开始工作

打开 Claude Code，即可使用相同智能体、技能、质量关卡与团队记忆。配置更新后运行 sync，同步规则并保留代码。 

# already productive with the team's harness

# when the repo config changes:
$ npx navori@latest sync

团队成员只需： clone → npx navori render --apply → npx navori doctor 即可使用相同 harness 开始工作。

从理论 一分钟落地到仓库。

一条采用命令就能生成这些内容，之后配置变化时重新渲染即可。

查看快速开始 命令参考
致谢

站在巨人的 肩膀上。

navori 集成了优秀工具，也从开源项目与标准中吸收想法。每项成果的贡献属于其原作者。

基础工具

思想与标准

启发本项目的开源项目

navori 借鉴了这些项目，其中 codegraph 同时作为插件集成。逐项目说明见 docs/inspiration.md.

使用的技术 clack citty zod Astro Tailwind CSS