项目文档位于 docs/。入口：docs/README.md — 包含项目概述、文档结构说明和所有包的导航索引。
修改任何包的代码时，需同步更新对应文档：
| 代码变更类型 | 需更新的文档 |
|---|---|
| 新增/删除功能、改变对外行为 | docs/{pkg}/models/README.md |
| 修改模块架构、依赖关系、技术选型 | docs/{pkg}/tech/README.md |
| 改变命名约定、代码模式、编码规范 | docs/{pkg}/specs/README.md（通用规范变更则更新 docs/extra/common-specs.md） |
| 新增跨包机制或共享约定 | docs/extra/ 中对应主题文档 |
| 修复了 docs/TODO.md 中记录的问题 | 标记为 [x]，记录结论，不删除条目 |
PR 和 code review 时应将文档同步作为检查项。
每次提交前，必须使用仓库配置的 Prettier 格式化本次修改中受支持的文件，并确认格式检查通过：
pnpm exec prettier --write <files...>
pnpm exec prettier --check <files...>不要为满足该要求格式化与本次提交无关的文件。全仓格式化必须作为独立提交。
docs/ 下所有 .md 文件需在标题后包含一致的 AI 生成声明：
> ⚠️ 本文档由 AI 生成，主要用于辅助 AI 理解项目。内容可能与实际代码不同步，请注意甄别。
新建文档时必须添加此标识。