seiso: A Markdown convention and linter for project docs written by AI and read by humans and agents（给 AI 写、人读、Agent 解析的项目文档立规矩）

📅 2026-09-27（7 天爆发窗口） | 🏷️ 值得研究的仓库 | ⭐ 163（7天）
🔗 原文：https://github.com/scarletkc/seiso

是什么

seiso 是一个用 Rust 编写的 Markdown 书写规范 + Linter（格式检查器），专门针对一类新文档：由 AI 写成、由人类和 AI Agent 共同阅读的项目文档。目标很简单——让机器产出的文档结构可预测、机器可解析、人也能舒服地读。2026-09-27 创建，一周左右 163 星。

🔍 小白解读

先说几个词

• Linter（代码/文本检查器）：自动检查你的文件有没有"不合规矩"的地方并报错或修好的工具，像 Word 里的语法检查，但更严格、可配置。
• 规范（convention）：大家约定俗成的写法标准，比如"标题层级不能跳级"。有了规范，机器才知道去哪找信息。
• Agent 解析：AI 助手读你的文档来获取上下文——它不像人一样"看"，而是靠结构化的格式快速定位信息。
• Rust：一种以速度和内存安全著称的编程语言，工具类项目常用。
• 上下文（context）：AI 干活前塞给它的背景资料。文档质量直接决定 Agent 干活质量。

这篇到底在说什么

现在大量项目文档是 AI 生成的：今天让 Claude 写个 README，明天让 Agent 补个设计文档。问题是每个模型、每次生成的排版习惯都不一样，人读着累，Agent 解析时更容易抓错重点。打个比方：团队里的实习生们每人一套记笔记的格式，三个月后谁也找不到东西。seiso 的思路是"先立规矩，再机器验收"——定义一套面向"AI 写、人读、Agent 解析"三方需求的 Markdown 规范，然后提供一个 Linter 在 CI 里强制执行，谁（包括 AI）不守规矩就报错。它把"文档质量"从口头约定变成了可自动化检查的工程问题。这类"规范+工具"的小项目一周 163 星，说明社区已经痛感到了 AI 生成文档的失控。

这跟普通人有什么关系

只要你的团队开始用 AI 写文档——操作手册、会议纪要、代码注释——就会遇到"机器写的文档越攒越乱"的问题。这类工具能让文档库保持整洁，长远看帮你省下大量"找资料、对格式"的时间。

为什么值得架构师关注

这是"文档即上下文（docs-as-context）"工程化的一个信号：当 Agent 成为一等读者，文档格式规范就变成了接口规范——接口就要有 schema、有校验、有 CI 门禁。对团队的具体影响：① 内部知识库若要喂给 Agent，先定义文档规范并接入 Linter 门禁，可以显著提升 RAG/Agent 检索命中率（结构混乱的文档是检索噪音的主要来源）；② 评估将其纳入 monorepo CI 的成本很低（Rust 工具、单二进制）；③ 更大的意义是方向验证——"为机器读者优化文档"会衍生出一批标准，早跟进的团队迁移成本低。注意项目还年轻（163 星），规范设计是否合理需自行评估，别直接全量强制。

核心内容

• 定位精确：面向"AI 生成 + 人类阅读 + Agent 解析"三方的 Markdown 项目文档规范与 Linter。
• Rust 实现，2026-09-27 创建，一周约 163 星（7 天窗口），属于刚冒头的早期项目。
• 核心价值主张：把 AI 生成文档的质量控制从"人肉 review"变成"自动化检查"。
• 与 CLAUDE.md / AGENTS.md 等新兴"Agent 读取文档"惯例同属一个趋势：文档的读者从人扩展到机器。

行动建议

适合作为试点引入：挑一个文档重灾区的仓库，跑一遍 seiso 看报错分布，评估其规范条目与团队现状的契合度；合理的条目可以吸收进团队自己的 docs lint 规则（不一定整体采用）。同时建议架构师把它当作一个信号跟踪："文档规范即 Agent 接口规范"这条线后续会出现更多标准，提前在知识库治理中预留位置。