Hai Audit Docs Against Code

Hai Audit Docs Against Code

For Chinese readers, see SKILL.zh_CN.md. The English SKILL.md is the execution source of truth.

Overview

Find stale or implementation-inconsistent claims in README and documentation, each backed by evidence from source code, configuration, schemas, API contracts, or generated types. The audit runs in both directions — docs-to-code and code-to-docs — and reports findings as a severity-ranked list, not prose.

Core Principles

1. Code is truth: when documentation conflicts with implementation, source code, configuration, and contract files win. 2. Contracts first: OpenAPI, protobuf, GraphQL schema, database schema, and TypeScript types are strong sources of truth — prefer them over hand-written prose. 3. Tighten safety defaults: security, permissions, sandboxing, privacy, billing, and destructive operations get elevated severity (see Severity table). 4. Evidence before judgment: every issue needs a concrete doc location and a concrete code/config/contract reference — operationalized in the Workflow. 5. Audit by scenario: organize around real user/developer/operator scenarios, not file-by-file scavenging — operationalized in the Workflow. 6. Explain the repair value: every fix states the benefit (reduced misuse, smoother onboarding, fewer failed integrations) — a required per-issue field.

Workflow

1. Enumerate the documentation surface.

• When the user names targets — a single file or any batch of files — audit exactly those.

Do not widen the scope to sibling docs or a whole directory uninvited.

• Only when no target is given, default to the standard surface: root README, docs/**/*.md,

API docs, examples, setup guides, generated docs.

• Contract files: OpenAPI, protobuf, GraphQL schema, database schema, and TS types.

2. Define audit themes.

• Extract 3-8 concrete scenarios from the README, docs, APIs, and configuration (quickstart setup, API integration, environment configuration, permissions/security, lifecycle states, domain entities).
• Group issues by theme; use a general documentation-hygiene bucket only when no theme fits.

3. Review each document (docs-to-code), driven by references/checklist.md.

• Use the checklist to extract important claims: behavior, commands, defaults, fields, API endpoints, permissions, examples, lifecycle states, configuration.
• Search the codebase for the matching implementation or contract.
• Classify mismatches: missing feature, renamed concept, changed behavior, outdated default, broken command, stale example, wrong API shape, or unsupported claim.
• Record each issue with the per-issue fields under Output.

4. Cross-check from implementation back to docs (code-to-docs), also driven by references/checklist.md.

• Use contract files, configuration, routes, CLI definitions, public types, and tests to find user-facing behavior that docs omit or describe incorrectly.
• Prioritize omissions that cause setup failure, integration failure, unsafe operation, or wrong mental models.

5. Produce the audit.

• Assemble findings into the report; keep uncertain findings as "needs evidence" rather than overstating them.
• Read references/output-template.md and fill it in before finalizing.

Severity

Elevate severity by at least one level when the claim touches security, permissions, sandboxing, privacy, billing, or destructive operations — a wrong claim there is more dangerous than elsewhere.

Output

Each issue carries: severity, document location, implementation/config/contract evidence, impact, minimal suggested fix, repair value, and related principle. End with a summary verdict (pass / conditional pass / fail), counts by severity, and a recommended fix order.

The full report shape — issue fields, summary verdict table, and worked examples — lives in references/output-template.md. Read it and fill it in before finalizing; do not invent a second schema.

Parallelization

If scope is large, split work by documentation type (README / API docs / setup docs / guides), module or feature area, or direction (docs-to-code and code-to-docs). When combining parallel audits, deduplicate issues and normalize severity.

Use a different skill when

• The comparison is doc-vs-doc with no codebase as truth source (internal contradictions, stale sections, duplication) — use hai-audit-docs-internally.
• You are auditing entity/data-model fields against a PRD (which fields exist, store-vs-compute, column-vs-config) — use entity-model-auditor.
• The document has drifted from the discussion conclusions and the user wants it rewritten, not a mismatch report — use hai-rewrite-doc.

审核检查清单

目录

1. README 功能与特性 2. 对外接口与合同 3. 配置与环境变量 4. 安全与权限 5. 运行方式与脚本 6. 视图与模块行为 7. 测试与质量保证 8. 术语与命名

---

1. README 功能与特性

