Skip to main content

moai spec 文档管理

更新 2026-09-11 3 分钟阅读 在 GitHub 上编辑 ↗

moai spec 管理 .moai/specs/ 目录中的 SPEC 文档。它提供状态更新、漂移检测、验收标准查看、EARS/GEARS lint、原子化关闭、era 审计、归档的子命令。

子命令

命令说明
moai spec status更新或列出 SPEC 状态
moai spec drift检测 frontmatter status 与 git log 之间的漂移
moai spec view <SPEC-ID>以树状结构查看验收标准
`moai spec lint [SPEC-IDpath/to/spec.md
moai spec close <SPEC-ID>原子化 4-phase 关闭(status: completed + progress.md backfill)
moai spec auditSPEC era 分类与 modern-era 状态漂移审计
moai spec archive将已关闭的 SPEC 归档至 .moai/specs/ 之外

moai spec status

bash
moai spec status <SPEC-ID> <new-status>   # 更新状态
moai spec status --list                   # 列出全部 SPEC
moai spec status --sync-git               # 从 git log 同步状态
标志说明
--dry-run不写入,预览变更
--list列出全部 SPEC 及状态
--sync-git从 main 的 git log 同步 SPEC 状态
--yes--sync-git 非交互式自动确认(CI/管道必需)

moai spec drift

bash
moai spec drift
标志说明
--jsonJSON 格式输出
--exit-code-on-drift检测到漂移时返回退出码 1
--count仅输出漂移数量
--no-cache绕过 HEAD-SHA 结果缓存后重新计算

moai spec lint

bash
moai spec lint [SPEC-ID | path/to/spec.md | SPEC directory ...]
标志说明
--jsonJSON 格式输出
--sarifSARIF 2.1.0 格式输出
--strict将警告视为错误
--format <fmt>输出格式(table)
--baseline <path>用检入仓库的按规则基线进行门控,替代 --strict——错误始终失败,某规则的非 advisory 警告数仅在超过已记录值时才会阻断,现存警告总数始终显示在输出中
--update-baseline重新计算并覆写 --baseline 文件(需要 --reason)
--reason "<text>"--update-baseline 记录的必填非空理由——理由为空或缺失将被拒绝
参数形式示例
SPEC-IDSPEC-SPC-001 — 解析为项目根目录下的 .moai/specs/SPEC-SPC-001/spec.md(与 moai spec view 规则相同)
文件路径.moai/specs/SPEC-SPC-001/spec.md
SPEC 目录.moai/specs/SPEC-SPC-001 — 读取其中的 spec.md

三种形式可在一次调用中混用;不带参数时仍按原方式扫描整个语料库。看起来像 SPEC-ID 却解析不到文件的参数,不是对文档的指摘,而是 参数错误(退出码 3),并会一并给出尝试过的路径。

此处会产生两个 advisory 级别的警告。ModalityUnjudged 会报告 linter 无法判定的需求,而不是静默略过。REQTableRowsRejected 会报告未被读作 REQ 定义的表格行。两者均为 advisory:--strict 不会将其提升为错误,也不改变退出码。

moai spec close

bash
moai spec close SPEC-ID

以单次提交将 SPEC 原子化转换为 status: completed。

标志说明
--backfill-only仅执行 progress.md backfill
--dry-run不提交,预览
--force不确认强制关闭
--jsonJSON 格式输出

moai spec audit

bash
moai spec audit

扫描 .moai/specs/SPEC-*/,用 era 启发式对每个 SPEC 分类并检测 modern-era 状态漂移。

标志说明
--jsonJSON 格式输出
--filter-era <era>按 era 过滤
--filter-spec <id>按 SPEC ID 过滤
--include-grandfathered包含 grandfather era SPEC
--strict严格模式

moai spec archive

bash
moai spec archive --dry-run   # 确认目标(不移动)
moai spec archive --yes       # 应用计划

归档超过 grace 窗口(默认 90 天)的 terminal SPEC。

标志说明
--dry-run不移动,报告目标集合
--yes确认移动(应用时必需)
--grace-days <n>grace 窗口天数(0 = 默认值 90)
--json以 JSON 输出计划

相关文档