moai-foundation-core

MoAI Foundation Core

支撑 MoAI-ADK 的 AI 驱动开发工作流的基础原则和架构模式。

核心理念：通过经过验证的模式和自动化工作流，实现质量优先、领域驱动、模块化且高效的 AI 开发。

快速参考

什么是 MoAI Foundation Core？

确保 AI 驱动开发具备质量、效率和可扩展性的六项基本原则：

1. TRUST 5 框架 - 质量门禁系统（Tested、Readable、Unified、Secured、Trackable）
2. SPEC-First DDD - 规范驱动的领域驱动开发工作流
3. 委派模式 - 通过专用 Agent 编排任务（绝不直接执行）
4. 令牌优化 - 200K 预算管理和上下文效率
5. 渐进式披露 - 三层知识交付（快速、实现、高级）
6. 模块化系统 - 文件拆分和参考架构，支持可扩展性

快速访问：

• 质量标准见 modules/trust-5-framework.md
• 开发工作流见 modules/spec-first-ddd.md
• Agent 协作见 modules/delegation-patterns.md
• 预算管理见 modules/token-optimization.md
• 内容结构见 modules/progressive-disclosure.md
• 文件组织见 modules/modular-system.md
• Agent 目录见 modules/agents-reference.md
• 命令参考见 modules/commands-reference.md
• 安全和约束见 modules/execution-rules.md

使用场景：

• 按照质量标准创建新 Agent
• 按照结构指南开发新技能
• 编排复杂工作流
• 规划和优化令牌预算
• 设计文档架构
• 配置质量门禁

---

实现指南

1. TRUST 5 框架 - 质量保障系统

用途：通过自动化质量门禁确保代码质量、安全性和可维护性。

五大支柱：

Tested 支柱：通过特征测试确保行为得到保留，并维持全面的测试覆盖率。使用项目的测试运行器执行覆盖率测试（例如 go test -cover、pytest --cov、cargo test、npm test -- --coverage）。失败时阻止合并并生成缺失的测试。特征测试用于捕获旧代码的当前行为，而规范测试用于验证新代码的领域需求。高覆盖率可确保代码可靠性、减少生产缺陷，并在重构期间保留行为。

Readable 支柱：采用清晰且具有描述性的命名规范。运行项目的代码检查工具（例如 golangci-lint、ruff、eslint、clippy）。失败时发出警告并建议改进重构。清晰的命名有助于理解代码、团队协作和提升维护效率。

Unified 支柱：采用一致的格式和导入模式。运行项目的格式化工具（例如 gofmt、black、prettier、rustfmt）。自动格式化代码，或在失败时发出警告。一致性可以消除风格争论和合并冲突，并提升可读性。

Secured 支柱：遵循 OWASP 安全标准。通过适当的 Agent 或参考技能呈现安全问题（例如，启动一个带有安全指令的通用 Agent，或加载 moai-ref-owasp-checklist / moai-ref-llm-security 参考资料）。失败时阻止合并并要求进行安全审查。安全漏洞会带来严重的业务和法律风险。

Trackable 支柱：编写清晰且结构化的提交消息。符合 Git 提交消息正则表达式模式（Conventional Commits）。失败时建议使用正确的提交消息格式。清晰的历史记录有助于调试、审计和协作。

集成点：通过提交前钩子进行自动验证，通过 CI/CD 流水线实施质量门禁，通过 Agent 工作流进行 TRUST 5 验证（moai-foundation-quality 编排），以及通过文档记录质量指标。

详细参考：modules/trust-5-framework.md

---

2. SPEC 优先的 DDD——开发工作流

目的：通过规范驱动开发，确保在实现前明确需求。

三阶段工作流：

Phase 1 SPEC（/moai plan）：workflow-spec 生成 GEARS 格式（主要格式；EARS 保留为 6 个月的向后兼容遗留参考，适用于 88 个 v3 之前的 SPEC）。输出为 .moai/specs/SPEC-XXX/spec.md。执行 /clear 以节省 45-50K 个 token。

Phase 2 DDD（/moai run）：针对需求执行 ANALYZE，保留现有行为执行 PRESERVE，针对增强执行 IMPROVE。验证覆盖率至少达到 85%。

Phase 3 文档（/moai sync）：API 文档、架构图、项目报告。