• [ ] README 中的功能/特性是否都有清晰实现或入口？
• [ ] 是否有已下线或隐藏的功能仍写在 README 中？
• [ ] 文档声明的支持平台/协议/格式是否与代码真实支持范围一致？
• [ ] 版本号、依赖版本是否与 package.json/requirements.txt 一致？
• [ ] 项目架构图是否反映当前目录结构？

2. 对外接口与合同

• [ ] 文档中的 API 示例、参数、返回值是否与 OpenAPI/proto/schema/TS types 一致？
• [ ] 文档中声称存在的端点/方法，代码中是否真实存在？
• [ ] 代码中已有的新接口，文档是否尚未更新？
• [ ] 请求/响应字段名称是否一致？
• [ ] 必填/可选参数是否标注正确？
• [ ] 默认值是否与实现一致？
• [ ] 错误码/状态码是否完整列出？

3. 配置与环境变量

• [ ] 文档列出的环境变量名称是否与代码中读取的一致？
• [ ] 环境变量默认值是否与代码中的 fallback 一致？
• [ ] 必填环境变量是否正确标注？
• [ ] Feature Flags 是否在代码中真实存在？
• [ ] 配置文件路径是否正确？
• [ ] 配置项的类型（string/number/boolean）是否正确？

4. 安全与权限

• [ ] 认证方式是否与实现一致（JWT/Session/OAuth）？
• [ ] 角色/权限/scope 定义是否与代码中的检查逻辑一致？
• [ ] sandbox/contextIsolation 等安全设置是否如文档所述启用？
• [ ] 加密/HTTPS 是否如文档所述配置？
• [ ] CORS 策略是否与文档描述一致？
• [ ] CSP 策略是否与文档描述一致？

5. 运行方式与脚本

• [ ] 启动命令是否与 package.json scripts 一致？
• [ ] 构建命令是否能成功执行？
• [ ] 测试命令是否与测试框架配置一致？
• [ ] 部署命令是否与 CI/CD 配置一致？
• [ ] 「快速开始」步骤是否能一键跑通？
• [ ] 是否引用了已移除的脚本或目录？
• [ ] 依赖安装命令是否正确？

6. 视图与模块行为

• [ ] 文档描述的关键页面/模块是否有对应组件存在？
• [ ] 文档提到的按钮/开关/选项是否真实存在？
• [ ] 组件行为是否与文档描述一致？
• [ ] 路由路径是否与文档一致？
• [ ] 截图是否反映当前 UI？

7. 测试与质量保证

• [ ] 测试框架是否与文档描述一致？
• [ ] 测试命令是否能成功执行？
• [ ] 覆盖率配置是否与文档声称一致？
• [ ] CI 流程是否与文档描述一致？

8. 术语与命名

• [ ] 类型名/枚举名/模块名是否与文档用语一致？
• [ ] 状态枚举值是否与文档中的中文描述一一对应？
• [ ] 示例代码是否能编译/运行？
• [ ] 引用的函数/类型/模块是否已被重命名或移动？
• [ ] 链接是否有效（无 404）？

---

项目类型特定检查

Electron 项目

• [ ] main/renderer 进程边界是否与文档描述一致？
• [ ] preload 脚本暴露的 API 是否与文档一致？
• [ ] contextIsolation/nodeIntegration 设置是否如文档所述？
• [ ] IPC 通道名称是否与文档一致？
• [ ] 窗口配置是否与文档描述一致？

Web 前端项目

• [ ] 路由配置是否与文档描述一致？
• [ ] 状态管理方案是否与文档一致？
• [ ] 组件库版本是否与文档一致？
• [ ] 构建输出目录是否与文档一致？

后端 API 项目

• [ ] 中间件顺序是否与文档描述一致？
• [ ] 数据库 schema 是否与文档一致？
• [ ] 缓存策略是否与文档描述一致？
• [ ] 限流配置是否与文档一致？

CLI 工具项目

• [ ] 命令名称是否与文档一致？
• [ ] 选项/参数是否与文档一致？
• [ ] 输出格式是否与文档示例一致？
• [ ] 退出码是否与文档描述一致？

文档对照代码审计输出模板

这是唯一的输出模板。整体报告骨架在最上方，单个问题项字段、审核结论表、变更影响表、示例依次列在下方。最终报告必须用这里定义的字段，不要再去别处找另一套定义。

