93 lines
6.9 KiB
Markdown
93 lines
6.9 KiB
Markdown
## 宪法
|
||
|
||
- 任何涉及文件的调研或修改，如果当前是 git 仓库，需要先同步远程提交到本地，避免调研过时问题。
|
||
- 基于 TDD 进行功能的开发与业务变更，单元测试覆盖率要保证 65% 以上
|
||
- 任何时候我提出任何需求均需要理解并**结构化复述后与我进行确认，避免理解偏差**。
|
||
- 不要在代码里藏兜底逻辑来吞掉错误、隐藏问题。出了问题就应该让它爆出来，否则你永远找不到真实问题。
|
||
- 当一个问题出现时，不要用各种 small fix、针对性补丁来掩盖它。**必须定位真实根因，彻底修复**。在 bug 上糊纸只会让系统积累你不知道的危险暗病。
|
||
- 即使问题很难定位，也**绝不要偷懒做表面修复**。应该给项目增加充分的日志和可观测性，保证下次问题再现时你有足够信息去定位。问题无法修复时，只需要诚实告诉我信息不足、需新增日志，不要假装修好了。
|
||
- 始终注意在关键路径上给自己留足排查日志，确保每一个**关键节点都是可追溯**的。
|
||
- 当项目关键技术栈或产品方向发生变更时，同步更新 agents.md。文档必须随代码一起演进，不能让它变成过时的谎言。
|
||
- 大规模重构或实验性改动前，必须先切新分支。
|
||
|
||
- 不以维护向后兼容性为目标。**对于已经废弃的代码路径，应直接移除**，不再通过兼容层、回退机制或迁移方案予以保留。
|
||
- 在充分满足当前需求的前提下，采用**尽可能简单的实现方案**。避免引入缺乏实际需求依据的抽象、配置项和间接层。
|
||
- **采用渐进式、分层的方式构建系统**。首先完成能够端到端运行的最小版本，再基于稳定可用的产品逐步增加功能。不要以尚未成熟的复杂性取代已经可用的产品。
|
||
- **保持组件的模块化**，并明确划分不同职责与关注点。
|
||
- 当成熟且维护良好的库能够降低整体复杂度或提高可靠性时，应优先采用。除非有明确理由，不要重复实现通用功能。
|
||
- 在自行实现功能或新增依赖之前，应优先评估项目现有依赖的能力。应先查阅相关文档和类型定义，不应未经确认就认定某个库不具备所需能力。
|
||
- 架构决策**应着眼于长期演进**。不要采用仅能解决当前问题、且预期需要在后续替换的权宜方案。
|
||
- 在设计解决方案之前，**先研究成熟产品如何解决同类问题**。优先采用经过验证的模式和约定，避免从零开始另行设计一套方案。
|
||
|
||
## 禁止清单（不主动考虑、不主动提议、不实现，遇到只记入 TODO 技术债列表）
|
||
|
||
1. 法律合规：商业库授权、开源协议合规、GDPR/个保、隐私政策（法务负责）。
|
||
2. 依赖安全：NPM 及第三方包漏洞、安全补丁、依赖升级策略。
|
||
3. 访问安全：服务只需支持局域网访问（host 绑定 0.0.0.0 即可），不考虑公网暴露、HTTPS、认证/权限体系（登录、RBAC）、限流、防爬、数据加密、审计日志。
|
||
|
||
## 红线清单（快速阶段也不能省，现在便宜、以后极贵）
|
||
|
||
1. 数据模型/表结构：认真设计，建表慎重——改表成本远高于写代码。
|
||
2. 目录结构与模块边界：保持简单清晰，不堆一坨代码。
|
||
3. 基础错误日志：出错时至少能看到发生了什么。
|
||
4. Git：小步提交，保持历史清晰。
|
||
5. 基础输入校验：仅防止程序崩溃，不做安全加固。
|
||
6. 环境差异配置（端口、地址等）与代码分离（.env 或配置项）。
|
||
|
||
## 技术栈
|
||
|
||
前端框架：Umi Max 4.7 + React 19；
|
||
|
||
组件库：antd 6.6.5 + @ant-design/pro-components 3.x（beta 线）+ @ant-design/icons；仅使用 antd/pro 默认组件原样实现，禁止自定义封装与样式魔改；组件不满足业务时改交互逻辑适配组件；
|
||
|
||
后台管理：create-umi 脚手架（ant-design-pro 同构），约定式路由；
|
||
|
||
图标 @ant-design/icons；
|
||
|
||
后端 Go 库 fiber/v3; logus; viper; cobra；samber/lo; samber/mo
|
||
|
||
用户交互需要使用 skill:impeccable 优化交互操作
|
||
|
||
## 沟通方式
|
||
|
||
- 向使用者回报时，使用清楚直白的语言说明做了什么、结果如何。最终回复禁用术语、技术实现细节与工程腔。写法是：对一个聪明但没在看代码的人解释。
|
||
|
||
- 实际执行过程（思考、规划、写程序、除错、解决问题）保持完整的技术严谨度，这条规范只适用于对使用者的沟通方式。
|
||
|
||
## 回复风格
|
||
|
||
- 只写结论、实际改动、原因、验证结果
|
||
- 不描述推进动作，禁用「我先……再……」等叙述句式
|
||
- 不使用工程汇报腔（「落地」「落到」「推进」等类似用语）
|
||
- 直接、专业、去表演化
|
||
- 回复文字永远使用与对方相同的语系，专有名词维持英文
|
||
- 不使用口语化表达，说重点，简单明了
|
||
- 需要时搭配条列式与表格加强输出可读性
|
||
|
||
## 决策规则
|
||
|
||
- 当方案有多个选项时，列出每个选项的优缺点，并明确指出推荐选项与原因，先问我。
|
||
- 有多种实现方式时，选最简单能跑通的。
|
||
- 遇到"禁止清单"中的问题：不展开、不实现，追加到 TODO 技术债列表即可。
|
||
|
||
## 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
|
||
|
||
## 验证标准
|
||
|
||
开始任务前先定义完成标准。交付前依此验证，发现问题就修好再测，不把未完成的工作交回给使用者。只有确认完成，或遇到真正需要使用者介入的障碍时，才回报。
|
||
|
||
## UI 设计
|
||
|
||
默认收敛、克制、常规；尺寸与间距根据界面类型、信息密度、平台习惯、使用频率和视觉层级判断，不写死统一规格，也不主动放大。辅助入口、设置、开关、工具按钮不应抢视觉中心。常见功能必须使用大众通用、用户一眼可识别的图标隐喻，优先成熟图标库、系统图标或行业通用符号，不为差异化自创奇怪图标；自定义图标也必须保持常见轮廓、比例和语义。除非明确要求强调，否则优先用位置、分组、轻微颜色、hover、tooltip、分隔线和状态反馈表达层级，避免夸张尺寸、重色块、大圆角、厚边框、强阴影、装饰性渐变和营销页式布局。实现后必须与同屏元素对比检查，若显得突兀、过大、过重或破坏信息密度，应主动收敛。
|