使用 Impeccable Doctor 命令检测并修复设计工件漂移一份面向 AI Harness 的维护指南【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable在 Impeccable 工作流中doctor是报告并修复的维护性命令它对比当前项目中的 Impeccable 工件与当前安装版本实际会读取的内容之间的漂移drift并给出可执行的修复建议。本文面向使用该 skill 的 Agent 与开发者说明三类漂移的判别、--json/--fix/--target的实际用法、按严重度分级的处置纪律以及 Monorepo 下最容易被误判的几类 finding读完即可在一次会话中正确地跑完一次 doctor 检测并对结果逐条收敛。该命令的决策语义由 doctor.md 定义并在 SKILL.md 中被登记为/impeccable doctor。一、Doctor 管什么以及它刻意不管什么Doctor 的职责边界非常窄它只处理工件artifact与安装版本读取逻辑之间的漂移涉及的对象包括PRODUCT.md、DESIGN.md及其.impeccable/design.jsonsidecar、.impeccable/config.json、持久化的 surface briefs以及 design hook。这句话的潜台词是这是维护maintenance不是设计design。执行时有三条硬性约束全部来自原文档不要重新设计任何东西不要打开报告点名以外的文件不要顺带运行任何其他命令无副作用执行。理解为什么有这些约束关键在于区分挂在过期out of date名下的三种不同漂移。它们是不同的东西必须分开对待漂移类型含义谁来处理判定方式Tool version工具版本漂移安装的 skill 比已发布版本旧npx impeccable update修复context.mjs在启动时上报UPDATE_AVAILABLE这不是 doctor 的活Schema drift模式漂移工件由旧版 Impeccable 写出存在无人读取的字段、缺失当前期望的字段、文件位于已退役的目录doctor 负责修复大部分纯机械对比文件系统层面可判定Truth drift事实漂移代码演进了但文档描述已过时document拥有DESIGN.mdinit拥有PRODUCT.md没有任何文件对比能裁定必须人工阅读第三类尤其关键当代码前进而文档不再描述现实时doctor 的价值不在替你改文档而在把具体差距而非模糊怀疑递给document或init。它不是事实漂移的终结者而是把事实漂移从一个笼统问题拆解成可执行差距的转交者。二、Step 1运行一次完整检测doctor 以 Node 脚本形式执行。标准用法是输出 JSON 报告node .gemini/skills/impeccable/scripts/doctor.mjs --json补充说明doctor.mjs属于已安装的 skill 工具链命令由 Impeccable CLI 一并分发本文档所在仓库是 skill 的源与决策说明所在实际运行时请以安装环境中的脚本路径为准。上述命令将文档中登记的命令形式保留在此便于在 skill 自带环境内原样执行。--target path在 Monorepo 里指定目标当用户在 Monorepo 中指名了某个 workspace、文件或路由时必须追加node .gemini/skills/impeccable/scripts/doctor.mjs --json --target path不加--target时报告默认描述仓库根而在 Monorepo 中根往往不是用户真正关心的那个项目因此在多包仓库里务必显式指定目标。读懂 JSON 输出的三个部分一份完整报告至少携带以下内容findings核心数组每条 finding 的结构字段为id规则标识、artifact涉及的工件类型、path文件路径、severity严重度分级见下一节、summary摘要、fix修复方案描述。workspaces仅在 Monorepo 出现列出每个 app 的 product 与 design 解析结果用于判断各 workspace 是自带上下文、继承上下文还是完全没有上下文。ruleRegistryAvailable: false一个需要特别留意的状态位。它表示被忽略的规则 id 无法被校验——这种情况下应该如实说无法校验被忽略的规则列表而不是暗示该列表是干净的。空 findings 是唯一的好结果当findings为空数组时检测通过。此时的做法是用一行说明结果良好然后立即停止。不要为了找事而扩大检测范围。三、Step 2按严重度分级行动Doctor 输出里的severity字段表示的是接下来该发生什么而不是问题有多严重。三档严重度对应三套截然不同的处置纪律severity语义正确的处置方式auto不携带任何决策纯机械修复直接运行一次--fix应用全部修复然后用一行报告移动了什么。不需要事先征求许可事后也不必逐条询问mention需要用户知情但现在不需要用户决策用一句话陈述每一条并附上它建议的修复方案route需要一条具体命令来收口说出命令名字与它能弥合的差距只有用户在本轮明确要求时才运行。init与document是对话流程不是你能无人值守代跑的修复三组 finding必须一次性全部报告。这里有一条重要的心理模型finding 不是 error命令不会因为它们而失败退出。auto类目执行修复指令node .gemini/skills/impeccable/scripts/doctor.mjs --fix然后以一句话汇报它移动了什么随后进入mention与route两类的人工通报与决策环节。四、Step 3Deprecated 字段是约束性的一旦某条 finding 报告某个字段已被废弃当前典型的是## Register小节它不是一条风格建议。处置规则是从这一刻起在任何后续决策中把该字段当作不存在对待——无论它当前保存着什么值主动提议删除该小节而不是保留。原文用一个非常精准的比喻解释为什么必须删除just in case式地保留它是让一个已经退役的轴线继续操纵当前输出。已废弃字段若继续存在于工件中仍可能被旧解析逻辑或依赖它的流程读取从而让历史决策悄然影响新产出。因此 Step 3 与 Step 2 的机械修复并行执行属于纪律性删除而非可选优化。五、Step 4对 Truth Drift 不过度断言Doctor 有两类 finding 特别容易诱发过度解读需要刻意克制。design-md-drift只是提交数不是矛盾证据该 finding 统计的是自DESIGN.md最后一次编辑以来视觉源目录的提交次数。要点在于提交次数不等于文档错误正确的做法是报告这个数字说明它衡量的是什么若用户想确认文档是否真的错了则对照当前 token 与组件重读DESIGN.md据此作答绝不因为数字很大就断言DESIGN.md已过期。workspace-context-inherited继承是设计行为对workspace-context-inherited的克制同样适用继承inheritance是设计好的行为而非缺陷。一份 product 记录是否如实地描述了多个 app这是需要用户回答的问题不是 doctor 应该修复的 defect。这条纪律贯穿 doctor 的整体哲学它负责把机械性漂移修干净、把事实性疑问精确地提出来但不替用户做关于内容真相的判断。六、Monorepo 专项判定在 Monorepo 中有几个 finding 值得单独建立心智模型。workspace-platform-native-evidence最该重视的 finding原文明确这是 Monorepo 场景下最值得注意的 finding。其机制是某个 workspace 携带了原生构建文件native build files同时它继承的根记录被解析为web结果该 workspace终生只收到 web 端的指引永远加载不到 ios.md 与 android.md。修复方案是在该 workspace 中放置一份子级PRODUCT.md——因为一条被继承的记录无法同时承载两个平台。想让 iOS 与 Android 工作区各得其法必须各自拥有属于自己的记录。config-project-roots-match-nothing根目录被静默顶替该 finding 表示projectRoots里的每一个 glob 都没有命中于是仓库根目录静默地充当了活动项目。改名过的 workspace 目录是常见诱因。处置报告这些 pattern并询问它们应当指向哪些目录。关于buildPath的两个 findingconfig-invalid-build-path与config-build-path-unset都围绕同一个键——.impeccable/config.json或被 gitignore 的.impeccable/config.local.json后者对该开发者优先里的buildPath。这是全部config.*判定中最需要精确上报的一类buildPath的取值是comp或code决定新 surface 是由生成的 comp 构建还是直接在代码中构建一个关键事实未读取的值不会回退到另一条路径——因此一个本意是code的项目可能一直在按comp主导的方式构建。此时必须报告该键的确切当前值config-build-path-unset只在项目已做过方向性工作direction work却从未记录偏好时触发其修复提议只在你的工具面存在图片生成能力时才应出现。没有图片生成能力就没有什么可选的也就无需提及。变更前先展示workspaces表在提议任何改动之前用workspaces表向用户展示哪些 app 自带上下文、哪些在继承、哪些完全没有。这张表是后续一切建议的事实基础没有它任何 Monorepo 层面的修复提议都是盲目的。七、退出启动检查boot checkDoctor 的能力并不只在主动调用时存在。context.mjs会在会话启动时报告上述 finding 的廉价子集cheap subset并按项目每周节流一次cache 位于~/.impeccable/staleness-check.json与更新检查缓存相邻因此不需要新增 .gitignore 条目。启动输出较重的约束下Tier 1 只对整个集合发出一条CONTEXT_STALE指令其中auto类 finding 从不节流、也从不展示给用户。以上纪律同样记录于根级 CLAUDE.md 的 Emission discipline 一节。退出该启动检查有两种途径在.impeccable/config.json中设置stalenessCheck: false——静默该检查或设置环境变量IMPECCABLE_NO_STALENESS_CHECK1——仅对单个会话生效。注意两个要点其一检查被禁用后 doctor 命令本身仍然可用其二对于只想要主动报告的维护者禁用启动检查 需要时手动跑 doctor正是推荐组合——这也是为何相关测试套件如对 boot 指令做断言的上下文测试都会设置该环境变量来隔离噪音。八、与其他命令的分工全景Doctor 是维护链上的收口者与其相邻的命令各司其职。整个命令空间以.gemini/skills/impeccable/SKILL.md为总入口其中登记了/impeccable doctor的触发场景用户调用它或用户询问什么过期了 / 过时了 / 需要刷新时加载 doctor.mdSetup 输出中的CONTEXT_STALE指令是同一份报告的廉价子集按指令自身说明就地处理而不是未经请求运行 doctor。命令间的职责边界建议如下init.md拥有PRODUCT.mddocument.md拥有DESIGN.mddoctor拥有把差距递给前两者的转交职责——schema 漂移它自己修truth 漂移它只负责把具体差距而非模糊怀疑送出去平台侧指引见 ios.md 与 android.md这正是 Monorepo 中workspace-platform-native-evidence决定 workspace 能否看到的关键路径。实践上的总口诀可以压缩为三行跑一遍--json看全貌auto直接--fix并一句话汇报mention/route一次性如实通报、在用户点头前不替跑对话式命令。做到这三点doctor 就能把工件漂移从一件模糊的维护焦虑收敛为一张可以逐条关闭的差距清单。附一次完整会话的速查序列以下命令均基于本文所述语义按序执行即可覆盖完整流程# 1. 全量检测Monorepo 务必带 --target node .gemini/skills/impeccable/scripts/doctor.mjs --json --target workspace路径 # 2. 应用 auto 类机械修复 node .gemini/skills/impeccable/scripts/doctor.mjs --fix # 3. 工具版本漂移的归口非 doctor 职责 npx impeccable update执行后空findings用一行确认并停止非空则严格按auto→mention→route三档在同一次报告中完成处置对design-md-drift与workspace-context-inherited保持报告数字、不下断言的克制涉及buildPath时上报确切当前值而非推测。这便是一次符合 Impeccable 维护纪律的完整 doctor 会话。【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考