项目简介

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 的四个根本性问题

| AI Coding 的根本问题 | Spring 当年的解法 | Modus 的解法 | | --------------------- | ------------------------------- | ---------------------------------------------- | | AI 不了解我的项目业务 | IoC 容器统一管理依赖 | 三层知识体系，业务上下文按需注入 | | AI 不遵守我的团队规范 | AOP 切面统一处理横切关注点 | Rule 项目宪法，全局强约束，AI 不可绕过 | | AI 行为每次不一致 | 约定优于配置，标准化行为模式 | Skill 固化最佳实践，Command 保证执行路径可复现 | | 经验随人员流动消失 | Spring 生态让经验沉淀为社区标准 | 知识体系随每次交付自动积累，越用越快 |

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

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

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

| 研效节点 | 建设状态 | 代表 Command | | ---------- | --------- | ---------------------------------------------------------- | | 项目冷启动 | ✅ 已完成 | modus init — 自动扫描代码库，生成三层知识体系 | | 需求创建 | ✅ 已完成 | /modus:auto — 读取 Story，四维评分，智能推荐执行路径 | | 评估设计 | ✅ 已完成 | /modus:plan · /modus:spec — 规划设计，产出物人工确认 | | 代码开发 | ✅ 已完成 | /modus:vibe · /modus:harness — 轻量编码到全自动双 Loop | | 测试 | ✅ 已完成 | Harness 内置 — 单测 / 性能 / 安全 / CR 四路并行 | | 部署发布 | ✅ 已完成 | Harness 内置 — CI 监控 + 逐级灰度冒烟 + 上线日志监控 |

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

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

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

| 加载方式 | 典型 token 消耗 | 说明 | | ------------------------------ | --------------- | -------------------------- | | Level 1（必须） | ~200 | knowledge-catalog 目录索引 | | Level 2（按需） | ~3,000/域 | 仅加载匹配的业务 Skill | | Level 3（按需） | ~500–2,000/文件 | 编码时才读取实际源码 | | 典型单域 vibe 总计 | ~3,700 | L1 + L2 × 1 域 | | 典型双域 vibe 总计 | ~6,700 | L1 + L2 × 2 域 | | 全量加载（8 个业务 Skill） | ~24,000+ | 应避免 |

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

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

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

建设能力

项目冷启动

SubAgent

| 名称 | 说明 | | ------------------------------ | ------------------------------------------------------------------------------------------------------- | | SA00 Skills Builder SubAgent | 知识生命周期管家——初始化、增量更新、ARCHIVE 提取，五种调用模式（A/B/C/D/E）覆盖知识全流程，团队级可复用 |

Commands

| 名称 | 说明 | | ------------- | ------------------------------------------------------------------------------------- | | /modus:init | 一键扫描代码库，自动识别业务域，生成三层知识底座 + 知识全景目录，存量老项目当天可接入 |

Skills

| 名称 | 说明 | | --------------------- | ----------------------------------------------------------------------------------------- | | modus-init | 定义 /modus:init 完整执行逻辑（8 步流程、多平台扫描、Skill 生成规范），可复用到任意项目 | | modus-skill-creator | Skill 创建 / 增量更新 / 知识提取的核心引擎，被所有工作流命令共享调用 |

目的

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

需求创建

Commands

| 名称 | 说明 | | ------------- | ----------------------------------------------------------------------------- | | /modus:auto | 读取 TAPD Story，四维评分后推荐最优执行模式，自动透传上下文启动，避免工具错配 |

Skills

| 名称 | 说明 | | ------------ | ----------------------------------------------------------------- | | modus-auto | 四维评分判定树 + 模式推荐逻辑，可复用于任何需要智能分流的研效场景 |

目的

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

评估设计

SubAgent

| 名称 | 说明 | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | | SA01 需求分析 SubAgent | 将 TAPD Story 翻译为精确技术规格，方法级影响范围 + Sprint 拆分，为后续 SubAgent 建立统一上下文；产出 01-analysis.md，触发 Gate A0 | | SA02 设计方案 SubAgent | 在需求与编码之间插入设计推导层，生成 LLM 可直接消费的 02-design-brief.md，减少编码时的架构歧义；含人工确认节点，触发 Gate A0.5 |

Commands

| 名称 | 说明 | | ------------- | ---------------------------------------------------------------------------------- | | /modus:plan | 上下文感知规划，六维复杂度分级 + 精准 3 问澄清 + plan.md，Build 确认后直接驱动编码 | | /modus:spec | 规范驱动开发，生成 GIVEN/WHEN/THEN 行为规格 + 四层产出物，归档自动合并主规格库 |

Skills

