技能介绍

问题：手写协作文档带来的系统性漂移

在一个由 AI Agent 与人类共同维护的代码库中，文档与元数据往往是最先腐烂的部分。典型的问题包括：

ADR 编号冲突：多人或多 Agent 并行编写架构决策记录（ADR）时，很容易出现编号重复。
索引滞后：手工维护 docs/domain/README.md 或 docs/adr/README.md，极易在新增领域或决策后忘记更新目录。
约束丢失：硬性限制散落在各个文档中，或者因为 frontmatter 缺少 title、status、owner 字段而失效。
风险盲区：高风险领域如果缺少明确的 rules 声明，CI 校验可能会直接阻塞发布。

简而言之，当文档变成代码库的一部分时，缺乏强类型和确定性的校验手段，任何「约定俗成」都会在协作中失效。

解决方案：基于命令驱动的元数据治理

Wing CLI 的目标是成为工程协作的「宪法执行器」。它不依赖于个人自律，而是通过命令行工具强制保证文档结构、编号连续性和索引一致性。

核心工作流分为三个阶段：

初始化与脚手架：

通过 wing init 建立项目元数据基础。后续创建任何新内容都必须通过命令完成，例如 wing new-domain 会自动建立目录结构、初始化局部 AGENTS.md 和 rules.md；wing new-adr 则负责自动分配编号并填充 frontmatter。这确保了「唯一事实来源」的一致性。\n

确定性校验：

在提交前，wing check 会对整个仓库进行静态分析。它不仅检查 frontmatter 字段是否完整，还会校验 last_reviewed 日期是否过期，甚至核对领域规则是否写入了正确位置。配合 CI 中的 wing check --strict，任何 warning 都会被视为阻断性 error。\

索引与同步：

自动生成的索引文档不再手工编辑，而是通过 wing sync 重建。这避免了因漏写目录而导致的知识孤岛。

适用边界与注意事项

Wing CLI 是一个治理工具而非代码生成器。它负责确保你的文档结构符合 OpenSpec 规范或团队约定，但不会替你写出具体的业务逻辑。\n
需要注意的是，高风险领域的规则必须由开发者定义在 rules.md 中。如果 wing.config.yaml 中的 risk_keywords 命中了某个领域，但该领域缺少硬限制声明，wing check 会通过 HIGH_RISK_DOMAIN_MISSING_HARD_CONSTRAINTS 强制报错。此时，你需要补全约束，而不是试图绕过检查。