GEARS 格式（当前表示法）：五种模式——Ubiquitous“系统范围内始终生效的要求：The shall ”；Event-driven“触发-响应要求：When the shall ”；State-driven“条件行为：While the shall ”；Where（能力门控）“受能力条件约束的行为：Where , the shall ”；Event-detected（取代已弃用的条件模态）“故障模式处理：When , the shall ”。统一复合子句：[Where ...][While ...][When ...] The <subject> shall <behavior>——三个修饰语可以任意选取并串联。<subject> 是泛指的，可以是任何名词（system、component、service、agent、function、artifact）。请参阅规范的编写指南：~/.claude/skills/moai-workflow-spec/SKILL.md §“GEARS Format”。

EARS 格式（遗留参考，向后兼容 6 个月——将于 2026-11-22 到期）：五种模式：Ubiquitous / Event-driven（WHEN/THEN）/ State-driven（WHILE）/ Unwanted（SHALL NOT）/ Optional（WHERE possible）。88 个 v3 之前的 SPEC 继续使用 EARS；对于 NEW SPEC 中残留的已弃用条件模态，lint 引擎会发出 LegacyEARSKeyword 警告（警告模式下不严格；在 moai spec lint --strict 下报错）。对于 NEW SPEC，请使用 GEARS。请参阅 modules/spec-ears-format.md（遗留参考，已弃用——请参阅 GEARS 格式指南）。

Token 预算：SPEC 占用 30K，DDD 占用 180K，文档占用 40K，总计 250K。

关键实践：在 Phase 1 后执行 /clear 以初始化上下文。

详细参考：modules/spec-first-ddd.md

---

3. 委派模式 - Agent 编排

目的：将任务委派给专用 Agent，避免直接执行。

核心原则：MoAI 必须通过 Agent() 将所有工作委派给专用 Agent。直接执行会绕过专业分工、质量关卡和令牌优化。正确的委派可将任务成功率提高 40％，并支持并行执行。

委派语法：MoAI 通过自然语言进行委派——“使用 {agent} 子 Agent 执行 {task}”——并传递完整的上下文、约束和理由。编排器绝不会传递 subagent_type 代码字面量；它会使用文字提示词启动 Agent()（或用于领域工作的 Agent(general-purpose)）。

三种模式：

依赖关系使用顺序模式：先使用 manager-spec 子 Agent 编写 SPEC，然后使用 manager-develop 子 Agent 以 SPEC 为上下文进行实现。

独立工作使用并行模式：在同一轮中启动多个 Agent(general-purpose) 队友，例如，一个接收后端指令，另一个接收前端指令，前提是工作彼此独立。

基于分析使用条件模式：使用 Explore 子 Agent 进行只读诊断，然后根据分析结果，将结果交给相应的保留 Agent（修复问题时交给 manager-develop，进行质量评分时交给 sync-auditor）。

Agent 选择：包含 1 个文件的简单任务使用 1-2 个 Agent 顺序执行。包含 3-5 个文件的中等任务使用 2-3 个 Agent 顺序执行。包含 10 个以上文件的复杂任务使用 5 个以上 Agent 混合执行。领域特定工作（后端 / 前端 / 安全 / 性能 / 重构）在 run-phase 中由 manager-develop 处理，或由每次启动时使用 .claude/rules/moai/workflow/archived-agent-rejection.md 中领域白名单的 Agent(general-purpose) 处理。

详细参考：modules/delegation-patterns.md

---

4. 令牌优化 - 预算管理

目的：通过战略性上下文管理，高效利用 200K 令牌预算。

预算分配：

SPEC 阶段占用 30K 个令牌。策略是仅加载需求，并在完成后执行 /clear。需求分析阶段只需最少的上下文。可为实现阶段节省 45-50K 个令牌。

DDD 阶段占用 180K 个令牌。策略是有选择地加载文件，只加载与实现相关的文件。实现需要深入的上下文，但不需要完整代码库。可在预算内实现规模大 70％ 的内容。

文档阶段占用 40K 个令牌。策略是缓存结果并复用模板。文档基于已完成的工作产物构建。可将冗余文件读取减少 60％。

所有阶段总计预算为 250K 个令牌。阶段之间进行分离并重置上下文，可以建立清晰的上下文边界，防止令牌膨胀。可在相同预算内支持规模大 2-3 倍的项目。

令牌节省策略：

阶段分离：在阶段之间执行 /clear，在 /moai plan 后执行以节省 45-50K 个令牌；当上下文超过 150K 时执行；在 50 条以上消息后执行。

选择性加载：仅加载必要的文件。

上下文优化：目标为 20-30K 个令牌。

模型选择：Sonnet 追求质量；Haiku 追求速度和成本效益，费率低 70％，总计可节省 60-70％。

