JSPM

Modus — Business-grounded AI coding accelerator for CodeBuddy IDE

项目简介

Spring 出现之前，每个 Java 项目都在重复解决同一批问题：对象怎么管理、事务怎么处理、依赖怎么注入——有了 Spring，这些问题不再属于「每个项目」，而是属于「框架」。

AI Coding 正处在 Spring 出现之前的阶段。

每个团队都在独立回答同一批问题：AI 怎么理解我们的业务上下文？编码规范怎么让 AI 遵守？多人协作时 AI 行为怎么保持一致？最佳实践怎么沉淀下来不随人员流动消失？没有框架，每个项目自己摸索，低水平重复，经验留在个人脑袋里。

Modus 要做 AI Coding 的 Spring。

框架的核心：Command 串联一切

Modus 对外只暴露 Command（斜杠命令），这是框架与使用者之间唯一的契约。一条命令背后，框架自动完成依赖注入——专业分工的 SubAgent、携带团队最佳实践的 Skill、守住架构红线的 Rule、积累业务知识的知识体系，全部在命令触发时按需装配：

/modus:harness  ← 使用者只需知道这一行
      │
      ├── SubAgent（专业分工智能体）  需求分析 / 编码 / 测试 / 安全审计，各司其职
      ├── Skill  （流程知识文档）     团队执行规程，一次沉淀，跨项目、跨人员共享复用
      ├── Rule   （项目宪法）         架构约束与编码规范，AI 不可逾越的硬性边界
      └── 知识体系（三层 Skill）      业务域 / 技术决策 / 团队规范，随每次交付自动积累

就像 Spring 用 @Transactional 解决了所有项目的事务问题，Modus 用 /modus:harness 解决了所有团队的全流程 AI 研发问题。你不需要理解内部机制，框架替你处理好了。

框架的价值：解决 AI Coding 的四个根本性问题

结果是： 第 1 次用 Modus 开发约 45 分钟，第 N 次约 15 分钟——不是因为 AI 变聪明了，而是框架帮你把项目知识、团队规范、执行流程都预装好了，冷启动成本趋近于零。

框架的生态：覆盖研效全链路每个节点

就像 Spring 从 Core 扩展到 MVC、Security、Cloud，Modus 的目标是为研效全链路每个节点提供开箱即用的 Command 与配套资产（当前已完成代码开发全链路，各节点持续扩充中）：

每个节点均有结构化产出物（01-analysis.md → 07-deploy-status.md）作为决策留痕，支持断点续跑，确保 AI 行为可追溯、可审计、可接手。

Token 效率：三级渐进加载 vs 全量加载

Modus 的核心设计理念之一是按需加载，而非全量预加载。三级渐进加载策略在实际使用中相比全量加载可节省大量 token：

节省幅度： 单域场景三级加载约为全量的 **15%**，双域约为 **28%**。

这与 claude-context MCP 的语义搜索思路一致——不是把整个代码库推入 context，而是精准检索相关内容。Modus 通过知识分层 + 置信度域匹配实现同等效果，无需向量数据库基础设施。

详细评估数据见 evaluation/metrics.yaml。

建设能力

项目冷启动

SubAgent

Commands

Skills

目的

1. 三层知识体系，分层按需加载
2. Skill 结构统一，防腐可复用
3. 项目宪法，全局强约束落地
4. 自动梳理老项目，零人工整理
5. 多平台规则融合，存量不浪费

需求创建

Commands

Skills

目的

1. TAPD 直连，零手动录入
2. 四维评分，精准路由模式
3. 难度分级，工具按需匹配

评估设计

SubAgent

Commands

Skills

目的

1. 设计前置，质量风险左移
2. 四层文档，职责清晰可追溯
3. 规格库唯一权威来源
4. 断点续跑，决策全程留痕

代码开发

SubAgent

Commands

Skills

目的

1. 上下文感知，消除冷启动
2. 编译 Gate，代码质量前置
3. Sprint 分层，逐步可验证
4. Token 节省约 59%

测试

SubAgent

Skills

目的

1. 三专项并行，节省 2/3 时间
2. P1/P2 自动闭环，无需人工协调
3. 专项分工，覆盖无死角
4. 质量标准客观统一可量化

部署发布

SubAgent

Skills

目的

1. 灰度逐级，prd 人工确认
2. 上线监控，异常及时感知
3. ARCHIVE 知识沉淀，经验复利积累
4. 全流程产出物，上线有据可查

设计哲学

→ context-aware 不 context-blind         — 编码前先加载业务上下文
→ business-grounded 不 feature-fragmented — 以领域知识驱动 AI
→ spec-driven 不 chat-driven             — 变更有文档，决策有留痕
→ multi-agent 不 single-brain            — 专业分工，各司其职
→ iterative 不 waterfall                 — 随时更新 Skill，随时归档
→ knowledge-compounding 不 cold-start    — 每次执行都在积累，越用越快

快速开始

需要 Node.js 18.0.0 或以上版本。

全局安装并初始化：

npm install -g @modus-ai/modus
cd your-project
modus init      # CLI 初始化，生成框架文件和配置

然后在 CodeBuddy IDE 对话框中运行：

/modus:init     # 扫描代码，生成业务知识库

7 个核心命令

典型工作流

你: /modus:init
AI: 识别到 3 个业务域：order, payment, user
    生成 Business Skills (Layer 2)...
    生成 modus-team-conventions (Layer 0-T)...
    生成 modus-tech-wiki (Layer 1)...
    生成 modus/knowledge-catalog.md（知识全景索引）
    ✅ 初始化完成 | 建议填写 modus/config.yaml 的 constitution 字段

