使用 seiso 检查 AI 编写的项目文档

seiso 的作用

seiso 是一种 Markdown 约定和检查工具，用于处理由 AI 编写、供人和编码代理阅读的项目文档。它帮助代码仓库保持文档一致、易于维护，并更适合作为未来变更的上下文。

该工具根据共享约定检查文档，而不是要求每个项目自行制定文档规则。每份文档都会声明一种类型，例如 howto、reference 或 adr，并且只包含适合该类型的材料。

seiso 还倡导让每条事实都有一个权威来源。其他页面应链接到该来源，而不是重复相同信息。这样可以减少矛盾，尤其是在 AI 生成的文档将字段列表、版本、状态或数量复制到多个文件时。

文档核心原则

• 每份文档声明一种类型，并遵循该类型的用途。how-to 文档用于说明步骤，而设计依据应记录在 ADR 中。
• 每条事实只有一个归属位置。其他文档应链接到权威页面，而不是重复描述。
• 长期维护的页面应避免包含变化速度快于页面本身的值，包括版本、部署状态和数量。
• 当句子涉及具体实现细节时，应使用指针标识文件或符号。
• 完成的文档不应称呼提出请求的人，也不应叙述文档的生成过程。
• 工具无法自行判断的决策应记录理由。没有解释的例外本身就是一种违规。

seiso 专注于这些文档规则。它不会尝试判断文字是否像机器生成，也将格式和拼写检查交给其他工具。

安装 seiso

选择一种受支持的安装方式。Rust、Python 和 npm 软件包提供相同的命令行工具。

cargo install seiso

uv tool install seiso
# 或使用 pipx：
pipx install seiso

npm install -g @scarletkc/seiso

PyPI 和 npm 软件包包含适用于 Apple 芯片和 Intel 芯片 macOS、使用 glibc 的 x64 和 arm64 Linux，以及 x64 Windows 的预构建二进制文件。在其他平台上，包括 Alpine 等基于 musl 的 Linux 发行版，请使用 Cargo 安装。如果有可用的 Rust 工具链，PyPI 软件包也可以在这些平台上从源代码构建。

如果你在源代码检出目录中工作，请通过 Cargo 运行命令：

cargo run -- <command>

初始化代码仓库

从代码仓库根目录运行 seiso。首先让它创建初始配置：

seiso init

该命令会在代码仓库根目录写入 seiso.toml 文件。生成的配置包含建议的排除项和文档类型映射。在依赖结果之前，请先检查这些建议，因为初始映射只是代码仓库的起点，不能替代项目决策。

运行首次检查

检查生成的配置后，检查代码仓库：

seiso check

默认情况下，seiso check 只运行稳定规则。这些规则已满足 seiso 的晋级标准，旨在为项目提供可靠的基线。

诊断信息会指出问题发生的位置，并说明修复方法。因此，许多发现可以直接根据命令输出进行修复。当某个发现需要人工判断时，例如决定两个页面中的哪一个应作为事实的归属页面，诊断信息会指出需要作出的决定。

探索规则和文档结构

使用规则命令了解 seiso 可以检查的内容：

seiso rule --all
seiso rule <CODE>

seiso rule --all 会列出所有规则并显示其状态。使用 seiso rule <CODE> 查看单条规则及其示例。

若要在不运行规则的情况下检查 seiso 的文档模型，请使用：

seiso parse

当你学习工具如何解释文档，或调查某次检查为何产生特定结果时，这个命令很有用。

谨慎使用预览规则

尚未满足晋级标准的规则以预览功能提供。预览规则具有实验性，可能会报告误报，因此标准检查不会启用它们。

使用 --preview 选项在本地试用：

seiso check --preview

预览规则有助于及早发现潜在的文档问题，但 README 建议在规则稳定之前，不要将其用于 CI 门禁。一个实用的工作流程是将稳定规则用于必需检查，将预览规则用于可选的本地审查。

将 seiso 纳入文档工作流程

1. 使用 Cargo、uv、pipx 或 npm 安装 seiso。
2. 从代码仓库根目录运行 seiso init。
3. 检查 seiso.toml 中建议的排除项和类型映射。
4. 运行 seiso check 并解决报告的问题。
5. 需要了解诊断信息时，使用 seiso rule --all 和单条规则说明。
6. 在本地试用 seiso check --preview，但不要将预览发现用作 CI 门禁。

对于更大型的工作流程，seiso 文档提供了有关配置、规则选择和输出格式的指南，以及有关 Claude Code 钩子、pre-commit 和 CI 集成的指南。

高级指南

保持事实来源权威

当 seiso 报告信息重复或位置不当时，应确定哪个文档负责维护该事实。将规范说明移到该文档中，并从相关页面链接到那里。这样可以更安全地进行更新，也能为读者和代理提供明确的事实来源。

根据意图匹配文档类型

使用 howto 记录操作步骤，使用 reference 记录持久的事实信息，使用 adr 记录设计决策背后的理由。分开维护这些用途，可以避免页面混合说明、参考数据和历史决策内容。

记录有充分理由的例外

某些仓库决策需要判断，而不是遵循机械规则。保留例外时，应记录其原因。seiso 将没有解释的例外视为文档问题，因为未来的贡献者和代理无法判断该例外是否出于有意。

规则不明确时查阅约定

seiso 约定定义了每种文档类型的契约，以及诊断结果可以声明的证据。当你需要了解预期结构或决定如何修复问题时，应结合 seiso rule <CODE> 的输出一并查阅。

结论

seiso 为项目文档提供了统一结构和专注的验证工具。安装它，生成并检查 seiso.toml，运行稳定检查，并利用规则说明让人类和编码代理更放心地使用文档。在规则正式推广前，应将预览规则视为实验性规则，并在仓库中明确记录归属和例外相关的决策。