audit

audit skill 概览

audit skill 的作用

audit skill 会对已实现的前端界面执行一次技术型 UX Audit，并将发现整理成结构化报告。它会围绕可衡量的质量维度进行检查，包括可访问性、性能、主题一致性、响应式表现，以及实现层面的反模式；随后为每个维度打分，并按严重程度用 P0 到 P3 标记问题。

谁适合安装 audit

这个 audit skill 最适合前端工程师、设计工程师、UX 工程师，以及需要在发布前审查页面、组件或功能的 AI agent。尤其当你需要的是可重复执行的审计流程，而不是一句模糊的“帮我 review 这个 UI”时，它会更有价值。

它真正解决的工作问题

大多数用户并不需要泛泛而谈的反馈，他们真正需要的是一种审计方式，能够：

• 聚焦有代码依据的问题
• 区分关键缺陷和细节打磨
• 避免过早进入修复阶段
• 产出一份可直接交接给后续实现工作的报告

这正是它的核心价值：在你让另一个 skill 或 agent 动手修改之前，先跑一轮技术质量审查。

这个 audit 与通用提示词的差异

这个 audit skill 最大的区别在于边界非常清晰。它明确把 audit 定义为技术审查，而不是视觉审美点评。它要求围绕五个维度做诊断式扫描，使用统一的评分模型，并按严重级别输出问题和行动计划。这样一来，不同页面之间的结果更容易横向比较，也更容易直接转成后续任务。

采用前需要注意的一点

这个 skill 依赖前置上下文。它自己的说明要求先调用 $frontend-design，如果设计上下文仍然缺失，还要在审计前运行 $teach-impeccable。如果跳过这些准备，输出质量会明显下降，因为这个 audit 依赖共享的设计原则和上下文收集规则。

如何使用 audit skill

audit 的安装与上下文准备

在你的 skills 环境中，从 pbakaus/impeccable 仓库安装 audit skill：

npx skills add pbakaus/impeccable --skill audit

由于这个 skill 位于 .codex/skills/audit 下，实际决定是否安装，重点不在依赖包，而在于它是否契合你的工作流。你应该预期在支持 skill 调用、并且能配合同仓库其他 skill 一起使用的环境中运行它。

先读这个文件

先看：

• SKILL.md

这个文件基本涵盖了所有关键行为：前置条件、审计范围、评分方式，以及期望的报告风格。这个 skill 目录下没有可见的辅助脚本或参考文件，所以大部分实现与使用指导都集中在主 skill 文档里。

运行 audit 前的必备前置步骤

不要在没有上下文的情况下直接调用 audit。这个 skill 明确要求先调用 $frontend-design，因为其中包含本次审计会用到的设计原则、反模式定义，以及上下文收集协议。如果当前还没有设计上下文，就需要先运行 $teach-impeccable，再执行审计。

实际顺序通常是：

1. 收集设计和产品上下文
2. 明确要评审的是哪个页面或组件
3. 运行 audit
4. 用生成的报告驱动后续修复任务，交给另一个任务或 skill 执行

audit skill 需要什么输入

当你给出明确目标和评审上下文时，audit skill 的效果最好。高质量输入通常包括：

• 具体的页面、路由、组件或流程
• 相关代码位置或文件
• 目标设备范围
• 如有必要，说明框架或技术栈
• 已知约束，比如遗留 CSS、设计系统限制或性能预算
• 本次评审是发布前检查、回归检查，还是探索性审计

一个弱请求是“audit my app”。一个更强的请求是：“run an audit for the checkout page on mobile and desktop, focusing on accessibility, loading behavior, and responsive breakpoints.”

把模糊目标变成可用的 audit 提示词

一个好用的 audit 提示词，应该明确目标、划清边界，并要求结构化输出。例如：

• “Run the audit skill on the pricing page. Review accessibility, performance, theming consistency, responsive behavior, and implementation anti-patterns. Score each dimension 0-4, list P0-P3 issues, and end with an action plan. Do not fix anything yet.”
• “Use audit for the settings modal component. Check keyboard support, semantic structure, focus handling, contrast, theme token usage, and mobile layout failure points.”

这类提示词比泛泛的 review 请求更有效，因为它贴合了这个 skill 的报告模型。

audit 实际会检查什么

根据 skill 的说明，这个 audit 覆盖五个维度：

• 可访问性
• 性能
• 主题一致性
• 响应式设计
• 反模式

其中，可访问性部分在源说明里最具体，涵盖对比度、ARIA、键盘导航、语义化 HTML、alt text，以及表单问题。这说明这个 audit 明显偏实现层面，更可能产出可落地的具体缺陷，而不是抽象建议。

预期输出格式，以及它为什么重要

这个 audit skill 的价值不只是有一张检查清单，更在于输出结构本身：

• 按维度逐项评审
• 每个维度给出 0-4 分
• 用 P0-P3 标记严重程度
• 提供可执行的行动计划

这种结构非常适合做分级处理。团队无需重读整份报告，就能把发布阻塞项和可进 backlog 的改进项区分开。

最适合 audit 的工作流

一个实用的 audit 使用流程通常是：

1. 先用必需的前置 skill 补齐设计上下文
2. 选定一个页面、功能或组件
3. 提供实现范围和约束
4. 运行 audit skill
5. 查看评分和严重程度
6. 将行动计划转成 ticket，或继续生成后续修复提示词

这个 skill 在范围明确的界面上效果最好。如果你试图一次审完整个产品，结论通常会变浅，优先级判断也会变差。

