dx-audit

DX 审计

审计或改进开发者导入、运行、配置的内容，以及出错时会阅读的内容。

• **是：**对公共 API、面向开发者的错误信息、CLI 命令、导出类型、安装和首次运行体验以及配置进行范围明确的审查；仅在用户要求时进行修复。
• **不是：**全仓库质量检查（tidy）、终端用户 UI（ui-design 的 Audit 模式）、Agent 信任审查（ax-audit）、公共网站或文档的 Agent 评分（agent-ready）、文档文案或 README（ghostwriter）、仓库架构（codebase-architecture），或构建新的 CLI（scaffold-cli）。

模式

选择请求所支持的最窄模式，并在阅读代码前用一行文字说明范围：

模式	适用情形	输出
针对性（默认）	指定或已更改的公共接口	只读的问题报告
修复	用户要求修复、改进、简化或实现	在说明的范围内进行局部修改，然后验证
穷尽	用户明确要求审查整个软件包或所有公共接口	列出所有重要问题，并按接口分类

Scope: <mode>; surfaces: <commands/exports/config>; prefixes: <err-, cli->; excludes: <UI, docs, architecture, private internals>

仅凭「DX」、「黄金标准」和「全面审查」等说法，不会将针对性审计扩大为穷尽审计。若同时调用多个技能，本技能只负责上述接口。

审计进度

DX audit progress:
- [ ] 1. Lock the public surface and write the scope receipt
- [ ] 2. Gather local evidence and run the safe probes
- [ ] 3. Select prefixes, then open candidate rules
- [ ] 4. Rank root causes
- [ ] 5. Report, or fix when asked
- [ ] 6. Verify on the same scope

1. 锁定公共接口范围

从相对于常规基准分支的 git diff 入手，只保留可从公共入口访问到的已更改文件：package.json 中的 exports 或 bin、命令注册表、导出类型、有文档说明的配置加载器，或已观察到的错误路径。若没有有用的差异，则使用用户指定的命令、导出项、错误或配置。私有辅助函数只有在被公共调用方使用时才纳入范围。

2. 收集证据，然后停止

1. 本地说明、清单，以及差异或指定的入口点。
2. 直接依赖的公共依赖项，以及最接近、能锁定行为的测试。
3. 对本地构建进行安全探测：
   • CLI：运行 --help、--version、一条成功路径、一条无效输入路径，并将同一命令的 stdout 通过管道传递（| cat），以检查非 TTY 行为。切勿通过触发真实变更来测试 DX；若支持 --dry-run，则使用它。
   • 软件包：构建后运行 pnpm dlx publint 和 pnpm dlx @arethetypeswrong/cli --pack .。这些命令会检查打包情况，但打包可能会执行生命周期脚本。调用 --pack 前，先检查这些脚本，或使用一次性检出。
4. 仅当差异更改了公共导出、签名或返回结构时，检查之前的发布约定。

当行为已得到证实、证伪，确认属于私有内容或确认超出范围时，即停止。只有在用户明确要求比较，或本地证据无法解决某个指定的不确定问题时，才进行外部调查；本技能所依据的标准已记录在 references/standards-map.md 中。

3. 先按候选规则分派

阅读 rules/_sections.md，然后按适用面选择前缀：

优先级	前缀	类别	默认影响	规则数
1	api-	公共 API 和 SDK	CRITICAL	7
2	err-	面向开发者的错误	CRITICAL	5
3	cli-	面向用户和 Agent 的 CLI 体验	HIGH	13
4	types-	导出类型的易用性	HIGH	5
5	onboard-	安装和首次运行	HIGH	5
6	config-	配置易用性	MEDIUM	3

适用面	前缀
公共 API 入口	api-、types-、已触及路径中的 err-
CLI 命令	cli-、已触及路径中的 err-
导出声明	types-；行为发生变化时还包括 api-
安装、package.json、首次运行	onboard-
配置加载器	config-、已触及路径中的 err-

适用性优先于优先级：仅针对 CLI 的审计不会加载 api-，即使 API 规则的优先级更高。

定向模式：列出所选前缀的文件名（这些名称就是检查清单），查找具体证据，然后只打开调查发现所需的规则文件。穷尽模式：阅读所选前缀下的每条规则。

能力门槛（在所选前缀内应用）：

• 当承诺、请求或已支持自动化或 Agent 使用时，适用结构化 JSON 输入、架构自省和紧凑轮询快照。
• 对破坏性、耗费资源或难以撤销的变更操作，适用试运行和确认机制。
• 对可能阻塞、持续时间超过单条命令或在输出含糊时需要重试的操作，适用进度和恢复机制。
• 当命令在语义上接受文件或流数据时，适用 stdin。
• 仅当公共契约发生变化时，适用稳定契约比较。

