第37章 Agent 缺失的设计词汇表
修复设置问题检查 Impeccable 的设置是否仍适合你的项目。本页共 4 个小节。大多数 Agent 使用 /impeccable;在 Codex 中使用 $impeccable。
项目会变,而 Impeccable 的设置可能还停留在旧状态。Doctor 会检查保存的上下文、配置和 hooks,找出诸如文件格式过时、设置失效、hook 指向不存在的脚本等问题。
检查你的项目
在你的 AI 编码工具中运行:
/impeccable doctor
也可以直接问:“这个项目的 Impeccable 设置里有什么过时了?”
工作方式:
检查设置。Doctor 会检查产品记录、视觉记录、配置、保存的页面简报和 design hooks。 修复机械性问题。对于不需要设计或产品决策的变更,它会自动执行迁移,并报告改动了什么。 解释剩余的发现。它会给出具体的修复建议,或指向需要你输入的命令。如果一切正常,你只会收到一条简短的确认。
Doctor 只负责维护设置,不会在修复过程中重新设计界面或改写产品定位。
可操作的发现
在这个例子中,项目文件夹被重命名了,但配置仍指向旧名称:
磁盘上的文件夹apps/ └── store/ 保存的项目根目录"projectRoots": [ "apps/old-name" ] Doctor 的发现配置的文件夹不存在。Impeccable 目前把仓库根目录当作活动项目。修改配置前,请先确认该设置应指向哪个文件夹。 来自一个示例小项目的真实诊断运行。此处为发现摘要;Doctor 未改动配置。
哪些会自动修复?
发现的类别决定了下一步动作,而非问题的严重程度:
类别 处理方式
Mechanical(机械性) Doctor 执行一个明确的迁移,比如把 design companion 文件从已废弃的位置移走,并报告改动。
Worth knowing(值得知晓) 解释发现并提供修复建议。你的工作可以继续。
Needs a command(需要命令) 指出缺口并推荐一个命令,如 init 或 document。该命令会在你请求时执行。
过时的文件格式可能有机械性修复;但判断文件是否仍准确描述你的产品或设计,则需要人工审阅其内容。
会话开始时的提示
Impeccable 还会在会话开始时运行一次轻量检查,可标记:产品记录格式过旧、design companion 文件需要刷新、无法识别的配置键,以及原生应用文件与纯 Web 上下文配对的情况。
这些提示不会阻塞你的任务。同一发现在每个项目每周最多显示一次。想看更完整的报告(包括损坏的 hooks 检查和视觉记录上次更新以来的变更),随时运行 Doctor。
仅在我要求时显示报告
在 .impeccable/config.json 中设置 "stalenessCheck": false 可关闭该项目的会话开始提示;在环境中设置 IMPECCABLE_NO_STALENESS_CHECK=1 可仅对当前会话生效。
即使禁用这些提示,你仍可运行 /impeccable doctor。
参考细节
检查哪些文件和设置?
PRODUCT.md:旧 schema 版本、已废弃的字段,以及记录的平台与原生构建文件之间的冲突。schema 版本描述的是文件格式;Impeccable 发布新的 patch 版本本身并不会让记录过时。 DESIGN.md 和 .impeccable/design.json:视觉记录中的缺口、companion 文件 schema 过旧、companion 文件比记录更旧,以及已废弃的文件位置。DESIGN.md 遵循外部的 design.md 格式,不带 Impeccable 的产品 schema 标记。 Config:无法识别的顶层或 detector 键、指向已不存在规则的忽略 rule ID、已删除文件的精确忽略路径,以及匹配不到任何文件夹的 project-root 模式。适用时,Doctor 还会检查保存的 mockup/code 工作流选择。 Design hooks:缺失的脚本路径,以及已安装 hook 与其启用状态之间的冲突。 保存的页面简报:关联文件或路由已找不到的记录。
如果 rule 注册表不可用,报告会说明无法校验被忽略的 rule ID。
代码大量变更是否意味着 DESIGN.md 不准确了?
其中一项检查会统计自 DESIGN.md 上次编辑以来视觉源码目录的提交数。这个数字只是提醒你去看看的理由,并不能证明记录有误。
想知道具体变了什么,可以让 Impeccable 将记录与你当前的 tokens 和组件进行对比。用 document 更新视觉记录,或用 init 重新审视产品上下文。
包含多个应用的项目
指定要检查的应用:
/impeccable doctor --target apps/store
不指定 target 时,报告描述的是仓库根目录,同时会列出哪些应用拥有自己的产品和设计记录、哪些是继承的。
继承通常很有用;但当各应用有差异时就要留意检查:原生应用继承 Web 产品记录,可能收到错误的平台指引。如果某个应用需要独立的产品上下文,就为它单独建一个 PRODUCT.md。
这是更新 Impeccable 本身的方式吗?
更新已安装的工具版本请使用:
npx impeccable update
Doctor 检查的是项目保存的设置与已安装版本预期是否一致。工具本身有可用更新时会另行报告。
相关内容
Context files 介绍每类记录应包含的内容。 Configuration & ignores 介绍设置与例外规则。 Automatic design checks 介绍如何启用和验证自动设计检查。