docs: 开发文档面向AI精简重构,补充文档编撰规范

This commit is contained in:
2026-06-01 16:43:17 +08:00
parent de51a817fb
commit b225b0a0c7
5 changed files with 177 additions and 369 deletions

View File

@@ -156,6 +156,8 @@ AI 工具必须严格遵守以下全部约束。
- 必填文本字段同时配 `required` + `whitespace`
- 操作确认用 `Popconfirm`,反馈用 antd message。
### 错误边界
- 生产入口必须启用 `ErrorBoundary``ReactQueryDevtools``DEV` 模式渲染。
---
@@ -234,3 +236,26 @@ AI 工具必须严格遵守以下全部约束。
## 更新触发条件
修改常用命令、质量门禁、开发规范(任何章节)、目录边界或开发文档索引时,必须更新本文档。
### 文档编撰规范
本节开发文档面向 AI 工具阅读,编撰时遵循以下原则:
**精简原则**
- 删除引导语、适用场景、过渡句等装饰性文字。AI 无需"应首先阅读"或"本文档说明…"类引导。
- 不重复项目结构树AI 可通过 glob 获取目录结构。
- 不重复已在 README.md 声明的规范细节专题文档只记录实现层面的函数签名、API 端点、模块职责等索引信息。
- 表格标题自明时不再加说明段落。
**信息完整性**
- 所有函数签名、API 端点(方法+路径+说明)、数据访问函数清单必须完整列举,不可用"等"省略。
- 页面行为描述须包含关键交互逻辑(如 Tab 切换、默认值、条件跳转、测试不阻止保存等),不可只写组件名。
- 配置文件列表必须完整,不可遗漏已有文件。
**结构规范**
- 每个专题文档末尾保留 `## 更新触发条件` 章节,明确列出哪些变更必须更新该文档。
- 用表格和编号列表替代散文段落,减少 token 消耗。
- 同一信息只在一处维护,避免多处重复导致不一致。