impeccable 的降级文档记录者：如何从已交付产物反向提取设计系统

.agents/skills/impeccable/reference/degraded/documenter.md 是 impeccable 技能包中 Documenter（设计系统记录者）角色的降级模式（degraded mode）运行手册，由构建流水线从子代理定义自动单源生成，用于在没有子代理能力的 AI 编程环境中内联执行该角色。本文完整拆解这份文档的角色定位、输入契约、五步工作流与输出契约，并结合生成它的构建管线、测试用例和它所引用的 DESIGN.md 格式规范（document.md）、craft floor 规则，说明"先建后写"这一设计系统记录原则背后的工程机制。

一、文件定位：不是手写的，而是构建时从子代理定义生成的

该文件第一行就是生成标记：

<!-- Generated from skill/agents/ at build time. Do not edit; edit the agent definition. -->

这说明了它在 impeccable 中的真实身份：它是 skill/agents/impeccable-documenter.md 的构建产物，而非独立维护的文档。仓库中 skill/reference/ 下并不存在手写的 degraded/ 目录，测试 tests/build.test.js 明确断言了这一点（"the source repo contains no hand-authored degraded/ reference files (generation-only)"）。

生成逻辑位于构建管线 scripts/lib/transformers/factory.js，可以确认三条机制：

1. 前缀剥离：角色文件名取自代理名去掉 impeccable- 前缀，即 impeccable-documenter 生成 documenter.md；
2. 统一前导段（DEGRADED_PREAMBLE）：每个降级文件都注入同一段说明文字（factory.js），即本文接下来第二节要分析的内容；
3. 与常规引用文件相同的编译管线：正文会经过 provider 块编译（<codex> 等标签按目标提供方保留或剔除）、{{scripts_path}} 占位符替换与规则标记剥离，由合成代理测试（tests/build.test.js）验证。

生成的降级文件会随各 provider 构建落盘到对应技能目录下，例如 plugin/skills/impeccable/reference/degraded/documenter.md 与本文主角 .agents/skills/impeccable/reference/degraded/documenter.md 是同一份内容在不同 provider 构建中的拷贝。同目录还有另外三个角色的降级手册：asset-producer.md、finish-reviewer.md、manual-edit-applier.md（tests/build.test.js 断言恰好这四个角色）。

二、降级前导段：内联执行时的行为约束

文件开篇的降级前导段（所有角色共用）包含四条行为约束：

• 当前 harness 没有子代理能力，因此你（当前模型）内联运行这个角色；
• 彻底抽离刚完成的工作（"Step fully out of the work you just finished"），本次回合只采用本文件的指令；
• 汇报时用一行披露这次替代（disclose the substitution）；
• 当正文针对"父代理"说话时，你同时扮演两方：先产出完整的输出契约，再亲自执行它。

这解决的是子代理架构中的职责污染问题：在正常流程中，父代理负责派发任务并验收子代理的返回；降级模式下没有边界隔离，文档明确要求模型"自己派发、自己验收"，用输出契约作为内部检查点。这与源定义 skill/agents/impeccable-documenter.md 的 frontmatter 中 tools: Read, Write, Bash, Glob, Grep（只读为主、单一写入口）的权限设计呼应——记录者需要扫读整个构建产物，但只允许写 DESIGN.md 及其 sidecar。

三、角色定位：以已交付产物为唯一事实来源

文档第一句定义了该角色的根本立场：

Ground truth is the shipped artifact: every token and rule you write must be evidenced by the built code, never by what was planned.

设计系统必须在构建完成后才记录。文档给出了理由：事前写好的规则手册会"被用来对抗现实，而不是描述现实"（a rulebook written before the build gets defended against reality instead of describing it）——即模型在实现时倾向于辩解而非修正文档。这一立场在 new-work.md 第 7 节的流程编排中得到印证：DESIGN.md 由"shipped documenter"在构建收尾时从已建成的世界中提取，"a new world shipped with no DESIGN.md is still an incomplete run"（交付了新世界却没有 DESIGN.md 的运行视为未完成），且 Documenter 在 Codex 中对应 impeccable_documenter，无子代理时即从本文所在的 degraded/documenter.md 运行。

四、回合上限纪律：硬性 max-turns 下的执行策略

