@modus-ai/modus 0.2.4 → 0.2.6

package/schemas/harness-schema.yaml

@@ -1,91 +1,216 @@
-# Modus Harness Schema
+# Modus Harness Schema v2.0
 # 定义 /modus:harness 双 Loop 多智能体流程的产出物及调度规则
+# 与 modus-harness/SKILL.md 保持完全一致（9 个 SubAgent：SA00~SA08）
+# 更新时间：2026-05-18
+
 name: harness
-description: 双 Loop 多智能体 Harness — 全自动需求分析、开发、测试、评审、部署流程
+version: "2.0"
+description: 双 Loop 多智能体 Harness — 全自动需求分析、设计、开发、测试、评审、部署流程
+schema_version: "1.1"  # HANDOFF 协议版本（见 docs/protocol.md）
+
+# 产物根目录（v3.2）
+directories:
+  harness: "modus/stories/{story-id}/harness/"
+  knowledge: "modus/knowledge/"
+  sessions: "modus/sessions/"
 
+# SubAgent 清单（SA00~SA08，共 9 个）
+# 命名偏移说明：SA02（设计）对应 Skill modus-harness-01-5-design（插入在 01 和 02 之间），
+# 导致后续 Skill 文件名编号比 SubAgent ID 少 1。HANDOFF agent 值以 SubAgent ID 为基准。
 subAgents:
+
+  - id: "00"
+    skill: modus-harness-00-skills-builder
+    handoff_agent: "00-skills-builder"
+    name: 知识注入/提取（Skills Builder）
+    generates:
+      - "Skill 文件（modus/knowledge/biz-*/SKILL.md）"
+      - "modus/knowledge-catalog.md"
+    requires: []
+    loop: 1
+    modes:
+      - "A: 新建 Skill"
+      - "B: 增量更新 Skill"
+      - "C: 知识批量写回"
+      - "D: ARCHIVE 知识提取"
+    notes: "INIT 阶段调用模式 B 更新知识，ARCHIVE 阶段调用模式 D 提取知识"
+
   - id: "01"
-    skill: modus-analyst
+    skill: modus-harness-01-analysis
+    handoff_agent: "01-analysis"
     name: 需求分析
-    generates: 01-analysis.md
-    requires: []
+    generates: ["modus/stories/{story-id}/harness/01-analysis.md"]
+    requires: ["00-INIT"]
     loop: 1
+    gateAfter: A0   # Gate A0: 检查 01-analysis.md HANDOFF gate_status = "passed"
+    max_retry: 2    # Gate A0 失败时最多重入 2 次
 
   - id: "02"
-    skill: modus-developer
-    name: 代码开发
-    generates: 02-sprint-contract.md
+    skill: modus-harness-01-5-design
+    handoff_agent: "02-design"
+    name: 设计方案生成
+    generates: ["modus/stories/{story-id}/harness/02-design-brief.md"]
     requires: ["01"]
     loop: 1
-    gateAfter: compile  # Gate A: 编译验证
+    human_checkpoint: true   # 架构决策确认 ⏸️ 人工交互节点
+    gateAfter: A05  # Gate A0.5: 检查 02-design-brief.md HANDOFF gate_status ∈ {passed, warning}
+    max_retry: 2
 
   - id: "03"
-    skill: modus-tester
-    name: 代码测试
-    generates: 03-test-report.md
+    skill: modus-harness-02-dev
+    handoff_agent: "03-dev"
+    name: 代码开发
+    generates: ["modus/stories/{story-id}/harness/03-sprint-contract.md"]
     requires: ["02"]
     loop: 1
-    parallel: ["03", "04", "05"]  # 与 04/05 并行
+    gateAfter: A    # Gate A: 执行 constitution.build_command，exit code = 0
+    max_retry: 3    # Gate A 失败时最多重入 3 次（含 Loop 2 精准重入）
 
   - id: "04"
-    skill: modus-perf-auditor
-    name: 性能审计
-    generates: 04-perf-report.md
-    requires: ["02"]
+    skill: modus-harness-03-test
+    handoff_agent: "04-test"
+    name: 代码测试（单元测试）
+    generates: ["modus/stories/{story-id}/harness/04-test-report.md"]
+    requires: ["03"]
     loop: 1
-    parallel: ["03", "04", "05"]
+    parallel: ["04", "05", "06"]  # 与 SA05/SA06 并行执行
+    gateAfter: B    # Gate B: 三份报告全部 artifact_status=complete
+    max_retry: 2
 
   - id: "05"
