diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..efca3671a --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,37 @@ +# 项目编程规范 + +## 理解需求 + +- 实现前先阅读 Issue 及其示例。遵循指定的 API、数据模型和导出类型;先核实已安装依赖的实际接口,必要时升级依赖,不要擅自替换成无关 API。 +- 在整个仓库中搜索相关用法,并一致地落实适用改动。保留现有行为、功能和源码链接;删除空文件、未使用代码、调试输出,以及没有实际效果的配置改动。 + +## 数据与错误处理 + +- 将可复用的数据发现、排序和分页逻辑放入共享工具函数。保持工具通用,不要把特定内容目录或页面硬编码进去。 +- 构建时页面应使用框架提供的静态生成 API。缺少必需内容、生成路径无效及其他构建错误都应明确暴露;仅在应用可以恢复时捕获错误,避免静默回退或空的 `catch` 块。 +- 使用类型安全检查和可选链明确处理可选数据。只有在缺失数据属于预期情况时,才显示有意义的占位内容。 + +## React、TypeScript 与内容 + +- 使用依赖实际导出的类型和 API。为组件声明明确的属性类型,对象属性应使用解构;不要重复导出依赖本身的类型。 +- 保持组件职责清晰且可复用:将重复 UI 提取为符合领域职责的组件,由父组件决定布局;渲染 MobX 可观察状态的组件应使用 `@observer` 装饰器。 +- 列表项应使用稳定且唯一的业务标识作为 `key`;对于可能变化或重排的集合,不要使用数组索引。 +- 使用语义化且易访问的 HTML:集合使用列表,名称与对应值使用描述列表,日期使用带 `dateTime` 属性的 `