报告骨架

# 文档对照代码审计报告

> 审核时间: YYYY-MM-DD
> 项目: [项目名称]
> 审核范围: README.md, docs/**/*.md, API/config/contract files reviewed

## 审核结论
- **结论**: 通过 / 有条件通过 / 不通过
- **汇总**: P0:<n> P1:<n> P2:<n> P3:<n> 待证据补充:<n>
- **建议修复顺序**: <highest-risk first>

## 审核主题与场景
- [主题/场景 1]: [为什么这个场景重要，覆盖哪些文档与代码]
- [主题/场景 2]: [为什么这个场景重要，覆盖哪些文档与代码]

## 问题列表

### [主题/场景 1]
[问题项，使用下方「单个问题项」字段]

### [主题/场景 2]
[问题项...]

## 已核对但无需修改
- <claim or doc area confirmed accurate>

单个问题项（字段顺序固定）

### [序号]. [一句话概括问题]

- **严重级别**: P0 / P1 / P2 / P3 / 待证据补充
- **位置**:
  - 文档: `<文件路径>:<行号>`
  - 代码: `<文件路径>:<行号>`
- **证据**:
  - 文档片段:

[简要引用相关描述]

  - 代码片段:

[简要引用关键实现/配置/合同]

- **影响**: [会如何误导用户/调用方/开发者？可能产生什么后果？]
- **建议（最小修正）**: [改「文档」还是「代码」？给出最小可行修正方向]
- **修复收益**: [改完后的具体收益，例如降低误用风险、减少排障成本、提升 onboarding 效率、避免错误集成]
- **关联原则**: [以代码为真 / 合同优先 / 安全默认收紧 / 按场景审计 / 说明修复收益]

审核结论（结尾汇总）

## 审核结论

### 结论
- [ ] **通过** — 无 P0/P1 问题
- [ ] **有条件通过** — 需先修复以下前置条件：
  1. [必须先修复的问题]
- [ ] **不通过** — 存在以下阻断项：
  1. [阻断问题]

### 汇总统计

| 级别 | 数量 |
|------|------|
| P0 Blocker | x |
| P1 Major | x |
| P2 Minor | x |
| P3 Nit | x |
| 待证据补充 | x |
| **总计** | **x** |

### 建议修复优先级
1. **立即修复 (P0)**: #[序号]: [简述]
2. **优先修复 (P1)**: #[序号]: [简述]
3. **计划修复 (P2)**: #[序号]: [简述]
4. **低优先级 (P3)**: 视排期统一处理

### 变更影响

| 影响范围 | 是否需要 | 说明 |
|----------|----------|------|
| Demo 更新 | 是/否 | [具体说明] |
| 截图更新 | 是/否 | [具体说明] |
| 脚本更新 | 是/否 | [具体说明] |
| Changelog | 是/否 | [具体说明] |
| 对外通知 | 是/否 | [具体说明] |

---

示例问题项

1. contextIsolation 安全配置与文档描述不一致

• 严重级别: P0
• 位置:
• 文档: docs/security.md:45
• 代码: src/main/window.ts:23
• 证据:
• 文档片段:

    所有渲染进程均启用 contextIsolation，确保 preload 脚本与页面脚本隔离

• 代码片段:

    webPreferences: {
      contextIsolation: false, // 实际未启用
      nodeIntegration: true
    }

• 影响: 用户/审计人员会误认为应用已启用安全隔离，实际存在 XSS 攻击风险
• 建议（最小修正）: 修改代码，将 contextIsolation 设为 true，并通过 preload 脚本暴露必要 API
• 修复收益: 安全文档与实际防护能力一致，减少审计误判，并降低渲染进程暴露 Node 能力带来的攻击面
• 关联原则: 安全默认收紧、以代码为真

---

2. API 端点 /api/users 返回字段与文档不一致

• 严重级别: P1
• 位置:
• 文档: docs/api.md:120
• 代码: src/routes/users.ts:45
• 证据:
• 文档片段:

    返回字段: id, name, email, createdAt, updatedAt

• 代码片段:

    return { id, name, email, created_at, updated_at }; // snake_case