| 名称 | 说明 | | -------------------- | ------------------------------------------------------------------------------------ | | modus-plan | /modus:plan 完整执行逻辑，含复杂度评估、知识检索、3 问澄清、Build 确认循环，可复用 | | modus-spec | /modus:spec 执行逻辑，含 delta specs、冲突检测、可选 verify、主规格库归档，可复用 | | modus-design-brief | 结构化设计方案生成（落盘 + 内联双模式），被 plan/spec/vibe 共享调用，可独立复用 | | modus-analyst | Harness 需求分析 SubAgent 行为定义，方法级影响范围提取 + HANDOFF 协议，可复用 | | modus-designer | Harness 设计推导 SubAgent 行为定义，架构澄清 + design-brief 生成，可复用 |

目的

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

代码开发

SubAgent

| 名称 | 说明 | | ------------------------ | -------------------------------------------------------------------------------------------------------- | | SA03 代码开发 SubAgent | 按 Sprint 逐层实现（数据 → 服务 → 编排 → 接口），编译 Gate A 自动验证（mvn compile），P1/P2 精准重入修复 |

Commands

| 名称 | 说明 | | ---------------- | ------------------------------------------------------------------------ | | /modus:vibe | 氛围编程——渐进加载业务上下文后直接编码，适合轻量任务，人工随时介入 | | /modus:harness | 全自动双 Loop 流程入口，8 个 SubAgent 从需求到部署全程闭环，一条命令驱动 |

Skills

| 名称 | 说明 | | ----------------- | -------------------------------------------------------------------------------------- | | modus-vibe | 三级渐进加载逻辑 + 编码执行规范，节省约 59% token，可复用于任意上下文感知编码场景 | | modus-harness | Harness Orchestrator 调度中枢，双 Loop 调度规则 + Gate 机制 + HANDOFF 协议，核心可复用 | | modus-developer | 代码开发 SubAgent 行为定义，Sprint 分层实现 + self-code-review + 编译验证，可复用 |

目的

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

测试

SubAgent

| 名称 | 说明 | | ------------------------ | ---------------------------------------------------------------------------------------------------------- | | SA04 代码测试 SubAgent | 三路径单元测试生成（Happy Path / 边界 / 异常），覆盖并发 + 事务 + 权限场景；与 SA05/SA06 并行执行 | | SA05 性能审计 SubAgent | 静态检测 N+1 / 大数据量 / 深分页风险，量化每个风险影响条数，高/中/低分级；与 SA04/SA06 并行执行 | | SA06 安全审计 SubAgent | 检测多租户隔离漏洞 / 权限缺失 / SQL 注入 / 敏感信息泄露，严重/高/低分级；有严重/高危问题则 Gate B 强制拦截 | | SA07 代码评审 SubAgent | 综合质量评估，P1/P2 触发 Loop 2 精准重入，唯一出口是通过 Gate C（无 P1/P2） |

Skills

| 名称 | 说明 | | ------------------------ | -------------------------------------------------------------------- | | modus-tester | 单元测试生成规范 + 三路径覆盖逻辑，可复用为独立测试 Agent | | modus-perf-auditor | N+1 检测规则库 + 性能风险分级模型，可复用为独立性能审计 Agent | | modus-security-auditor | 多租户安全规则 + SQL 注入 / 权限检查规范，可复用为独立安全审计 Agent | | modus-reviewer | CR 问题分级标准 + Loop 2 重入触发逻辑，可复用为独立代码评审 Agent |

目的

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

部署发布

SubAgent

| 名称 | 说明 | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------- | | SA08 部署发布 SubAgent | CI 监控 + 灰度逐级冒烟 + 上线后 30 分钟日志监控，prd 等待人工确认，可复用为独立部署验证 Agent；完成后触发 ARCHIVE 知识提取 |

Skills

| 名称 | 说明 | | ---------------- | ---------------------------------------------------------------------------------- | | modus-deployer | 部署验证完整流程定义（CI 状态轮询 / 冒烟测试 / 日志监控），可复用到任意 CI/CD 场景 |

目的

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 @tencent/modus-ai
cd your-project
modus init      # CLI 初始化，生成框架文件和配置

然后在 IDE 或 AI Agent 对话框中运行：

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

7 个核心命令

| 命令 | 用途 | 产出物位置 | | ---------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | /modus:init | 扫描项目，生成业务/团队/技术三层知识库 + 知识目录 | modus/knowledge/biz-*/SKILL.md（权威源）+ .codebuddy/skills/（平台适配桩）+ modus/knowledge-catalog.md | | /modus:vibe | 氛围编程，三级渐进加载业务上下文后直接编码，节省约 59% token | 直接修改代码，编码发现的新知识暂存 modus/sessions/pending-knowledge.yaml | | /modus:commit | 知识感知提交：沉淀 vibe 会话发现的新知识到 Skill，再执行 git commit | modus/sessions/pending-knowledge.yaml（清空后写入 Skill） | | /modus:plan | 功能规划，两层知识检索 + 3 问澄清 + plan.md + Build 确认执行 | Story 模式：modus/stories/{story-id}/plan.md；独立模式：modus/plans/{name}/plan.md | | /modus:spec | 规范开发，delta specs + GIVEN/WHEN/THEN 验收，含可选 verify + 冲突检测 | modus/changes/{name}/，归档合并到 modus/specs/ | | /modus:auto | 智能模式推荐：读 TAPD Story，四维评分，推荐 vibe/plan/spec/harness | 启动所选模式后按该模式产出 | | /modus:harness | 全自动双 Loop 多智能体流程，9 个 SubAgent（SA00~SA08）协作，含知识沉淀闭环 | modus/stories/{story-id}/harness/ |