-    skill: modus-security-auditor
-    name: 安全审计
-    generates: 05-security-report.md
-    requires: ["02"]
+    skill: modus-harness-04-perf
+    handoff_agent: "05-perf"
+    name: 性能审计
+    generates: ["modus/stories/{story-id}/harness/05-perf-report.md"]
+    requires: ["03"]
     loop: 1
-    parallel: ["03", "04", "05"]
+    parallel: ["04", "05", "06"]
+    gateAfter: B
+    max_retry: 2
 
   - id: "06"
-    skill: modus-reviewer
-    name: 代码评审
-    generates: cr-report.md
-    requires: ["03", "04", "05"]  # Gate B: 等待 03/04/05 全部完成
-    loop: 2
+    skill: modus-harness-05-security
+    handoff_agent: "06-security"
+    name: 安全审计
+    generates: ["modus/stories/{story-id}/harness/06-security-report.md"]
+    requires: ["03"]
+    loop: 1
+    parallel: ["04", "05", "06"]
+    gateAfter: B    # Gate B 额外条件：安全报告无严重/高危未修复问题（强制拦截）
+    max_retry: 2
 
   - id: "07"
-    skill: modus-deployer
+    skill: modus-harness-06-review
+    handoff_agent: "07-review"
+    name: 代码评审（CR）
+    generates: ["modus/stories/{story-id}/harness/cr-report.md"]
+    requires: ["04", "05", "06"]  # Gate B 通过后触发
+    loop: 1                        # CR 在 Loop 1 执行；Loop 2 是对 SA03 的精准重入，非 CR 重跑
+    gateAfter: C    # Gate C: cr-report.md HANDOFF issues 为空或全为 P3
+
+  - id: "08"
+    skill: modus-harness-07-deploy
+    handoff_agent: "08-deploy"
     name: 部署发布
-    generates: 07-deploy-status.md
-    requires: ["06"]
-    loop: 2
-    gateAfter: noPnPProblems  # Gate C: cr-report.md 无 P1/P2
+    generates: ["modus/stories/{story-id}/harness/08-deploy-status.md"]
+    requires: ["07"]  # Gate C 通过后触发
+    loop: 1
+    human_checkpoint: true  # prd 环境等待人工确认
 
+# Gate 规则（强制，不可跳过）
 gates:
-  compile:
-    description: 编译验证
-    condition: "项目构建工具编译，exit code = 0"
+  A0:
+    description: "需求分析质量门"
+    checkFile: "01-analysis.md"
+    checkField: "gate_status"
+    condition: "gate_status = \"passed\""
+    onFail: retrySubAgent01
+    maxRetry: 2
+
+  A05:
+    description: "设计方案确认门（Gate A0.5）"
+    checkFile: "02-design-brief.md"
+    checkField: "gate_status"
+    condition: "gate_status ∈ {passed, warning}"
     onFail: retrySubAgent02
-    maxRetry: 3
+    maxRetry: 2
 
-  noPnPProblems:
-    description: 代码评审质量门
-    condition: "cr-report.md 中 P1 和 P2 问题数量为 0"
-    onFail: retryFromSubAgent02
+  A:
+    description: "编译验证门"
+    checkMethod: "execute constitution.build_command"
+    condition: "exit_code = 0"
+    onFail: retrySubAgent03
     maxRetry: 3
 
+  B:
+    description: "并行审计完成门"
+    checkFiles:
+      - "04-test-report.md"
+      - "05-perf-report.md"
+      - "06-security-report.md"
+    checkField: "artifact_status"
+    condition: "三份报告 artifact_status 均为 complete，且各 gate_status ≠ failed"
+    extraCondition: "06-security-report.md 中无严重/高危未修复问题（强制拦截）"
+    onFail: "继续等待（文件未齐）；gate_status=failed 则重入对应 SubAgent（最多 2 次）；超时 30 分钟上报用户"
+    timeout: "30m"
+
+  C:
+    description: "代码评审质量门"
+    checkFile: "cr-report.md"
+    checkField: "issues"
+    condition: "issues 数组为空，或全部 level 为 P3"
+    onFail: triggerLoop2
+    maxLoop2Retries: 3
+
+# Loop 2 精准重入规则
 loop2:
-  trigger: "cr-report.md 中存在 P1 或 P2 问题"
-  action: "定位涉及的 Sprint，精准重入 SubAgent 02（非全量重跑）"
-  rerunPath: ["02", "Gate A", "03+04+05", "06"]
-  maxLoops: 3
-  onMaxLoopsReached: "暂停流程，上报用户，请求人工介入"
+  trigger: "Gate C 失败（cr-report.md HANDOFF issues 含 P1 或 P2）"
+  sprintLocating:
+    primary: "issues[].affected_sprint 字段（整数，如 Sprint 2）"
+    fallback: "affected_sprint 缺失或为 0 时，重跑全量 Sprint（保守策略）"
+    multiple: "多个 issue 指向不同 Sprint 时，取编号并集一并重跑"
+  rerunPath: ["03（受影响 Sprint）", "Gate A", "04+05+06（并行）", "07"]
+  maxRetries: 3
+  onMaxRetriesReached: "暂停流程，上报用户，请求人工介入，写入 .harness-state.yaml"
 
-finalReview:
-  trigger: "Gate C 通过（cr-report.md 无 P1/P2）"
-  action: "等待人工 Final Review，确认后合入主干"
+# ARCHIVE 阶段（SA08 完成后触发，进入 Human Final Review 等待前执行）
+archive:
+  trigger: "SA08 部署完成（08-deploy-status.md artifact_status=complete）"
+  callSubAgent: "00（模式 D：知识提取）"
+  sourceArtifacts:
+    - "01-analysis.md"
+    - "02-design-brief.md"    # 提取架构决策 [decision] 知识
+    - "03-sprint-contract.md"
+    - "04-test-report.md"
+    - "05-perf-report.md"
+    - "06-security-report.md"
+    - "cr-report.md"
+    - "08-deploy-status.md"
+  knowledgeTypes:
+    - "[decision] - 来自 02-design-brief.md/03-sprint-contract.md 的技术选型"
+    - "[guideline] - 来自 08-deploy-status.md 的上线操作规范"
+    - "[pitfall] - 来自 cr-report.md P2/P3 和 04/05 报告高风险项"
+    - "[process] - 来自 01-analysis.md 的业务流程"
+    - "[invariant] - 来自 cr-report.md 和 01-analysis.md 的业务约束"
 
+# 断点续跑状态文件
+stateFile:
+  path: "modus/stories/{story-id}/harness/.harness-state.yaml"
+  fields:
+    story_id: "string"
+    loop: "integer（1 或 2）"
+    completed_agents: "string[]（已完成的 SubAgent ID 列表）"
+    current_agent: "string（当前正在执行的 SubAgent，空=全部完成）"
+    loop2_triggers: "Issue[]（Loop 2 触发的 P1/P2 问题列表）"
+    last_updated: "ISO 8601 时间戳"
+
+# 超时配置
 timeout:
-  perSubAgent: 15m
+  perSubAgent: "15m"
+  parallelGroup: "30m（SA04/05/06 并行组整体超时）"
   action: "汇报卡点，询问用户是否重试"
 
-directories:
-  active: modus/plans/active
-  archive: modus/plans/archive
+# Human Final Review
+finalReview:
+  trigger: "Gate C 通过 + ARCHIVE 完成"
+  action: "输出推荐 Commit Message，等待人工确认合入主干"

package/schemas/knowledge-schema.yaml

@@ -4,6 +4,49 @@
 name: knowledge
 description: 知识体系 schema — 知识目录索引、Skill frontmatter、知识条目类型
 
+# ─────────────────────────────────────────
+# config.yaml scanRules 结构
+# ─────────────────────────────────────────
+scan_rules:
+  description: |
+    /modus:init Step 2 执行代码扫描时的规则配置，遵循公式：
+    最终扫描文件 = (include_extensions 匹配的文件) - (exclude_patterns 排除的路径)
+    各规则来源叠加计算（类似 .gitignore 的分层覆盖机制）。
+  location: "modus/config.yaml → scanRules 字段"
+  fields:
+    - name: include_extensions
+      type: list[string]
+      description: 要扫描的文件后缀名列表。默认值覆盖主流后端/前端语言。
+      default: [".java", ".kt", ".py", ".ts", ".tsx", ".js", ".go", ".rs", ".php", ".rb", ".swift", ".scala"]
+
+    - name: exclude_patterns
+      type: list[string]
+      description: |
+        glob 格式的排除模式，支持 ** 通配符。
+        默认已排除：构建产物（target/、build/、dist/）、IDE 配置（.idea/、.vscode/）、
+        依赖目录（node_modules/）、生成代码（generated/、*Generated.java）。
+        用户可在 config.yaml 中追加项目特有的排除模式。
+      default:
+        - "target/**"
+        - "build/**"
+        - "dist/**"
+        - "node_modules/**"
+        - ".idea/**"
+        - ".vscode/**"
+        - "generated/**"
+        - "**/*Generated.java"
+        - "*.lock"
+
+    - name: include_paths
+      type: list[string]
+      required: false
+      description: 额外需要扫描的目录，默认扫描项目 src/ 下全部内容。用于将 plugins/、extensions/ 等非标准目录纳入扫描。
+
+    - name: exclude_domain_patterns
+      type: list[string]
+      required: false
+      description: 强制排除的包名 glob 模式（如 "com.example.legacy.**"），用于将不希望被 modus 管理的历史代码排除在域识别之外。
+
 # ─────────────────────────────────────────
 # knowledge-catalog.md 结构
 # ─────────────────────────────────────────