文档指出该角色"运行在一个无预警终止的硬性回合上限之下"，而"在 DESIGN.md 写成之前结束的运行等于什么都没记录"。源定义 skill/agents/impeccable-documenter.md 给出了具体数值：max-turns: 30。针对这一约束，文档给出一套优先级策略：

• 批量读：每个回合塞进多个 Read 调用，而不是每回合读一个文件；
• 优先取主证据：先读 reference/document.md（操作规范）和样式表，再谈其余；
• 采样而非遍历：对组件做抽样（sample components rather than walking the tree）；
• 中途开写：在运行到一半时就必须开始写文件；
• 取舍原则：从一手证据记录的、不完美的系统，胜过从未落盘的穷尽扫描（"a system recorded from the primary evidence beats an exhaustive scan that never becomes a file"）。

这套策略本质上是把"写文件"设为不可失守的最低目标，把"扫描完整度"设为可牺牲项——与 frontmatter 中 effort: medium、model: inherit 的配置共同构成一个在有限预算内保证产出存在的执行画像。

五、输入契约（Input Contract）

文档明确列出了角色启动时应预期收到的七项输入：

输入项	说明
项目根目录	扫描边界
产物路径（artifact path(s)）	已交付的代码/页面，唯一事实来源
方向契约文本	包含 THESIS、OWN-WORLD、STORY、FIRST VIEWPORT、FORM 五个块
PRODUCT.md 路径	产品上下文
技能 reference/document.md 路径	DESIGN.md 的操作规范
写入边界	写 DESIGN.md 的位置（项目根或应用根）

另有一条关键语义：已存在的 DESIGN.md 意味着"更新"而非"替换"——必须保留已确认的在任决策（confirmed incumbent decisions），并与本次构建对齐。这对应 document.md "When to run" 一节中"已有 DESIGN.md 时不得静默覆盖，必须先展示现有文件并让用户选择 refresh / overwrite / merge"的规定。

六、五步工作流

第 1 步：通读操作规范 reference/document.md

文档要求"完整读取，并严格遵循"，因为它是 DESIGN.md 的格式、token 模式、sidecar 与章节顺序的操作规范。该规范（skill/reference/document.md）的核心内容决定了记录者的产出形态：

• YAML frontmatter 是机器可读层：colors、typography、rounded、spacing、components 五组 token，其中组件子 token 限 8 个属性（backgroundColor、textColor、typography、rounded、padding、size、height、width），token 引用使用 {colors.primary} 这类路径语法，且"组件可引用基元，基元不得互相引用"；
• Markdown 正文固定八节且顺序不可变：Overview、Colors、Typography、Layout、Elevation & Depth、Shapes、Components、Do's and Don'ts，不相关的节应省略而非填充，标题不允许近义改写（工具解析依赖精确标题）；
• sidecar 文件 .impeccable/design.json 承载 frontmatter 装不下的扩展：tonal ramp、shadow/motion token、断点、完整组件 HTML/CSS 片段与叙事内容，schemaVersion: 2 下不再重复 token 基元，而是按 frontmatter token 名键入元数据（colorMeta.<token>、typographyMeta.<token>）。

第 2 步：扫描产物

扫描清单具体到取值手段：样式表、CSS 自定义属性、源码中的计算值、组件模式、间距节奏（spacing rhythm）、"实际使用中的字阶"（type ramp as actually used）。同时文档给出方向契约与构建冲突时的裁决规则：OWN-WORLD 块命名了理想世界，构建展示了它如何落地，两者分歧时"构建获胜"（the build wins），文字中可以记录分歧本身。

第 3 步：只写"持久系统规则"

写 DESIGN.md（及 sidecar）时只收录两类内容：项目实际在用的 token 与构建实际遵循的命名规则。判定标准一句话："只使用一次的 token 不是系统"（a token used once is not a system）。这一条与 document.md "Pitfalls" 中的"Don't extract every token. Stop at what's actually reused; one-offs pollute the system"完全同构，防止一次性值污染规范。

第 4 步：两种已被现场观测到的错误模式

文档列举了记录规则时两种已发生过的（both observed live）错误：

1. 禁止条款禁止了世界自身原生的手法（a prohibition that bans a device the world itself uses natively）——禁令必须对照世界自己的材质逐条检查；
2. 为了合法化一个缺陷而记录某个值（a value recorded to legitimize a defect）——值的资格由构建本身和可读性挣得，绝不由"让某条审计发现消失"挣得。

