awesome-coding-skills-cn AGENTS.md

把本文件放进项目根目录即可让 Codex / Cursor / Gemini CLI 及其他 AI 编码工具遵守以下规则。

核心纪律

• 不造 API：只调用确认存在的库函数，不确定就查文档或源码，禁止凭记忆编造。
• 外科手术式改动：只改与当前任务直接相关的代码行，不顺手触碰格式、import 或无关逻辑。
• 拒绝过度工程：只实现当前需求的最小方案，不预留"将来可能用到"的抽象或扩展点（YAGNI）。
• 显式暴露假设：动手前列出关键假设，歧义处先问清楚，不闷头猜测。
• 改前先读：修改任何文件前先完整读一遍，理解命名规范和错误处理约定再动手。

系统化调试

• 先复现：动代码前先写下稳定复现步骤和"期望行为 vs 实际行为"，无法复现就先补日志。
• 读真实报错：逐字读完整堆栈，从第一次抛出点开始定位，不跳过、不脑补。
• 二分缩小范围：用打印或注释二分法把问题缩到最小代码段，不靠直觉猜位置。
• 找根因不贴补丁：能用一句话解释"为什么会错"之后再改代码，禁止用空 try/except 吞异常掩盖症状。
• 改完验证：重跑最初的复现步骤确认修复，再跑全量测试套件确认无新的失败。

测试驱动

• 先写测试：在任何实现代码存在之前，先写表达期望行为的测试用例。
• 看它失败：写完测试立即运行，确认失败原因是"功能缺失"而非测试本身写错。
• 最小实现：只写刚好让当前测试通过的代码，克制"顺手加逻辑"的冲动。
• 全量验证：实现后运行完整测试套件，新测试绿且原有测试全部仍绿才算完成。
• 测行为不测实现：断言返回值和可观察状态，不 mock 或 spy 内部私有方法。

改老项目不崩

• 先摸地形：改动前用搜索找出所有调用点和依赖关系，影响面超出预期时先向用户确认。
• 跟随既有约定：完全模仿该仓库的命名风格、文件结构、错误处理方式，不引入个人偏好。
• 小步可回退：每次提交只做一件事，提交信息清楚说明改了什么和为什么改。
• 不动公共接口除非必要：改对外函数签名或 HTTP 端点前评估所有下游影响，优先保持向后兼容。
• 保留并复用既有工具：动手前先搜索仓库里有没有现成实现，不重复造轮子，不引入功能重复的新依赖。

前端最佳实践（React/Vue）

• 组件单一职责：一个组件只做一件事；超过 300 行必须拆分；展示组件不持有业务状态、不调接口。
• 状态就近放置：状态只提升到真正需要它的最近公共祖先，只有跨路由需要共享时才引入全局 store。
• 避免无谓重渲染：传给子组件的对象和函数必须保持稳定引用；React 用 useMemo/useCallback，Vue 用 computed。
• 副作用收口：请求和订阅必须放进受控 effect，用 AbortController 或 onUnmounted 正确清理，防止竞态和内存泄漏。
• 可访问性默认开：可点击元素用 <button>/<a>，图片加 alt，表单 input 关联 label，Tab 键可正常遍历所有控件。

中文 commit 规范

• 格式固定为 type(scope): 中文主题：type 只用七个英文关键字（feat/fix/docs/refactor/test/chore/perf），主题用中文祈使句，不超过 50 字，末尾不加句号。
• 主题写"做了什么"而非流水账：动词放句首，一眼能判断是否需要点进 commit 看细节。
• 正文只写"为什么"：解释动机与权衡，不逐行复述 diff；主题与正文之间空一行。
• 一次只提一件事：提交前扫描暂存区确认每处改动服务同一目的，混入的无关改动拆分到独立提交。
• scope 用真实模块名：对应项目中真实存在的目录或包名，不编造 misc/global 等占位词。

国内技术栈适配

• 小程序/uniapp 禁用 DOM/BOM API：window/document/localStorage 全部换成 wx.*/uni.* 对应接口；setData 合并调用并用 path 精确更新，禁止在循环里多次调用。
• uniapp 跨端必须用条件编译：平台差异逻辑用 #ifdef APP-PLUS/#ifdef MP-WEIXIN/#ifdef H5 包裹，不写死单端 API。
• 微信登录走官方流程：前端只传 code 给后端，后端用 code2session 换 openid；openid 和 session_key 不落前端存储。
• SpringBoot 分层清晰：Controller 只接参/返响应；业务逻辑全在 Service；参数校验注解统一在全局异常处理器处理，不在 Controller 里写业务或手写 if-else 校验。
• 国内镜像与合规：npm 用淘宝镜像，Maven 用阿里云镜像，前端资源走国内 CDN；上线前对照合规清单检查隐私政策与权限申请说明。