- 本文件提供仓库级默认规则，适用于整个仓库。
docs/AGENTS.md用于补充当前版本文档规则；离工作目录更近的规则优先。- 如需为历史版本或其他子目录定义不同要求，应在对应目录下补充
AGENTS.md或AGENTS.override.md。
- 当前版本文档位于
docs/。 - 历史版本文档位于
versioned_docs/。 - 当前版本导航位于
sidebars.js。 - 历史版本导航位于
versioned_sidebars/。 - 站点配置位于
docusaurus.config.js。 - 常用校验命令：
npm run remark:once。 - 常用构建命令：
npm run build。
- 用户要求 review 时，默认进入 review 模式：优先识别会误导用户、破坏导航、破坏构建、或引入事实性错误的问题，而不是大段润色。
- 先看本次改动范围；如果能拿到 diff，就以 diff 为主，避免对未改动区域做泛化点评。
- 优先给出可定位的问题：结论应尽量落到具体文件和行，并说明用户影响。
- 单纯风格偏好不作为 finding；已清晰的句子不要为了“更像 AI 优化过”而重写。
- 如果没有发现问题，应明确写出“未发现 findings”，并补充剩余风险或未验证范围。
P1：会导致链接、锚点、导航、构建失效，或会直接误导用户执行错误步骤、错误命令、错误参数、错误前提、错误能力判断、错误兼容性判断的问题。P2：不会立刻造成失败，但会明显增加理解成本或造成轻度误导的问题，例如术语不一致、标题层级异常、路径或 UI 名称漂移、页面内容与导航描述不一致。P3：不改变含义的错别字、病句、轻微歧义、可直接修复的小问题。- 单纯审美、措辞口味、句式偏好不计入 findings。
- 一条 finding 只说明一个问题，避免把多个缺陷揉成一条。
- 每条 finding 应包含：位置、问题本身、用户影响；能给出验证方式时，再补充验证方式。
- 除非用户明确要求，不要给整页重写方案；优先给最小、可执行的修正方向。
- 不确定产品行为、默认值、限制条件、兼容性或连接器能力时，不要猜测；应明确写“未验证”或“需要产品/实现侧确认”。
- 如果是行内评论或 review pane 场景，优先给针对具体 diff 行的反馈，并保持修改范围最小。
- 不要随意修改代码块、命令、参数名、接口字段名、UI 名称、版本号、路径、示例值或限制说明。
- 操作步骤应具备前提、顺序和可验证结果；三者缺任何一项时，优先从准确性和可执行性角度反馈。
versioned_docs/**代表历史版本内容，不要未经证据把历史版本静默对齐到当前版本行为。- 如果当前版本与历史版本可能同时受影响，应明确指出需要同步检查的范围，而不是默认两边一起改。
- 评审涉及
sidebars.js、versioned_sidebars/**、front matter 的id或slug、跨文档链接、标题锚点时，应同时检查导航、doc id、锚点和引用关系是否一致。 - 如果你在执行修复而不是纯 review：修改链接、标题、相对路径后优先运行
npm run remark:once；修改 sidebar、文档 ID、版本化内容或站点配置后，条件允许时运行npm run build。
- 当改动涉及
docs/prerequisites/**或versioned_docs/**/prerequisites/**时，可在条件允许时轻量核对连接器实现或元数据来源。 - 公开可参考来源之一是 Tapdata connectors 仓库。
- 如果对应连接器源码不可见、位于私有仓库，或无法可靠定位实现，则跳过该项核对，并注明未验证。
- 仅标记明显冲突的情况，例如 CDC、写入能力、增量支持、数据类型、认证方式、网络或权限前提、限制条件等与实现明显不一致。
- 不要将“缺少外部旁证”本身当作缺陷。