4. 按根本原因排序，而非按实例排序

• 按每条引用规则的 frontmatter impact 对 CRITICAL、HIGH、MEDIUM 排序，并原样复制。影响指规则声明的后果，而非置信度评分：某个子命令失败时仍返回 0，影响等级依然是 HIGH，因为它绕过的 CI 门禁相同。引用前先打开规则文件，因为凭记忆引用的 ID 可能与文件内容不符；若不存在对应文件，则删除该引用。
• 将同一根本原因的重复实例合并为一条发现，最多列出三个代表性位置。某一适用面中缺少 JSDoc、错误代码或 --json，应作为一条发现，而不是每个符号各列一条。
• 没有当前使用路径的缺失功能不构成缺陷。
• 定向模式：列出所有 CRITICAL 发现，然后按价值从高到低列出其余发现，总数最多五条；其余内容按类别概述。

5. 报告或修复

审计请求为只读。修复请求授权在收据范围内进行局部更改，不授权重新设计相邻文档、UI 或架构。

## DX Audit

Scope: `tool status` CLI; `err-`, `cli-`; 4 files inspected.

### Findings
- [HIGH] `cli-idempotent-resume` at `src/start.ts:42`: retrying the same target creates a second job.
  Fix: return the existing job id and state unless the caller passes `--fresh`.

### Deferred
- 2 lower-impact config candidates were outside the locked CLI scope.

只列出有发现的文件；无问题的适用面用一条通过说明列出已检查的适用面和规则文件。修复模式下，将 Deferred 替换为 Changed 和 Verification（已通过的准确命令或探测）。篇幅应与发现数量相符，而非套用模板。

6. 在相同范围内验证

重新打开每个已修改或引用的位置，重新运行相同的探测和针对性项目检查，并重新应用相同的候选规则。让证据与声明相匹配：构建成功无法证明 CLI 行为，运行时探测无法证明导出类型，只有 attw 或消费者风格的 tsc 导入才能证明类型解析。

参考文件

文件	阅读时机
rules/_sections.md	每次审计时，确定前缀的适用性和优先级
rules/<prefix>-*.md	候选规则有证据时，或处于穷尽模式时
references/standards-map.md	发现需要外部引用、用户询问某项为何属于规则，或需要依据边界情况作出判断时
rules/_template.md	添加或编辑规则时

易踩坑

• pnpm dlx <pkg>（或 npx）和全局安装检查的是注册表中的副本，而不是工作树中的版本。 此时，--help、退出码和错误字符串描述的是已发布版本。先构建，再调用本地入口点（node ./dist/cli.js）。
• 通过管道运行时，process.stdout.isTTY 的值是 undefined，而不是 false。 如果防护条件写成 isTTY === false，通过管道输出时就不会禁用颜色或旋转指示器，因此 ANSI 代码会写入重定向的文件。用 | cat 检查，不要盲信防护条件。
• 在 console.log 后立即调用 process.exit(1)，可能会截断原本要说明情况的输出。 stdout 通过管道输出时是异步写入的，因此 CLI 打印用法说明后调用 exit()，在 | cat 下可能什么都不输出。解决方法是设置 process.exitCode = 1，然后自然返回（cli-exit-codes）。
• 能够正确读取的 exports 映射，解析结果仍可能有误。 在 "type": "module" 下，指向 .js 文件的 "require" 会伪装成 CJS；而列在 import 之后的 types 条件永远不会被命中。publint 和 attw 能发现这两种问题；只读取映射则无法发现（onboard-exports-resolve-typed）。

相关技能

• ui-design 审核模式：检查面向最终用户的前端质量和无障碍性
• ax-audit：检查相同的文件，但面向不同的读者；它关注 Agent 能否操作并从故障中恢复，而本技能关注开发者是否觉得界面易用
• scaffold-cli：使用这些现成模式构建新的 CLI；本技能则审核已有内容
• tidy：检查差异的一般正确性和结构
• agent-ready：检查公开 HTTP/文档的 Agent 评分（AFDocs、Is Agentic、Is It Agent Ready）；本技能则审核软件包建立后的状态
• ghostwriter：文档文案、README 结构和面向初次阅读者的叙述
• agents-md：AGENTS.md 和 CLAUDE.md 指令文件
• codebase-architecture：检查仓库内部的结构和模块契约，而非软件包对外发布的界面

仅用于维护：evals/evals.json 和 evals/evaluation-scenarios.md 保存了针对本技能变更的回归场景；用户任务期间不会加载这两个文件。