docs: merge AGENTS.md.new constraints and update tech stack
- Merge general engineering constraints from AGENTS.md.new (constitution, communication, reply style, multi-option decisions, sub-agent usage, UI design) - Update frontend stack: react-admin + MUI -> Refine + shadcn/ui + Tailwind CSS - Standardize icon library as RemixIcon - Remove UI replacement boundary section
This commit is contained in:
@@ -1,5 +1,56 @@
|
||||
# 仓库规范
|
||||
|
||||
## 宪法(通用工程约束)
|
||||
|
||||
- 任何涉及文件的调研或修改,如果当前是 git 仓库,需要先同步远程提交到本地,避免调研过时问题。
|
||||
- 基于 TDD 进行功能的开发与业务变更,单元测试覆盖率要保证 65% 以上。
|
||||
- 任何时候我提出任何需求均需要理解并**结构化复述后与我进行确认,避免理解偏差**。
|
||||
- 不要在代码里藏兜底逻辑来吞掉错误、隐藏问题。出了问题就应该让它爆出来,否则你永远找不到真实问题。
|
||||
- 当一个问题出现时,不要用各种 small fix、针对性补丁来掩盖它。**必须定位真实根因,彻底修复**。在 bug 上糊纸只会让系统积累你不知道的危险暗病。
|
||||
- 即使问题很难定位,也**绝不要偷懒做表面修复**。应该给项目增加充分的日志和可观测性,保证下次问题再现时你有足够信息去定位。问题无法修复时,只需要诚实告诉我信息不足、需新增日志,不要假装修好了。
|
||||
- 始终注意在关键路径上给自己留足排查日志,确保每一个**关键节点都是可追溯**的。
|
||||
- 当项目关键技术栈或产品方向发生变更时,同步更新 agents.md。文档必须随代码一起演进,不能让它变成过时的谎言。
|
||||
- 大规模重构或实验性改动前,必须先切新分支。
|
||||
- 不以维护向后兼容性为目标。**对于已经废弃的代码路径,应直接移除**,不再通过兼容层、回退机制或迁移方案予以保留。(注:开发阶段数据兼容豁免见下,本条针对代码路径。)
|
||||
- 在充分满足当前需求的前提下,采用**尽可能简单的实现方案**。避免引入缺乏实际需求依据的抽象、配置项和间接层。
|
||||
- **采用渐进式、分层的方式构建系统**。首先完成能够端到端运行的最小版本,再基于稳定可用的产品逐步增加功能。不要以尚未成熟的复杂性取代已经可用的产品。
|
||||
- **保持组件的模块化**,并明确划分不同职责与关注点。
|
||||
- 当成熟且维护良好的库能够降低整体复杂度或提高可靠性时,应优先采用。除非有明确理由,不要重复实现通用功能。
|
||||
- 在自行实现功能或新增依赖之前,应优先评估项目现有依赖的能力。应先查阅相关文档与类型定义,不应未经确认就认定某个库不具备所需能力。
|
||||
- 架构决策**应着眼于长期演进**。不要采用仅能解决当前问题、且预期需要在后续替换的权宜方案。
|
||||
- 在设计解决方案之前,**先研究成熟产品如何解决同类问题**。优先采用经过验证的模式和约定,避免从零开始另行设计一套方案。
|
||||
|
||||
## 沟通方式
|
||||
|
||||
- 向使用者回报时,使用清楚直白的语言说明做了什么、结果如何。最终回复禁用术语、技术实现细节与工程腔。写法是:对一个聪明但没在看代码的人解释。
|
||||
- 实际执行过程(思考、规划、写程序、除错、解决问题)保持完整的技术严谨度,这条规范只适用于对使用者的沟通方式。
|
||||
|
||||
## 回复风格
|
||||
|
||||
- 只写结论、实际改动、原因、验证结果
|
||||
- 不描述推进动作,禁用「我先……再……」等叙述句式
|
||||
- 不使用工程汇报腔(「落地」「落到」「推进」等类似用语)
|
||||
- 直接、专业、去表演化
|
||||
- 回复文字永远使用与对方相同的语系,专有名词维持英文
|
||||
- 不使用口语化表达,说重点,简单明了
|
||||
- 需要时搭配条列式与表格加强输出可读性
|
||||
|
||||
## 多选项决策
|
||||
|
||||
- 当方案有多个选项时,列出每个选项的优缺点,并明确指出推荐选项与原因。
|
||||
|
||||
## Sub-Agent 使用时机
|
||||
|
||||
当任务符合以下任一条件时,直接 spawn sub-agent 分工执行,无需询问使用者:
|
||||
|
||||
- 任务可拆分为多个**平行且无依赖**的子任务
|
||||
- 各子任务职责明确分离,合并执行会造成 context 混杂
|
||||
- 大量结构相同的重复性任务(可用 `spawn_agents_on_csv` batch 执行)
|
||||
- 各子任务需要不同的 model 配置或 sandbox 权限,例如:
|
||||
- 探索型任务使用轻量 model + `read-only` sandbox
|
||||
- 审查型任务使用高推理 model + `read-only` sandbox
|
||||
- 修改型任务使用执行导向 model + `workspace-write` sandbox
|
||||
|
||||
## 开发阶段原则
|
||||
|
||||
- 开发阶段仅关注业务功能:不实现访问限制、认证、网络隔离等安全策略,安全由用户自行把控。
|
||||
@@ -23,21 +74,19 @@
|
||||
|
||||
### React 前端
|
||||
|
||||
- 使用 React 19、Vite 8、`react-admin` 5.15.x 和 MUI 9。在 `web/package-lock.json` 中锁定精确的已安装版本。
|
||||
- 初始实现只使用开源版 react-admin 和 MUI 包。Enterprise Edition 与 MUI X Pro/Premium 需单独的产品与许可证评审。
|
||||
- 视觉体系由 CreatorHub 自有掌控:品牌 token 保留在项目主题中,导航/外壳保留在项目自有的 Layout、AppBar 和 Menu 组件中。Mantis Free 可作为 MIT 许可的视觉参考,但不得导入或 fork 整个模板。
|
||||
- 不将 Ant Design、Arco 或其他组件体系混入 react-admin/MUI 应用。
|
||||
- 将启动、停止、回收等领域动作保留为显式动作;不得为迎合 react-admin 惯例而伪装成通用 CRUD 更新。
|
||||
- 使用 React 19、Vite 8、Refine 与 shadcn/ui、Tailwind CSS。在 `web/package-lock.json` 中锁定精确的已安装版本。
|
||||
- 视觉体系由 CreatorHub 自有掌控:品牌 token 保留在项目主题与 Tailwind 配置中,导航/外壳保留在项目自有的 Layout 组件中。shadcn/ui 组件按需生成并纳入仓库自有代码,不引入 Ant Design、Arco、MUI 等其他组件体系。
|
||||
- 图标统一使用 RemixIcon,不为差异化自创奇怪图标。
|
||||
- 将启动、停止、回收等领域动作保留为显式动作;不得为迎合 Refine 惯例而伪装成通用 CRUD 更新。
|
||||
|
||||
## UI 替换边界
|
||||
## UI 设计
|
||||
|
||||
- 未来 UI 切换仅限于项目自有的 MUI 主题、Layout/AppBar/Menu,以及 react-admin `dataProvider` 边界。API 调用与响应映射放在 data provider 中,不放展示组件里。
|
||||
- 现阶段不构建并行设计系统、框架中立的组件层或投机性的适配器层级。仅当具体替换方案无法被现有三处缝隙(seam)容纳时,才引入新边界。
|
||||
- 从 MUI 或 react-admin 切换出去前必须经用户评审。替换现有 UI 栈,而非两套组件体系并行运行。
|
||||
默认收敛、克制、常规;尺寸与间距根据界面类型、信息密度、平台习惯、使用频率和视觉层级判断,不写死统一规格,也不主动放大。辅助入口、设置、开关、工具按钮不应抢视觉中心。常见功能必须使用大众通用、用户一眼可识别的图标隐喻,优先成熟图标库、系统图标或行业通用符号,不为差异化自创奇怪图标;自定义图标也必须保持常见轮廓、比例和语义。除非明确要求强调,否则优先用位置、分组、轻微颜色、hover、tooltip、分隔线和状态反馈表达层级,避免夸张尺寸、重色块、大圆角、厚边框、强阴影、装饰性渐变和营销页式布局。实现后必须与同屏元素对比检查,若显得突兀、过大、过重或破坏信息密度,应主动收敛。
|
||||
|
||||
## 验证与交付
|
||||
|
||||
- 每个非平凡行为变更附带最小的回归测试,且该测试在无此变更时会失败。在信任与集成边界覆盖成功、校验、失败和兼容路径。
|
||||
- 开始任务前先定义完成标准。交付前依此验证,发现问题就修好再测,不把未完成的工作交回给使用者。只有确认完成,或遇到真正需要使用者介入的障碍时,才回报。
|
||||
- 每个非平凡行为变更附带最小的回归测试,且该测试在无此变更时会失败。在信任与集成边界覆盖成功、校验、失败和兼容路径;单元测试覆盖率保证 65% 以上。
|
||||
- 后端变更必须通过 `go test ./...`、`go vet ./...`,并完成 `./cmd/control-plane` 和 `./cmd/docker-gateway` 双端构建;涉及并发、生命周期或共享状态的变更须运行 `go test -race ./...`。Docker 或 Compose 变更还须通过 `docker compose config --quiet`。
|
||||
- 前端变更必须从 lockfile 安装、通过仓库的非交互式测试命令,并通过 `npm --prefix web run build`。主题、Layout、导航、资源动作或 data provider 的变更需要聚焦的交互覆盖,包括适用的错误与禁用状态。
|
||||
- 除非 issue 明确批准契约变更,保持既有 API 与 Docker 生命周期行为不变。在 PR 中文档化任何状态码、载荷、配置、迁移、安全或重试方面的影响。
|
||||
|
||||
Reference in New Issue
Block a user