什么时候该用 audit 做 UX Audit

当你需要基于实现证据来判断 UX 质量问题时，就适合使用 audit for UX Audit。它尤其适合：

• 发布前就绪性检查
• 改版后的回归检查
• 横向比较不同页面的技术质量
• 在用户测试前识别可访问性和响应式缺陷
• 为另一个 agent 生成待修复缺陷清单

但它并不适合纯研究类问题，比如信息架构、文案表达是否清晰，或品牌视觉探索。

audit 的边界与不适用场景

这不是一个设计点评 skill，也不是一个修复型 skill。它的职责是记录问题，而不是解决问题。如果你的真实目标是“让这个页面更好看”，那只有在你同时也需要一份技术缺陷清单时，安装它才更值得。如果你的目标是“现在就重写这个组件”，那除非质量风险很高，否则这一步 audit 可能并不必要。

audit skill 常见问题

audit skill 对新手友好吗？

友好，前提是你已经清楚要审哪个界面。这个 skill 给出了比较明确的审计框架，但新手很容易忽略前置上下文这一步。如果该用时没有先跑 $frontend-design 和 $teach-impeccable，audit 结果就可能变得空泛或前后不一致。

我需要整个 impeccable 仓库吗？

对于这个 skill 来说，依赖更多是概念层面的，而不是大量文件层面的。可见的 audit 目录里只有 SKILL.md，但说明中明确依赖同仓库中的其他 skill。所以更实际的做法是拿到整个仓库级别的访问能力，而不是孤立地只拿这一个文件。

audit 比直接让 AI review 我的 UI 好在哪？

普通提示词经常会把主观审美意见和技术缺陷混在一起。这个 audit skill 会强制收窄范围、统一审查维度，并输出带评分的结果。通常这会带来更好的问题分级、更强的多次审计可比性，也能减少在模糊评论上来回争论的时间浪费。

audit 能自动修复问题吗？

不能。这个 skill 的设计目标就是做诊断和报告。如果你希望把评审和实现清晰拆开，这其实是它的优点，而不是缺点。你可以把它产出的报告交给后续独立的修复任务来处理。

我应该先 audit 什么？

建议先从一个高影响面的界面开始：

• 首页首屏和导航
• 注册或结账流程
• 仪表盘入口页
• 共享组件，比如 modal、form、table

这些区域通常能很快暴露可访问性、响应式和性能问题，让你的第一次 audit 更有价值。

什么情况下不该用这个 audit skill？

以下情况可以跳过这个 audit：

• 你只想要主观的设计灵感
• 你还没有可供检查的具体实现
• 你需要的是完整产品研究，而不是技术审查
• 你只是要快速上线一个原型，不需要带评分的正式报告

如何提升 audit skill 的使用效果

给 audit 更聚焦的目标

提升 audit 输出质量最快的方法，就是收窄范围。尽量只审一个路由、一个流程，或者一类组件。“Audit the account deletion flow” 通常会比 “audit the whole app” 产出更强的发现。

提供这个 skill 预期的上下文

因为这个 audit 依赖前端设计上下文，所以最好在一开始就补足它需要的背景信息：

• 页面对应的用户目标
• 预期交互模型
• 设备优先级
• 主题或设计系统规则
• 业务约束

这样可以减少误报，也能让它按真实设计意图去判断哪些属于反模式。

明确要求只输出有证据的发现

如果你想让这个 audit 在实际使用中更可靠，可以明确要求它只输出可观察、可举证的问题。例如，让 agent 为每条发现都指明对应的元素、模式、状态或行为。这样报告会更贴近实现现实，也更容易复核。

用发布上下文提升严重程度判断质量

当你定义了影响场景后，严重程度标签会更准确。要告诉 audit 当前目标属于哪一类：

• 面向公众的营销页面
• 登录后的产品界面
• 结账或转化流程
• 内部工具
• mobile-first 体验

比如，checkout 中的键盘陷阱，严重程度就应该与 admin 页面里纯视觉间距不一致的问题区分开来。

audit 使用中的常见失败模式

最常见的问题包括：

• 跳过必需的前置 skill
• 一次审查过大的界面范围
• 让它直接修复，而不是先做诊断
• 没有提供设备或 viewport 上下文
• 把主观设计偏好当成技术缺陷

这些问题通常会导致报告噪音更大、优先级更弱，或者审计范围混乱。

哪些更强的输入能提升 audit 输出质量

更好的提示词通常会包含这类具体信息：

• “focus on keyboard navigation and forms”
• “treat mobile Safari as a priority”
• “check theme token consistency in dark mode”
• “flag only measurable anti-patterns”
• “score each dimension and end with top 5 fixes by impact”

这些细节能帮助 audit 把深度放在真正重要的地方。

第一次 audit 之后该如何迭代

第一轮之后，不要原样重复跑同一个宽泛提示词。更好的做法是：

1. 先修复或筛选最高严重级别的问题
2. 在同一块有边界的界面上重新运行 audit
3. 针对得分最低的维度要求更深入检查
4. 对比分数变化以及仍未解决的 P0-P1 问题

这样，audit skill 就能从一次性报告工具，变成可重复执行的质量门禁。

将 audit 与后续实现工作配合起来

当 audit 作为两步工作流中的“诊断阶段”使用时，效果最好。第一步，先生成报告；第二步，把这份报告作为结构化输入，交给单独的实现流程去处理。这样既能保留 audit 的客观性，也能避免“边改边审”把重要缺陷掩盖掉。