典型工作流

你: /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: [知识注入] order[verified] | payment[proven]
    ✅ [需求分析] 完成 → 01-analysis.md（影响范围: 5 个类 | domains: order,payment | Gate A0: passed）
    ⏸️ [设计方案] 02-design-brief.md 就绪 — 架构决策: 3 个，请确认后继续（Gate A0.5）
    ✅ [代码开发] 完成 → 03-sprint-contract.md（Sprint 3/3 | Gate A: passed）
    ⏳ [并行审计] 单测/性能/安全 执行中（2/3 完成）→ Gate B
    ✅ [代码评审] Gate C 通过，无 P1/P2
    📚 [ARCHIVE] 提取知识 4 条（decision:1 | pitfall:2 | guideline:1）
    ⏸️ [部署发布] prd 等待人工确认 → Final Review

知识体系（核心竞争力）

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

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

三层知识结构：

| 层级 | Skill 文件 | 内容 | 生命周期 | | --------- | ------------------------ | -------------------------------- | ----------------------------- | | Layer 0-T | modus-team-conventions | 编码规范、提交规范、硬性约束 | 人工维护为主 | | Layer 1 | modus-tech-wiki | 架构决策、反模式库（跨项目积累） | 工作流 ARCHIVE 自动积累 | | Layer 2 | modus-biz-{domain} | 领域模型、业务规则、API 契约 | 每次 plan/spec/harness 后回写 |

知识成熟度： 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（生产）
  SA00 INIT（知识注入 + Skill 更新）
  → SA01 需求分析   → [Gate A0]  gate_status="passed" 才继续
  → SA02 设计方案   → [Gate A0.5] 含人工架构决策确认 ⏸️
  → SA03 代码开发   → [Gate A]   mvn compile exit_code=0，失败自修复，最多 3 次
  → SA04/SA05/SA06 并行（单测 / 性能 / 安全审计）→ [Gate B]
     Gate B 额外条件：06-security-report.md 无严重/高危问题（强制拦截）
  → SA07 代码评审   → [Gate C]  无 P1/P2 方可放行

Loop 2（精准重入，Gate C 发现 P1/P2 时触发）
  定位受影响 Sprint（by issues[].affected_sprint）
  精准重入 SA03 受影响 Sprint → Gate A → SA04/SA05/SA06 → SA07 → Gate C
  最多重试 3 次，超限上报用户

收尾
  SA08 部署验证 ⏸️（prd 人工确认）→ ARCHIVE 知识提取 → 人工 Final Review

| Gate | 检查对象 | 通过条件 | | ---- | ---------------------------- | ----------------------------------------- | | A0 | 01-analysis.md HANDOFF | gate_status = "passed" | | A0.5 | 02-design-brief.md HANDOFF | gate_status ∈ {passed, warning} | | A | 编译命令 | exit_code = 0 | | B | 04/05/06 三份报告 HANDOFF | artifact_status 均完成且无安全严重/高危 | | C | cr-report.md HANDOFF | issues 为空或全为 P3 |

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

文件结构

your-project/
├── .codebuddy/
│   ├── skills/
│   │   ├── modus-team-conventions/SKILL.md  ← Layer 0-T（平台适配桩，权威源在 modus/knowledge/）
│   │   ├── modus-tech-wiki/SKILL.md          ← Layer 1（平台适配桩）
│   │   ├── modus-biz-{domain}/SKILL.md       ← Layer 2（引用桩，权威源在 modus/knowledge/biz-*/）
│   │   └── modus-harness-*/SKILL.md          ← 9 个 SubAgent Skill（SA00~SA08）
│   └── commands/modus/                       ← 斜杠命令入口
│
└── modus/
    ├── config.yaml                           ← 项目宪法
    ├── knowledge-catalog.md                  ← 全景索引（~200 tokens）
    ├── knowledge/biz-{domain}/SKILL.md       ← 业务知识（Single Source of Truth，v3.2）
    ├── stories/{story-id}/harness/           ← /harness 产出物（01-analysis.md → cr-report.md → 08-deploy-status.md）
    ├── plans/{name}/plan.md                  ← /plan 产出物
    ├── plans/archive/                        ← /plan 归档
    ├── changes/                              ← /spec 产出物及归档
    ├── specs/{domain}/spec.md               ← 主规格库（/spec 归档后）
    └── sessions/                             ← 首次运行 /modus:vibe 后自动创建
        ├── pending-knowledge.yaml            ← /vibe 发现的待沉淀知识缓冲区
        └── 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