你: /modus:vibe 帮我给订单模块加一个批量审批接口
AI: [Level 1] 读取知识目录（200 tokens）
    [Level 2] 加载 order 域业务知识（3000 tokens，仅此一个域）
    [Level 3] 按需读取 OrderService.java、OrderMapper.java
    我来实现批量审批接口...

你: /modus:harness https://tapd.cn/xxx/stories/view/1234567
AI: [INIT] 注入知识：order[verified] | payment[proven]
    ✅ SubAgent 01 完成 → 01-analysis.md（影响范围: 5 个类 | domains: order,payment）
    🔄 SubAgent 02 执行中...（Sprint 2/3 | token: 3/5 Skill 预算已用）
    ⏳ 并行等待 03/04/05（2/3 完成）
    ✅ Gate C 通过，无 P1/P2
    📚 ARCHIVE 完成 → 提取知识 4 条（decision:1 | pitfall:2 | guideline:1）
    ⏸️ 等待人工 Final Review

知识体系（核心竞争力）

Modus 的知识体系让 AI 从「冷启动」变为「越用越快」：

第1次开发 → 45 分钟（AI 需理解项目背景）
第N次开发 → 15 分钟（knowledge-catalog + proven Skill，精准命中）

三层知识结构：

知识成熟度： draft → verified → proven（在工作流中被引用后自动晋升，长期未引用自动衰减）

渐进加载： Level 1（catalog，200 tokens）→ Level 2（Skill，3000 tokens/个）→ Level 3（代码文件，按需），节省约 59% token。

项目宪法： modus/config.yaml 的 constitution.hard_rules 是所有 SubAgent 的最高优先级约束，一次配置，永久生效。

constitution:
  tech_stack: "Java 17 + Spring Boot 3 + MyBatis"
  build_command: "mvn clean compile -q"
  hard_rules:
    - "Mapper 接口必须在 dao 包下"
    - "金额字段使用 Long（单位：分）"

/modus:harness 流程一览

Loop 1（生产）
  INIT → SA01 需求分析 → SA02 代码开发 → Gate A（编译）
  → SA03/04/05 并行（测试/性能/安全）→ Gate B → SA06 代码评审 → Gate C

Loop 2（修复，有 P1/P2 时触发）
  精准重入受影响的 Sprint → Gate A → SA03/04/05 → SA06

收尾
  SA07 部署验证 → ARCHIVE 知识沉淀 → 人工 Final Review

每个 SubAgent 的产出物（01-analysis.md 至 07-deploy-status.md + cr-report.md）均存放在 modus/plans/active/{story-id}/，支持断点续跑。

文件结构

your-project/
├── .codebuddy/
│   ├── skills/
│   │   ├── modus-team-conventions/SKILL.md  ← Layer 0-T
│   │   ├── modus-tech-wiki/SKILL.md          ← Layer 1
│   │   ├── modus-biz-{domain}/SKILL.md       ← Layer 2（每域一个）
│   │   └── modus-harness-*/SKILL.md          ← 9 个 SubAgent Skill（SA00~SA07，含 SA01.5）
│   └── commands/modus/                       ← 斜杠命令入口
│
└── modus/
    ├── config.yaml                   ← 项目宪法
    ├── knowledge-catalog.md          ← 全景索引（~200 tokens）
    ├── specs/{domain}/spec.md        ← 主规格库（/spec 归档后）
    ├── plans/{name}/plan.md          ← /plan 唯一规划文档（含 .modus-state.yaml）
    ├── plans/active/{story-id}/      ← /harness 产出物
    ├── plans/archive/                ← /plan 归档
    ├── changes/                      ← /spec 产出物及归档
    └── sessions/
        ├── pending-knowledge.yaml    ← /vibe 发现的待沉淀知识缓冲区（/commit 时清空）
        └── vibe-log.md               ← /vibe 会话日志（append-only，多人无冲突）

文档

→ Getting Started: 安装与第一步
→ Commands Manual: 5 个命令完整用法（执行步骤、产出物、示例）
→ Concepts: 核心概念（知识分层、渐进加载、Project Constitution）
→ Harness: 双 Loop 多智能体原理（含 HANDOFF 协议、Gate 规则）
→ Knowledge: 知识体系生命周期与最佳实践
→ Commands Reference: 命令快速参考

CLI 命令

modus init              # 初始化项目（生成 .codebuddy/ 文件 + 知识目录）
modus rehook            # 修复 hook 路径（git clone 到新机器/路径后执行）
modus update            # 升级后刷新文件
modus config show       # 查看当前配置
modus config profile    # 选择启用哪些命令
modus config set        # 修改单个配置项

斜杠命令（在 IDE 对话框中使用）：

/modus:init    — 扫描代码，生成三层知识库
/modus:vibe    — 氛围编程，渐进加载上下文后直接编码
/modus:commit  — 知识感知提交：先沉淀 vibe 发现的新知识，再执行 git commit
/modus:plan    — 功能规划，生成 plan.md，Build 确认后执行
/modus:spec    — 规范驱动开发，生成 delta specs + 验收标准
/modus:auto    — 智能模式推荐：读 TAPD Story，四维评分，推荐最优模式
/modus:harness — 全自动双 Loop，9 个 SubAgent 从需求到部署全程闭环

/modus:commit 是 /modus:vibe 知识沉淀的唯一触发点。 vibe 编码过程中发现的新知识暂存于 modus/sessions/pending-knowledge.yaml，运行 /modus:commit 时统一确认后写入 Skill，git commit 与知识沉淀同步完成。

License

MIT