moai-foundation-quality

TRUST 5 质量原则与执行

本技能介绍 MoAI 的质量模型背景知识：TRUST 5 五项原则、Agent 如何执行这些原则、3 级验证机制，以及 /moai gate 运行的语言感知工具链。MoAI 不会随附质量验证库——质量通过 Agent （manager-develop、sync-auditor）、斜杠命令（/moai gate、 /moai review）和验证机制（minimal/standard/thorough）来执行。

快速参考

TRUST 5 原则（Tested、Readable、Unified、Secured、Trackable）是 质量维度，而非代码对象。每项代码变更都会根据全部五项原则进行评估。

质量机制（实际的执行层）：

• /moai gate — 并行运行 lint + format + type-check + test，作为 提交前质量门禁（<30s）。自动检测项目语言并运行相应的工具链。
• manager-develop（run-phase）— 通过 cycle_type ∈ {tdd, ddd, autofix} 实现；所选循环决定测试和行为的构建方式。
• sync-auditor — 通过 4 个维度评分（Functionality、Security、Craft、Consistency）进行独立、审慎的质量评估；最终得分为各维度的 调和平均数，而非算术平均数。
• 3 级验证机制 — minimal（快速验证）、standard（默认检查）、 thorough（完整的 sync-auditor + TRUST 5）。由 Complexity Estimator 根据 SPEC 范围自动确定。
• LSP 质量门禁 — 特定阶段的阈值（run：零 errors/type-errors/ lint-errors；sync：零 errors、最多 10 条 warnings、LSP 状态干净）。

MoAI 质量模型

MoAI 不提供 Python SDK 或任何用于质量验证的库。 质量通过工作流、Agent 和门禁命令来执行。 本技能说明这些部分如何协同工作，以便 Claude 调用能够正确地判断质量。

TRUST 5 如何在各阶段执行

阶段	质量检查	负责方
plan	记录 LSP 基线；在计划中识别质量风险	manager-spec
run	零 errors/type-errors/lint-errors；测试通过；达到覆盖率要求	manager-develop（cycle_type 决定方法）
sync	Lint 干净（≤10 条 warnings）；文档已更新；再次确认 TRUST 5	manager-docs，然后由 sync-auditor 评分
audit	独立进行 4 个维度的评分（Functionality/Security/Craft/Consistency）	sync-auditor

cycle_type 与质量（manager-develop）

run-phase 的 cycle_type 决定如何构建质量：

• tdd — 测试驱动开发（RED-GREEN-REFACTOR）。先通过失败测试 明确行为，再进行实现。最适合新功能。
• ddd — 领域驱动重构（ANALYZE-PRESERVE-IMPROVE）。 在保留行为的前提下转换现有代码。最适合重构和减少技术债务。
• autofix — 由诊断结果驱动修复（LSP / lint / type errors）。最适合 /moai fix 和回归恢复。

有关各循环的具体机制，请参阅 Skill("moai-workflow-tdd")、Skill("moai-workflow-ddd") 和 Skill("moai-workflow-loop")。

TRUST 5 原则

TRUST 5 是代表五个质量维度的助记符。将每个维度视为审视任何变更时要提出的问题，而不是要计算的分数。

• T — 已测试：变更是否有测试？测试是否全部通过？覆盖率是否达到或超过项目阈值（默认 85%+）？对于现有的未测试代码，是否有特征测试记录当前行为？
• R — 易读：命名是否清晰？注释是否使用英语（或配置的代码注释语言）？新贡献者能否不经讲解就理解其逻辑？
• U — 统一：变更是否符合文件现有的约定（命名、错误处理、导入）？是否使用项目的格式化工具进行格式化？文件内的一致性优先于个人偏好。
• S — 安全：是否验证了所有外部输入？是否遵循 OWASP Web 安全指南？凭据是否未提交到版本控制中（而是使用环境变量）？请参阅 moai-ref-owasp-checklist。
• T — 可追踪：提交是否遵循 Conventional Commits？是否引用了所实现的 SPEC / 问题？能否将变更追溯到某项需求？

有关各原则的评估清单以及“ 不适用”防护机制，请参阅 TRUST 5 原则。

质量门禁与 3 级测试框架

测试框架级别决定质量验证的深度。复杂度估算器会根据 SPEC 范围自动确定级别。

级别	执行内容	适用场景
minimal	仅快速验证（lint + type + test）	小型 SPEC、低风险
standard	默认检查（lint + type + test + format）	大多数 SPEC
thorough	完整的 sync-auditor + 4 维 TRUST 5 评分	大型 SPEC、高风险

/moai gate 是轻量级的提交前入口：它会并行运行 lint + format + type-check + test，且不会应用任何修复。这是最快获取质量信号的方式。如需更深入的审查，请使用 /moai review。