@@ -94,6 +137,38 @@ skill_frontmatter:
       description: 知识层级（仅 team-conventions 和 tech-wiki 需要填写）
       values: ["0-T", "1"]
 
+    - name: upstream_skills
+      type: list
+      required: false
+      description: |
+        本 Skill 依赖的上游 Skill 列表（仅填写直接依赖，不递归填写传递依赖）。
+        当上游 Skill 的 last_hash 发生变化或 maturity 降级时，本 Skill 的 stale_cascade 自动置为 true。
+        格式：["modus-biz-order", "modus-biz-user"]
+      default: []
+
+    - name: stale_cascade
+      type: boolean
+      required: false
+      description: |
+        联动失效标记。当任一 upstream_skills 中的 Skill 发生 hash 变更或 maturity 降级时，
+        由 vibe/plan 的防腐机制自动将此字段置为 true。
+        置为 true 后，引用本 Skill 前须先执行 /modus:refresh 验证依赖链是否仍然有效，
+        确认无误后由 skill-creator 模式 B 将此字段重置为 false。
+      default: false
+
+    - name: external_deps
+      type: map
+      required: false
+      description: |
+        本 Skill 的规范依赖外部库的版本范围。当 pom.xml / package.json 中对应库发生
+        跨大版本升级（major version 变化）时，自动触发 stale 降级。
+        格式：key 为库名，value 为 semver 范围（如 "~2.7"、">=3.0 <4.0"）
+      example:
+        spring-boot: "~2.7"
+        mybatis-plus: ">=3.5"
+        dubbo: "~3.1"
+      default: {}
+
 # ─────────────────────────────────────────
 # 知识条目类型（五类 MECE）
 # ─────────────────────────────────────────
@@ -147,10 +222,45 @@ maturity_lifecycle:
     verified_decay:
       condition: "verified 且距 last_referenced 超过 6 个月"
       action: "降为 draft，追加注释 ⚠️ 6个月未引用，可能已过时"
+    upstream_cascade_decay:
+      condition: "upstream_skills 中任一 Skill 的 last_hash 发生变化，或其 maturity 降级"
+      action: "将本 Skill 的 stale_cascade 置为 true，在 knowledge-catalog 中标注 ⚠️ 上游变更待验证"
+    external_dep_decay:
+      condition: "pom.xml 或 package.json 中，external_deps 里某库的 major version 发生变化"
+      action: "将本 Skill maturity 降为 stale，追加注释 ⚠️ 外部依赖 {lib} 升级（{old} → {new}），规范需验证"
 
   decay_check_trigger:
-    - "00-skills-builder 模式 D 执行时"
+    - "modus-skill-creator（SubAgent 00）模式 D 执行时"
     - "可手动触发：/modus:init --lint"
+    - "vibe/plan Step 3 防腐检查时（仅检查 stale_cascade，不全量扫描）"
+    - "modus-init 执行后自动扫描 pom.xml/package.json 版本变化触发 external_dep_decay"
+
+# ─────────────────────────────────────────
+# external_deps 自动提取规范
+# ─────────────────────────────────────────
+external_deps_extraction:
+  description: |
+    /modus:init 生成 Skill 时，自动从构建文件中提取该域依赖的外部库版本，
+    写入 Skill frontmatter 的 external_deps 字段。
+  source_files:
+    java: "pom.xml（根目录 + 各 module 级别）"
+    node: "package.json（各包目录）"
+    python: "pyproject.toml / requirements.txt"
+  extraction_logic: |
+    1. 扫描该域 key_files 中的 import/require 语句
+    2. 提取引用了 pom.xml/package.json 中声明的第三方库（排除标准库）
+    3. 按引用频次排序，取前 5 个高频库
+    4. 从构建文件中读取对应库的当前版本，转为 semver 范围（固定 major.minor，不锁 patch）
+    5. 写入 frontmatter: external_deps: {lib: version-range}
+  version_range_format:
+    example_input: "spring-boot-starter 2.7.14"
+    example_output: "spring-boot: \"~2.7\""
+    rule: "major.minor 相同则用 ~minor，跨 minor 用 >=min <max"
+  decay_detection: |
+    modus update / /modus:init --lint 执行时：
+    1. 重新读取 pom.xml/package.json 中 external_deps 列出的库的当前版本
+    2. 比对 major version：若发生变化（如 2.x → 3.x），触发 external_dep_decay
+    3. 将受影响的 Skill 降级为 stale，在 knowledge-catalog 中标注 ⚠️
 
 # ─────────────────────────────────────────
 # HANDOFF 块格式（Harness 产物交接协议）