详细参考：modules/token-optimization.md

---

5. 渐进式披露 - 内容架构

目的：采用三级知识交付，在价值与深度之间取得平衡。

三个层级：

快速参考层：投入 30 秒，了解核心原则和必要概念，约 1,000 个 token。为时间有限的用户快速提供价值。用户只需 5% 的时间即可获得 80% 的理解。

实施层：投入 5 分钟，了解工作流、实用示例和集成模式，约 3,000 个 token。通过可执行的指导，衔接概念与实践。无需深厚的专业知识，即可立即开展高效工作。

高级层：投入 10 分钟以上，深入了解技术细节、边缘情况和优化技巧，约 5,000 个 token。为复杂场景提供精通级知识。通过全面覆盖，将升级处理次数减少 70%。

SKILL.md 结构（最多 500 行）：快速参考部分、实施指南部分、高级模式部分、协同使用效果良好部分。

模块架构：SKILL.md 作为入口并包含交叉引用，modules 目录用于存放深度内容且大小不限，examples.md 用于存放可用示例，reference.md 用于存放外部链接。

超过 500 行时拆分文件：SKILL.md 中快速参考部分占 80-120 行，实施部分占 180-250 行，高级部分占 80-140 行，参考资料占 10-20 行。溢出内容放入 modules/topic.md。

详细参考：modules/progressive-disclosure.md

---

6. 模块化系统 - 文件组织

目的：采用可扩展的文件结构，支持无限量内容。

标准结构：创建 .claude/skills/skill-name/ 目录，其中包含作为核心文件且少于 500 行的 SKILL.md、用于存放扩展内容且大小不限的 modules 目录（包括 patterns.md）、用于存放可用示例的 examples.md、用于存放外部链接的 reference.md、用于存放实用工具的 scripts 目录（可选），以及 templates 目录（可选）。

文件原则：SKILL.md 保持少于 500 行，并采用渐进式披露和交叉引用。modules 目录按主题组织，不限大小，内容独立完整。examples.md 中的内容可直接复制粘贴，并带有注释。reference.md 包含 API 文档和资源。

交叉引用语法：将模块引用为 Details in modules/patterns.md，将示例引用为 Examples in examples.md#auth，将外部文档引用为 External in reference.md#api。

发现流程：SKILL.md 到主题，再到 modules/topic.md，最后深入了解。

详细参考：modules/modular-system.md

---

高级实施

详细模块参考中提供了高级模式，包括跨模块集成、质量验证和错误处理。

主要高级主题：

• 跨模块集成：结合 TRUST 5 + SPEC-First DDD
• Token 优化的委派：并行执行并重置上下文
• 渐进式 Agent 工作流：升级处理模式
• 质量验证：执行前/后验证
• 错误处理：委派失败恢复

详细参考：references/examples.md，包含可用代码示例

---

适用场景

Agents：builder-harness，用于基于基础原则生成 Agent／技能／harness；manager-spec，用于编写计划阶段内容；manager-develop，用于执行阶段实施；manager-docs，用于同步阶段文档；sync-auditor，用于独立评估 TRUST 5 质量；super-advisor，用于按需提供高推理能力咨询。

技能：moai-foundation-cc，用于编写 Claude Code 内容（技能、Agent、插件、钩子）；moai-workflow-spec，用于 GEARS 格式规范（当前规范；EARS 保留为旧版参考）；moai-workflow-ddd，用于执行 ANALYZE-PRESERVE-IMPROVE；moai-workflow-tdd，用于 RED-GREEN-REFACTOR 循环；moai-foundation-quality，用于 TRUST 5 验证编排；moai-foundation-thinking，用于战略推理，以及通过 ultrathink 关键词启用 Adaptive Thinking。

工具：AskUserQuestion，用于直接与用户互动并澄清需求。

命令：/moai plan，用于 SPEC-First 阶段 1；/moai run，用于 DDD 阶段 2；/moai sync，用于文档阶段 3；/moai feedback，用于持续改进；/clear，用于令牌管理。

基础模块（扩展文档）：modules/agents-reference.md，介绍保留的 13 个 Agent 目录（12 个 MoAI 定制 Agent，包括 manager-lead 和 manager-todo，以及 1 个 Anthropic 内置 Agent Explore）；modules/commands-reference.md，介绍 6 个核心命令的工作流；modules/execution-rules.md，介绍安全、Git 策略和合规性。有关迁移对 12 个已归档 Agent（manager-strategy、manager-quality、manager-brain、manager-project、claude-code-guide、researcher 和 6 个 expert-* Agent）的引用，请参阅 .claude/rules/moai/workflow/archived-agent-rejection.md。

