Karajan Code - 多 Agent 协同开发治理框架

技能简介

Karajan Code（@karajan-family/code）是一款面向 AI 编程助手时代的"开发治理框架"，核心理念是"AI 写代码，Karajan 管过程"。它为 Claude Code / Codex / Copilot / Cursor / Antigravity / OpenCode / Aider 等多款 AI Agent 安装统一方法论 + git gate，让"假绿"（false green）在结构上不可发生：测试先红后绿、SonarQube + 跨 AI 双盲评审、Solomon 第三方仲裁、安全 finding 不可覆盖、git worktree 并行隔离。GitHub 41 星、原生内置 MCP server（kj_rag_query）、CLI 提供 kj rag / hu / review / worktree / solomon / adr / check 等命令，覆盖从规划、上下文、评审、并行、安全的全链路开发治理流程。

核心能力

• RAG 检索增强（kj rag）：kj rag query 把 codebase 内置为 Agent 可查询的 RAG 索引；本地 Ollama 或内置 ONNX embedder 开箱即用，云端 embedder 必须显式声明 sensitivity 并对 chunk 做 PII redact。--library 子命令提供"工程典范卡"，包含何时适用、何时不适用、规范引用，避免 Agent 惯性照搬遗留代码。
• 看板前置（HU Board）：所有工作必须先挂在 HU Board 上 —— kj hu add|move|list 自带看板，亦可对接 Linear / Trello / Jira / GitHub Issues（通过 Agent 自身 MCP 接入）；Karajan 在没装 board 时拒绝运行。ADR（架构决策记录）通过 kj adr add|list 进入 git。
• 测试先行 + 不可留红：强制 failing test 先存在；测试套件绝不留红，否则任何 commit 都被卡住。
• 确定性优先 + 跨 AI 评审：kj review --staged 先对 staged 文件跑 SonarQube（BLOCKER/CRITICAL 直接拒绝），再绑一个不同 AI 对 sha256 精确 diff 出具 verdict；没有 verdict 的 commit 不可进入（pre-commit gate）。
• Solomon 第三方仲裁：kj solomon 在 plan-AI 与 reviewer-AI 意见冲突时做第三方裁定；安全类 finding 永不可被仲裁覆盖。
• 分支隔离与并行 lane：基线分支只通过原子 PR 移动；kj worktree start|list|done 给每个并发任务一个独立 worktree lane。
• 最小权限 Agent 沙箱：被 fork 出来的 Agent 子进程只能继承自己 CLI 的 auth，绝不会泄漏云厂商 key / registry token；kj check 枚举项目可达 MCP，标记越权连接。
• 原生 MCP 暴露：安装时自动注册 kj_rag_query MCP tool，Agent 查询 codebase 的代价被压到最低，倾向"先查再写"而非"凭印象写"。

安装配置

• 环境要求：Node.js 22+、Git 仓库、至少一个支持的 AI 编程 CLI（Claude Code / Codex / Copilot / Antigravity / Cursor / OpenCode / Aider）。
• 全局安装：npm install -g @karajan-family/code（或 pnpm add -g），命令名 kj。
• 初始化：kj init，写入 karajan.yml，包含 board 选型、embedder provider、SonaQube 端点、Solomon 默认 AI、worktree 根目录等。

使用步骤

1. 绑定看板：kj hu init --provider linear（或 trello / jira / github），生成空 HU Board；亦可 kj hu import --from 批量导入 backlog。
2. 检索上下文：kj rag build 把 codebase 索引化（Ollama/ONNX 离线或云端 embedder），kj rag query "" 让 Agent 直接查索引。
3. 卡片驱动开发：每个改动前先 kj hu add ""，再让 Agent 在该 HU 下工作；Card 不在 Board 上时 Karajan 拒绝 commit。
4. 写测试 + 实现：Agent 收到任务后必须先在测试文件写 failing case，再写实现直到测试绿；任何中间红测试都会被 git gate 拦截。
5. 跑评审：kj review --staged 触发 SonarQube + 跨 AI review，没有 approved verdict 的 commit 无法进入；冲突时 kj solomon 启动第三方 AI 仲裁。
6. 并行 lane：kj worktree start 在新 worktree 里跑实验任务，kj worktree list 查看所有 lane，kj worktree done 合并回基线。
7. 收尾合并：每个 lane 完成后通过原子 PR 合入主干；kj adr add "" 写 ADR，kj check 审计 MCP 越权。

适用场景

• 多 AI 编程助手混合团队：团队同时用 Claude Code、Codex、Cursor 写代码，需要统一方法论与质量门。
• 金融/医疗/政企等强监管行业：安全 finding 不可覆盖、必须可追溯，Solomon 仲裁 + SonarQube 前置提供结构化合规。
• 大型 monorepo 重构期：多 lane 并行 worktree 隔离，避免实验性改动污染主干。
• AI Coding 教学 / 培训：用 Karajan 强制学员按 TDD / RAG / review 方法学习，避免"AI 写啥就是啥"。
• 开源项目维护：每个 contributor 提交都先过 SonarQube + 跨 AI 双审，提升合入质量。
• 多团队协作：把"卡片驱动 / 测试先行 / 评审必过"固化为工具能力而非团队公约，避免"靠自觉"。

适用人群

• 高级架构师 / Staff Engineer（治理层面规划 AI 编程流水线）
• 多 AI 工具并行的研发团队 Tech Lead
• 强监管行业（金融、医疗、政企）的 DevSecOps
• 教育 / 培训场景（教 AI 编程时代的方法论）
• 开源项目维护者
• 重构期 monorepo 负责人

工作原理

Karajan Code 把"开发治理"拆成六个 git hooks + 一组 CLI 命令。RAG 层用本地 Ollama 或内置 ONNX embedder 把 codebase 切片、向量化，Agent 通过 kj_rag_query MCP tool 在每次决策前调用，避免凭印象写。Board 层要求每个工作流都从 HU Card 开始；HU Card 与 Linear/Jira/GitHub Issues 双向同步，Karajan 在 install 时校验 board 存在，否则拒绝运行。TDD gate 在 pre-commit hook 里跑测试，发现红测试直接拒绝 commit。Review gate 串接 SonarQube（确定性）+ 跨 AI 双盲评审（语义级），对 staged diff 计算 sha256 后绑 verdict，未通过 verdict 的 commit 不进 git。Solomon gate 在 plan/review 冲突时由第三个 AI 仲裁；安全类 finding 不可被仲裁覆盖。Worktree lane 把每个并发任务隔离在独立 git worktree，减少 merge hell。所有这些以 CLI + MCP tool + git hook 形式落到本地，零 SaaS 依赖。

官方链接

• npm 包（社区版）：https://www.npmjs.com/package/karajan-code
• npm 包（family scope）：https://www.npmjs.com/package/@karajan-family/code
• GitHub 仓库：https://github.com/manufosela/karajan-code
• 官方文档：https://karajancode.com
• 公开路线图：https://planning-game-xp.web.app/public/?project=Karajan%20Code