语言适配的工具链

质量门禁会自动检测项目语言，并运行相应的工具链。未安装的工具会自动跳过；未检测到受支持语言标记的项目会静默通过门禁。这项技能与语言无关——16 种受支持语言一视同仁。

语言	Lint	Format	Test
Go	go vet → golangci-lint	gofmt	go test
Python	ruff	black	pytest
TypeScript / JavaScript	eslint	prettier	jest / mocha
Rust	cargo clippy	rustfmt	cargo test
Java / Kotlin	（按项目配置的 linter）	（按项目配置）	junit
Ruby	rubocop	rubocop	rspec
PHP	phpstan / phpcs	php-cs-fixer	pest / phpunit
...	（支持 16 种语言；自动检测）

有关完整的工具链映射，以及 /moai gate 如何检测语言，请参阅 语言适配的工具链。

模块参考

每个模块都会按需加载。加载与当前任务相关的模块即可。

• TRUST 5 原则 — 将五个维度转化为评估问题、各原则的检查清单，以及“不适用”防护机制。
• 主动分析 — /moai gate、/moai review 和 /moai loop 如何主动发现质量问题，以及如何对发现的问题进行分类处理。
• 最佳实践 — 使用 WebSearch / WebFetch 获取最新的框架和库最佳实践，并据此进行验证。
• 集成模式 — 质量如何融入 SPEC 工作流阶段（plan/run/sync）及测试框架级别。

参考文件

• examples.md — TRUST 5 评估实例及门禁／评审分诊演练。 对具体变更应用 TRUST 5 时加载。
• reference.md — 质量机制参考：框架层级详情、语言工具链表、Agent 角色及 sync-auditor 评分模型。需要权威映射时加载。

配合使用效果良好

Agent（13 个 Agent 的目录见 .moai/config/sections/delegation.yaml）：

• manager-develop — 执行阶段的实现；通过 cycle_type 负责 Tested 和 Unified 原则。
• sync-auditor — 独立进行 4 维质量评分（功能性／安全性／工艺／一致性）。
• Explore（Anthropic 内置）— 在评估质量前以只读方式探索代码库。

技能：

• moai-foundation-core — TRUST 5 框架交叉参考和 SPEC 工作流基础。
• moai-ref-testing-pyramid — 测试金字塔策略、覆盖率目标和测试模式。
• moai-ref-owasp-checklist — Secured 原则的 OWASP Top 10 安全检查清单。
• moai-workflow-tdd / moai-workflow-ddd / moai-workflow-loop — manager-develop 使用的 cycle_type 工作流。

命令：

• /moai gate — 提交前质量门禁（lint + format + type + test）。
• /moai review — 代码评审，检查安全性及 MX 标签合规性。
• /moai fix — 自动检测并修复 LSP／lint／type 错误。
• /moai loop — 迭代修复，直到问题解决或达到最大迭代次数。

常见的自我开脱

自我开脱	事实
“Linter 警告是误报”	误报应通过行内注释屏蔽。忽略警告会让团队养成忽视真实问题的习惯。
“可以等到发布前再进行安全扫描”	安全漏洞会不断累积。发现得越晚，返工成本越高。应持续扫描。
“覆盖率已经够高了，剩下的 15% 都是边界情况”	生产环境中的 Bug 往往出现在边界情况中。未覆盖的代码风险最高。
“代码评审很主观，自动化已经足够”	自动化能发现语法和模式问题；评审则能发现设计缺陷、命名歧义和缺失的抽象。
“热修复不需要繁琐地遵循 TRUST 5”	不经过质量门禁的热修复会引发下一次热修复。对热修复而言，TRUST 5 是最低要求，而非最高要求。

切斯特顿栅栏：移除质量检查之前，先弄清它为何存在。不了解门禁的由来就将其移除，只会重蹈它原本旨在避免的失败。

左移：越早发现缺陷，修复成本越低。质量检查应纳入开发循环，而不是留到最后。

警示信号

• 全局屏蔽 Linter 或类型检查器警告，而非逐行屏蔽
• 处理用户输入或身份验证时，未参考 OWASP 检查清单
• 新增功能的提交未生成覆盖率报告
• 以“ 不适用 ”为由跳过 TRUST 5 维度，且未说明理由
• 已生成质量报告，却未处理其中发现的问题

验证

• Linter 无报错，或剩余警告均有说明原因的行内屏蔽注释（展示命令输出）
• 与安全相关的变更已参考 OWASP 检查清单（展示检查清单参考项）
• 已生成覆盖率报告且达到阈值（展示工具输出）
• 已评估 TRUST 5 的全部五个维度（展示每个维度的评估结果）
• 已对质量发现进行分诊，并为每项制定解决计划
• Linter 配置中没有全局禁用规则