Impeccable doctor 命令全解系统性检测并修复 PRODUCT.md、DESIGN.md 与配置工件的版本漂移【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccableImpeccable 技能把项目的设计真相落盘成一组有版本的工件PRODUCT.md、DESIGN.md 及其.impeccable/design.json侧车文件、.impeccable/config.json、持久化的 surface brief、设计钩子。当技能版本升级、Schema 演进或代码前移之后这些工件会与已安装版本实际读取的内容产生漂移drift从而悄悄把过期决策带进后续每一轮设计输出。doctor命令正是为此设计的维护工具它不产出任何设计只负责报告并机械修复这种漂移。读完本文你将掌握doctor的完整用法——如何运行漂移扫描、解读 findings 数据结构、按auto/mention/route三档严重度正确处置、在 monorepo 中精准定位误配置以及如何用stalenessCheck关闭开机自检。该命令的操作规范定义在技能参考文档 doctor.md各编辑器镜像如 .claude/skills/impeccable/reference/doctor.md、.cursor/skills/impeccable/reference/doctor.md内容一致其上游来源是 skill/SKILL.src.md 中的 Doctor 段落与仓库根部的 CLAUDE.md 实现说明。doctor 拥有什么、不拥有什么doctor 的职责范围非常克制边界先于一切操作步骤被定义死这是维护不是设计。不重新设计任何东西不打开报告点名之外的任何文件也不以副作用方式运行任何其他命令。扫描对象固定PRODUCT.md、DESIGN.md 及其.impeccable/design.json侧车文件、.impeccable/config.json、持久化的 surface brief以及设计钩子design hook——即技能安装版本在每次会话中实际读取的全部工件集合。仓库内的工具设计在 CLAUDE.md 中被明确定位为维护工具而非设计命令它遵循hooks与pin的工具模式一行声明加一份参考文档刻意不在IMPECCABLE_SUB_COMMANDS、command-metadata.json、SKILL_CATEGORIES或pin的合法命令表里登记因此不会出现在设计菜单中抢占入口。技能源码 skill/SKILL.src.md 同样说明当用户调用 doctor、或询问什么过期了 / 过时了 / 需要刷新时加载本文档。三类漂移必须区分开所有被笼统称为out of date的情况实际上可以拆成三种性质完全不同的漂移处置方式也完全不同漂移类型成因谁负责修复工具版本漂移Tool version已安装的技能比发布版旧context.mjs在启动时报告UPDATE_AVAILABLE运行npx impeccable update解决——不是 doctor 的职责Schema 漂移Schema drift工件由更老版本的 Impeccable 写出存在无人读取的字段、缺失新版期望的字段、文件位于废弃位置机械性问题doctor 修复其中大部分真相漂移Truth drift代码已经前移文档不再描述真实代码没有任何文件比较能裁决document拥有 DESIGN.mdinit拥有 PRODUCT.md。doctor 的职责是把一个具体的差距交给它们而不是抛一个模糊的怀疑第三种漂移值得特别注意doctor.md明确要求将差异定位到具体缺口再转交因为 DESIGN.md 与 PRODUCT.md 的再生成都是对话式的见 init.md 与 document.md医生不能代替这两个命令去顺手修一下文档。第一步运行漂移扫描对仓库根目录执行完整检查node .opencode/skills/impeccable/scripts/doctor.mjs --json命令路径的解析遵循 SKILL.md 中 Setup 的约定运行时报告给技能的 base directory 会解析本技能与参考文档里所有node .opencode/skills/impeccable/scripts/...命令.opencode/skills/impeccable/scripts只是在运行时没有报告 base directory 时的回退路径。参数说明--json以结构化 JSON 输出 findings便于 Agent 与脚本消费。--target path当用户在 monorepo 里点名了某个 workspace、文件或路由时使用。不加该参数时报告描述的是仓库根目录而在 monorepo 中根目录往往并不是真正的活动项目。--fix一次性应用所有auto严重度的修复见下节。理解输出结构输出主要携带两类信息findings每条包含id机型标识、artifact涉及的工件、path文件路径、severity严重度档位、summary摘要、fix建议的修复方式六个字段。workspaces仅 monorepo给出每个应用各自的 product 与 design 解析结果即哪些子应用携带了自己的上下文、哪些继承了根记录。额外注意两个特殊标记ruleRegistryAvailable: false表示被忽略的 rule id 无法被校验当前环境拿不到规则注册表。此时应如实说明该列表并非经过校验的干净名单不能暗示已忽略规则全部合法。空的findings数组就是最好的结果用一行说明未发现漂移然后停止不要为了显得勤快而继续动作。findings 不是错误命令本身不会因为存在 findings 而失败。这一findings 即数据的设计与 CLAUDE.md 中描述的实现一致——启动指令、文本报告与--json渲染的是同一份数据集Schema 统一为{ id, artifact, path, severity, summary, fix }。第二步按严重度行动doctor 反复强调一个容易误解的点severity 说明应该发生什么而不是问题有多严重。据此可以把处置分成三档严重度含义处置方式auto不携带任何决策机械修复运行一次node .opencode/skills/impeccable/scripts/doctor.mjs --fix应用全部修复然后用一行汇报移动/修复了什么。事先不要征求许可事后也不要再追问mention需要让用户知道但此刻无需用户做任何决定用一句话逐条陈述并附上它提供的修复建议route需要某个特定命令来收口点出命令名称及其将关闭的差距只有当用户在本轮明确要求时才运行它——init与document是对话式流程不是可以在无人值守下执行的修复三组auto / mention / route必须在同一次汇报中全部给出不允许先处理一部分、把其余拖到下一轮。与doctor --fix只应用auto、且仅在无判断介入处应用这一点与 CLAUDE.md 的实现说明完全一致doctor --fixapplies onlyauto, and only where no judgment is involved。第三步废弃字段具有约束力凡报告指出某字段已废弃当前典型例子是## Register这一节这不是一条风格建议。从那一刻起无论该字段存着什么值都必须把该字段当作不存在来处理每一次决策并主动提出删除该节的建议。文档给出的理由非常直白把它以防万一地保留下来正是让一条已经退役的轴继续悄悄左右当前输出的方式。这是一个软约束传染问题——历史字段只要还在文档里LLM 读取 DESIGN.md / PRODUCT.md 时就仍可能被它牵引。第四步在真相漂移上不要过度断言doctor 专门给出两条克制纪律防止把统计数字误当结论design-md-drift的语义是统计 DESIGN.md 上次编辑以来视觉源目录中的提交数。提交数不等于矛盾。正确做法是如实报告该数字说明它衡量的是什么只有当用户确实想知道文档是否写错了才把 DESIGN.md 与当前的 tokens、组件逐一对照并基于对照结果作答。永远不要因为数字大就断言 DESIGN.md 已过期。workspace-context-inherited同理继承是设计好的行为。某一条 product 记录是否真实地描述了多个 app这是要交给用户判断的问题而不是需要修复的缺陷。这种克制与整个技能的编辑前验证真实视觉真相哲学一脉相承——数值只能提示方向只有对真实工件tokens / CSS / 组件 / 资产的阅读才能裁决文档对错。Monorepo 专项注意点在 monorepo 布局下doctor 会暴露几类根因性的配置错误值得逐一掌握workspace-platform-native-evidence最需要重视的 finding某 workspace 携带原生构建文件iOS / Android却继承了一条解析为 web 的根记录。结果它整个生命周期都收到 web 导向的设计指引永远加载不到 ios.md 或 android.md。修复方式是给该 workspace 写一份子级 PRODUCT.md——因为一条被继承的记录无法同时承载两个平台。原生平台相关处理细节可参考 adapt.native.md 与 audit.native.md。config-project-roots-match-nothingprojectRoots的所有 glob 都未命中任何目录于是仓库根目录被静默地顶替为活动项目。常见成因是 workspace 目录被改名。正确处置是报告当前 glob 模式并询问用户这些模式本应指向哪些目录而不是自行猜测改名。config-invalid-build-path与config-build-path-unset两者都围绕同一个键——.impeccable/config.json里的buildPath或者是被 gitignore 的.impeccable/config.local.json后者对单个开发者而言优先级更高。该键只取comp或code两个值决定新 surface 是从生成的 comp 起步构建还是直接在代码中构建。buildPath的语义与默认行为详见 init.mdcomp-first指先用一张图片设定期望基准再写代码构图更大胆、更慢、构建必须匹配图片code-first指直接编码、把野心写进方向契约并在 finish 阶段审计更精简、更快。未回答问题时不应记录任何值。一个未读取的值不会回退到相反路径——所以一个本意是code的项目可能一直以 comp 主导的方式在构建。因此必须报告确切的现值而不是让用户以为没配就是默认。config-build-path-unset只在项目已做过方向性工作却从未记录过偏好时触发而且只有在你的工具面tool surface存在图像生成能力时才应该给出记录偏好的提议——没有图像生成就没有可选项也就无话可说。在提出任何改动之前先用workspaces表向用户展示哪些 app 携带自己的上下文、哪些继承根记录、哪些什么都没有。退出开机自检boot check漂移检查并不是只在显式运行 doctor 时才发生。context.mjs会在会话启动时报告上述 findings 中廉价子集并且按项目每周最多节流一次。如果你希望报告只在用户主动询问时出现有两种退出方式全局关闭在.impeccable/config.json中设置stalenessCheck: false单次会话关闭设置环境变量IMPECCABLE_NO_STALENESS_CHECK1。关闭自检不影响 doctor 命令本身的可用性——平时静默、按需报告正是文档推荐的组合。从实现侧看节流与缓存的机制在 CLAUDE.md 中有交代启动自检只发出一条CONTEXT_STALE指令代表整组结果mention与route类 findings 通过~/.impeccable/staleness-check.json缓存按周节流autofindings 从不节流也从不展示给用户仓库的测试套件如在 tests/skill-behavior 中在断言其他启动指令时会设置该环境变量以隔离自检噪声。把 doctor 放进日常维护节奏总结一套推荐的实践闭环会话启动时留意context.mjs输出的CONTEXT_STALE指令——它是本次完整报告的一个廉价子集按其自身指令就地处理而不是顺手把完整 doctor 跑一遍。需要全量视图时尤其更换编辑器、升级技能、重组 monorepo 之后显式运行doctor --json用workspaces表先看清每个子应用的上下文归属。修复只分两类动作--fix一次性吃掉所有automention陈述一遍route只有用户明确要求才把对话交给init/document。对统计型 finding 保持克制提交数、继承记录都不是文档错了的证据把数字如实上报把裁决留给对真实代码的阅读。需要关掉每周自检的开发者用stalenessCheck: false或IMPECCABLE_NO_STALENESS_CHECK1让 doctor 回归随叫随到。把 doctor 视作技能的体检工具而非设计能力它的价值就体现在每一次技能升级与代码重构之后快速区分机械性的 Schema 修复与需要人类判断的真相漂移让 PRODUCT.md、DESIGN.md、配置与 surface brief 永远反映当前版本真正读取的内容从而保证后续每一轮设计输出都建立在最新、最真的工件之上。【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