这是对"记录者"角色的防腐蚀条款：记录者天然有把既有产物合理化（rationalize）的倾向，文档用这两条把这种倾向显式化为审查对象。

第 5 步：永不把 craft-floor 的拒绝"典入"系统

文档第 5 步划定了一条不可逾越的边界：craft floor（工艺底线）所禁止的元素，只能作为"构建携带的缺陷"记录在 not-canonized 行中，绝不能写成设计系统规则。craft floor 的禁项清单定义在 skill/reference/craft-floor.md 的 "Refuse" 一节，其中与本文直接点名呼应的有四条：

• kickers and eyebrows（标题上方的眉标）——文档称之为"唯一不是默认而是真禁令"的一条，"没有任何 brief 能把它挣回来"；
• hard offset shadows（零模糊硬偏移阴影，如 box-shadow: 4px 4px 0）——除非世界本身是 neobrutalist；
• glyph icons（Unicode 字符/emoji 冒充图标系统）；
• system display faces（Impact、Arial Black、平台默认无衬线作为 own-world 页面的展示字体）。

文档还附了一个现场事故作为反面教材：一次真实会话交付了五个自造的 kicker，而记录者把它们的样式写进了 DESIGN.md——"这就是一次违规变成 house style 的方式"（that is how one violation becomes the house style）。这条规则与 new-work.md 中"DESIGN.md 描述一个不再存在的布局会把缺陷变成系统指导"的警告构成闭环：记录者是把缺陷"制度化"的最后一道闸门。

七、输出契约（Output Contract）

文档最后规定了角色返回给父代理（降级模式下返回给自己验收）的最小交付物，且强调"No other prose"（不得有其他文字）：

1. 写出的文件路径（file paths written）；
2. 五行摘要，覆盖三个维度：调色板策略（palette strategy）、字阶形状（type ramp shape）、命名规则（named rules）；
3. 一行 not-canonized 声明：点名构建中你刻意没有典入系统的内容及原因。

三项要求分别对应"可验证性"（路径可复查）、"信息密度"（五行强制压缩，防止流水账）与"第 4/5 步的落地"（缺陷必须显式出现在返回中，而不是被静默丢弃）。

八、在 impeccable 流程中的位置与工程校验

把本文放回 new-work.md 的收尾编排，Documenter 的触发时机与复跑规则是：

• 它在finish review 的最后一轮修正落地之后运行——"the documenter runs after the last correction lands"；
• 任何修正轮次若发生在文档化之后，必须对变更面重跑 documenter，因为过期的 DESIGN.md 会把已修复的缺陷重新教给后续生成新屏幕的代理；
• 它的输入来自父代理的完整上下文：项目根、产物路径、方向契约、PRODUCT.md、document.md 引用路径与写入边界。

工程侧对这条单源链路的校验集中在 tests/build.test.js 的 "degraded-mode fallback reference generation" 测试组，共四条断言：

断言	验证点
每个 agent 都产出 reference/degraded/<role>.md 且前缀剥离	恰好是 asset-producer.md、documenter.md、finish-reviewer.md、manual-edit-applier.md 四个文件
前导段 + 正文特征短语	文件以生成标记开头，并包含源正文中的特征词（同组内用 material_fixes 证明源正文被内联）
provider 块编译	合成代理的 <codex> 块在 codex 目标保留、在 claude-code 目标剔除，前导段在两端一致
仓库无手写 degraded 文件	skill/reference/degraded 目录必须不存在

九、要点小结

• degraded/documenter.md 是 skill/agents/impeccable-documenter.md 经 factory.js 构建管线生成的降级运行手册，头部前导段规定了内联执行时的角色隔离与自验收方式；
• 该角色的核心原则是事后记录（ground truth is the shipped artifact），配合 max-turns: 30 的硬预算，采用"批量读、先规范后样式表、中途开写"的生存策略；
• 五步工作流的关键防线是第 4、5 步：禁止"为缺陷背书"和"把 craft-floor 禁项典入系统"，后者以 craft-floor.md 的 kicker、硬偏移阴影、glyph 图标、系统展示字体禁项为边界；
• 输出契约限定为"路径 + 五行摘要 + 一行 not-canonized 声明"，保证每次运行都留下可验证、可审计的记录；
• 整条单源链路（agent 定义 → 构建 → 降级引用 → 测试断言）意味着修改该角色行为必须编辑 skill/agents/impeccable-documenter.md，而非任何生成产物。