package/templates/agents/modus-analyst.md

@@ -9,6 +9,6 @@ enabled: true
 
 读取并严格遵循 `.codebuddy/skills/modus-analyst/SKILL.md` 中的执行规范。
 
-产出物路径：`modus/plans/active/{story-id}/01-analysis.md`
+产出物路径：`modus/stories/{story-id}/harness/01-analysis.md`
 
 产出物头部必须包含 HANDOFF 块，包含 `agent`、`story_id`、`domains`、`risk_level`、`key_constraints`、`skill_refs`、`gate_status` 字段。

package/templates/behavior-guard.md

@@ -0,0 +1,165 @@
+# Modus Behavior Guard
+
+> 安装位置：`modus/behavior-guard.md`（由 `/modus:init` 创建）  
+> 加载时机：所有 Modus 命令 Step 0 读取，与 `modus/config.yaml` 同级  
+> 来源：直接借鉴 [Andrej Karpathy's LLM coding guidelines](https://x.com/karpathy/status/2015883857489522876)，适配 Modus/Java 上下文
+
+---
+
+这是对所有 Modus SubAgent 生效的**全局行为约束**。优先级低于 `constitution.hard_rules`（项目技术规则），高于任何 Skill 中的建议。
+
+**权衡声明：** 这些原则偏向谨慎而非速度。对于显然的单步操作，使用判断力。
+
+---
+
+## 1. Think Before Coding
+
+**不假设。不隐藏困惑。暴露权衡。**
+
+开始实现前：
+- 明确说出你的假设。如果不确定，问。
+- 如果存在多种解读，呈现它们，不要静默选择。
+- 如果有更简单的方案，说出来。该推回时推回。
+- 如果有不清楚的地方，停下来。说明困惑是什么。问。
+
+**modus 场景示例：**
+
+❌ 错误：直接按猜测的域开始生成代码
+✅ 正确：`[已匹配 order 域 · 置信度 92%]` → 继续；或展示候选列表等待确认
+
+❌ 错误：用户说「做个导出功能」，直接生成完整导出模块
+✅ 正确：
+```
+「导出功能」可能意味着：
+  A. 接口返回分页 JSON（最简，当前 Skill 中无导出相关记录）
+  B. 后台任务生成文件+邮件通知（需新 MQ Topic）
+  C. 前端直接下载 CSV（需 Facade 层新接口）
+哪种更符合你的期望？
+```
+
+---
+
+## 2. Simplicity First
+
+**最少代码解决问题。没有投机性内容。**
+
+- 不实现未被要求的功能。
+- 单次使用的代码不抽象。
+- 未被要求的"灵活性"或"可配置性"不加。
+- 不可能发生的场景不做错误处理。
+- 如果写了 200 行但 50 行能做到，重写。
+
+自我检验：「资深工程师会说这过于复杂吗？」如果是，简化。
+
+**modus 场景示例：**
+
+❌ 错误：用户说「加个状态校验」，生成了 Strategy 模式 + 枚举工厂 + 抽象类体系
+✅ 正确：在 Service 方法头加一行 `if (!order.canTransit(targetStatus)) throw new BizException(...);`
+
+❌ 错误：modus-init 对 50 个文件的项目也跑 5 轮全量扫描 + SubAgent 并行
+✅ 正确：先读目录结构，按实际发现的域数量决定深度
+
+---
+
+## 3. Surgical Changes
+
+**只动必须动的地方。只清理自己的垃圾。**
+
+修改已有代码时：
+- 不「顺手优化」相邻代码、注释或格式。
+- 不重构未损坏的东西。
+- 匹配现有代码风格，即使你会选择不同方式。
+- 发现无关的死代码，提及——不删除。
+
+你的改动产生孤儿时：
+- 删除**你的改动**让其变得无用的 import/变量/方法。
+- 不删除原本就存在的死代码，除非被要求。
+
+检验标准：每一行改动都必须能追溯到用户的请求。
+
+**modus 场景示例：**
+
+❌ 错误：用户让修一个 NPE bug，顺便把整个方法改成 Optional 链式 + 加了 log + 补了注释
+✅ 正确：只加 `if (order == null) throw new BizException(ORDER_NOT_FOUND);`，其余不动
+
+❌ 错误：vibe 编码完成后自动更新 Skill 文件（用户没要求更新文档）
+✅ 正确：缓冲到 pending-knowledge.yaml，等 git commit 时统一沉淀
+
+---
+
+## 4. Goal-Driven Execution
+
+**定义成功标准。循环直到验证通过。**
+
+将任务转化为可验证的目标：
+- 「加个校验」→「为无效输入写测试，然后让测试通过」
+- 「修这个 bug」→「写出能复现的测试，然后让它通过」
+- 「重构 X」→「确保重构前后测试都通过」
+
+多步骤任务，先陈述简短计划：
+```
+1. [步骤] → 验证：[检查项]
+2. [步骤] → 验证：[检查项]
+3. [步骤] → 验证：[检查项]
+```
+
+强成功标准让 Agent 独立循环完成。弱标准（「让它能跑」）需要反复澄清。
+
+**modus 场景示例：**
+
+❌ 错误：`/modus:vibe 加批量审批` → 直接开始写代码，没有说明"完成"意味着什么
+✅ 正确：
+```
+任务目标：实现批量审批接口，支持最多 50 条订单同时审批
+完成标准：
+  · mvn test -Dtest=BatchApproveServiceTest 通过
+  · 并发场景下不产生重复审批（分布式锁验证）
+  · 影响范围：仅 OrderService + OrderFacade，不触及其他文件
+```
+
+---
+
+---
+
+## 5. Token Budget Guard
+
+**有意识地使用 token。大操作前声明预算。**
+
+Token 是 AI 工作流的核心成本约束。每次命令执行前，应在内部估算本次的 token 消耗范围，避免不必要的全量加载。
+
+**Modus 各步骤 token 预算参考：**
+
+| 操作 | 估算 token | 说明 |
+|------|-----------|------|
+| Level 1：读 knowledge-catalog | ~200 | 仅目录索引，所有命令必须执行 |
+| Level 2：读 1 个业务 Skill | ~3,000 | 按需加载，不相关的域不读 |
+| Level 3：读 1 个实际代码文件 | ~500–2,000 | 仅在编码时按需读取 |
+| 全量加载（8 个业务 Skill） | ~24,000 | 应避免——三级加载 vs 全量差约 **10×** |
+| behavior-guard + config.yaml | ~500 | Step 0 固定成本 |
+| Design Brief（Simple） | ~200 | 内联生成，不读额外文件 |
+| Design Brief（Medium/Complex） | ~1,000 | 调用 design-brief Skill |
+
+**决策规则：**
+- 若任务只涉及 1 个域 → 只读该域 Skill（Level 2 成本 = ~3,000 tokens）
+- 若置信度 < 85% 涉及多域 → 先确认再加载，不预先全量加载
+- 若 Skill 已加载但任务无关 → 不重复读取，复用上下文中已有的内容
+
+自我检验：「本次操作有没有读了不必要的文件？」如果有，下次先匹配域再加载。
+
+**modus 场景示例：**
+
+❌ 错误：vibe 任务只涉及 order 域，但读了全部 8 个业务 Skill（~24,000 tokens）
+✅ 正确：Level 1 读目录 → 匹配 order 域 → Level 2 仅读 order Skill（~3,200 tokens）
+
+❌ 错误：连续 3 次 vibe 都重新读 behavior-guard.md 和 config.yaml
+✅ 正确：同一 session 中，Step 0 内容已在上下文，不重复读取
+
+---
+
+## 这些原则生效时的表现
+
+- **diff 中没有多余改动** — 只有被请求的变更
+- **第一次就写简单代码** — 不因过度设计而返工
+- **澄清问题在实现前提出** — 不是在出错后
+- **干净的 PR，没有顺手重构** — 每行改动都有来源
+- **token 消耗在合理范围** — 三级加载优于全量加载，同 session 不重复读取