---

快速决策指南

新建 Agent：首要原则是 TRUST 5 和委派。辅助原则是令牌优化和模块化。

新建技能：首要原则是渐进式和模块化。辅助原则是 TRUST 5 和令牌优化。

工作流：首要原则是委派模式。辅助原则是 SPEC-First 和令牌优化。

质量：首要原则是 TRUST 5 框架。辅助原则是 SPEC-First DDD。

预算：首要原则是令牌优化。辅助原则是渐进式和模块化。

文档：首要原则是渐进式和模块化。辅助原则是令牌优化。

深入了解模块：modules/trust-5-framework.md、modules/spec-first-ddd.md、modules/delegation-patterns.md、modules/token-optimization.md、modules/progressive-disclosure.md、modules/modular-system.md、modules/agents-reference.md、modules/commands-reference.md、modules/execution-rules.md。

完整示例：references/examples.md 外部资源：references/reference.md

常见的自我辩解

自我辩解	实际情况
“TRUST 5 只是指导原则，不是门槛”	TRUST 5 是硬性质量门槛。完成前，五个维度必须全部通过。
“这么小的改动可以跳过 SPEC”	任何没有 SPEC 的改动都未被跟踪。缺少 SPEC 的改动会累积成难以管理的技术债务。
“简单任务委派给 Agent 只会增加开销”	MoAI 是编排者，而不是实现者。跳过委派会绕过领域专业知识和质量检查。
“代码显然正确，我会跳过质量门槛”	显然正确的代码仍需要证据。测试和 lint 是验证机制；信心不是。
“渐进式披露对这个项目并不重要”	即使是小型项目，也能从节省令牌的技能加载方式中受益。披露关注的是上下文预算，而不是项目规模。

危险信号

• MoAI 直接执行实现代码，而不是委派给 Agent
• TRUST 5 维度只检查了一部分（只检查 Tested 和 Readable，却忽略 Secured）
• SPEC 文档已存在，但没有验收标准
• 未参考选择决策树就选定了 Agent
• 以“稍后检查”为由跳过质量门槛

验证

• 已处理 TRUST 5 的全部五个维度（已测试、易读、统一、安全、可追踪）
• 已记录 Agent 选择，并提供与决策树一致的理由
• SPEC 文档包含验收标准和可观察的证据要求
• 委派链可追踪：MoAI -> agent -> execution
• 已配置技能 frontmatter 中的渐进式披露级别

---

Token 预算（从 moai-foundation-context 吸收）

上下文窗口优化、/clear 策略、会话状态持久化和多 Agent 移交模式。

上下文窗口目标

权威的各模型类别 /clear 阈值表（1M/GLM = 50%，200K/256K = 90%）请参阅 .claude/rules/moai/workflow/context-window-management.md § Context Window Targets。此处不要重复列出阈值（SSOT）。

阶段 Token 分配

阶段	预算	策略
/moai plan	30,000	仅加载需求，完成后执行 /clear
/moai run	180,000	选择性加载文件，按需加载技能
/moai sync	40,000	缓存结果，减少冗余读取

/clear 策略

必须执行 /clear 的时机：

1. 完成 /moai plan 后（开始 /moai run 前）
2. 上下文超过 150,000 个 token 时（Sonnet/standard）
3. 主要阶段转换前

切勿在以下情况下使用 /clear：Agent 任务进行中，或会话状态尚未持久化时。

会话状态持久化

执行 /clear 前，将进行中的状态持久化到 .moai/specs/<SPEC-ID>/progress.md：

• 当前任务状态（已完成、进行中、受阻）
• 文件修改摘要
• 所需的下一步操作
• 用于 /clear 后粘贴并恢复的恢复消息

恢复消息格式：

Wave <N> 이어서 진행. SPEC-<ID>부터 <approach>.
progress.md: .moai/specs/<ID>/progress.md
다음 단계: <command>.

多 Agent 移交

在上下文接近上限时委派给子 Agent：

1. 调用 Agent() 前，在 progress.md 中总结发现
2. 在启动提示词中仅传递必要上下文（避免完整转储文件）
3. 子 Agent 返回的结果会计入父级上下文——请将此因素纳入考虑
4. 如果返回后父级上下文超过 120,000 个 token，请保存并执行 /clear

完整优化模式：modules/token-optimization.md