• 影响: 前端按文档使用 camelCase 会取不到值
• 建议（最小修正）: 更新文档，标注实际字段名为 snake_case
• 修复收益: 调用方可按文档直接读取字段，减少前端联调时因命名不一致产生的定位成本
• 关联原则: 以代码为真、合同优先

Hai Audit Docs Against Code 中文版

本文件是中文阅读版；执行规则以 SKILL.md 为准。

概览

找出 README 和文档中过时或与实现不一致的声明，每个问题都以源码、配置、schema、API 合同或生成类型作为证据。审计双向进行——文档对代码、代码对文档——并以按严重级别排序的列表（而非散文）输出结论。

核心原则

1. 以代码为真：文档与实现冲突时，以源码、配置和合同文件为准。 2. 合同优先：OpenAPI、protobuf、GraphQL schema、数据库 schema、TypeScript types 都是强真相来源——优先于手写散文。 3. 安全默认收紧：安全、权限、沙箱、隐私、计费、破坏性操作提高严重级别（见严重级别表）。 4. 有证据再下结论：每个问题都要有具体文档位置和具体代码/配置/合同证据——在工作流中落实。 5. 按场景审计：围绕真实的用户/开发者/运维场景组织审计，不做逐文件松散扫雷——在工作流中落实。 6. 说明修复收益：每个修复都要说明收益（减少误用、改善 onboarding、避免集成失败）——是每个问题项的必填字段。

工作流

1. 枚举文档范围。

• 用户点名了目标——单个文件或任意一批文件——就只审这些。不要擅自把范围扩大到同级文档或整个目录。
• 只有在用户没有指定目标时，才默认审标准文档面：根目录 README、docs/**/*.md、API 文档、示例、安装指南、生成文档。
• 合同文件：OpenAPI、protobuf、GraphQL schema、数据库 schema 和 TS types。

2. 定义审计主题。

• 从 README、文档、API 和配置中提炼 3-8 个具体场景（快速开始安装、API 集成、环境配置、权限/安全、生命周期状态、领域实体）。
• 按主题归类问题；只有在没有主题匹配时才使用通用的「文档卫生」兜底分类。

3. 逐文档审计（文档对代码），以 references/checklist.md 驱动。

• 用清单抽取重要声明：行为、命令、默认值、字段、API 端点、权限、示例、生命周期状态、配置。
• 在代码库中搜索对应的实现或合同。
• 分类不一致：功能缺失、概念改名、行为变更、默认值过期、命令失效、示例过时、API 形状错误、声明无依据。
• 按「输出」中的问题项字段记录每个问题。

4. 从实现反查文档（代码对文档），同样以 references/checklist.md 驱动。

• 用合同文件、配置、路由、CLI 定义、公共类型和测试，找出文档遗漏或描述错误的对外行为。
• 优先处理会导致安装失败、集成失败、不安全操作或错误心智模型的遗漏。

5. 产出审计报告。

• 把发现汇总成报告；证据不足的发现保留为「待证据补充」，不要夸大。
• 定稿前阅读并填写 references/output-template.md。

严重级别

当声明涉及安全、权限、沙箱、隐私、计费或破坏性操作时，至少提高一级严重级别——这些地方的错误声明比别处更危险。

输出

每个问题项包含：严重级别、文档位置、实现/配置/合同证据、影响、最小修复建议、修复收益、关联原则。结尾给出汇总结论（通过 / 有条件通过 / 不通过）、各级别数量统计和建议修复顺序。

完整报告结构——问题项字段、汇总结论表、完整示例——都在 references/output-template.md。定稿前阅读并填写它；不要另造一套字段定义。

并行拆分

范围大时按以下维度拆分：文档类型（README / API 文档 / 安装文档 / 指南）、模块或功能区、方向（文档对代码、代码对文档）。合并并行审计结果时去重并统一严重级别。

什么时候改用别的 skill

• 对照对象是文档对文档、没有代码库作为真相来源（内部自相矛盾、过时段落、重复内容）——改用 hai-audit-docs-internally。
• 审计实体/数据模型字段是否符合 PRD（字段是否该存在、该存还是该算、列还是配置）——改用 entity-model-auditor。
• 文档已经偏离讨论结论、用户要的是重写而不是一份不一致报告——改用 hai-rewrite-doc。