设计哲学

→ 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     # 扫描代码，生成业务知识库

6 个核心命令

| 命令 | 用途 | 产出物位置 | |------|------|-----------| | /modus:init | 扫描项目，生成业务/团队/技术三层知识库 + 知识目录 | .codebuddy/skills/ + modus/knowledge-catalog.md | | /modus:vibe | 氛围编程，渐进式加载业务上下文后直接编码 | 直接修改代码，无新增文件 | | /modus:plan | 功能规划，两层知识检索 + 3 问澄清 + 单一 plan.md + Build 确认执行 | 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 多智能体流程，8 个 SubAgent 协作，含知识沉淀闭环 | modus/plans/active/{story-id}/ |

典型工作流

你: /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，精准命中）

三层知识结构：

| 层级 | 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（生产）
  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          ← 8 个 SubAgent Skill
│   └── 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 产出物及归档

文档

→ 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        # 修改单个配置项

License

MIT