# Copilot Agent Rules - Base 以下为始终生效的核心规则。各项目可通过 `AGENTS.private.md` 添加项目特定规则。具体操作流程（PR 创建、部署、Figma 还原、TDD 等）已封装为 Skill，通过 `/skill名` 调用。 ## 🚨 元规则 本文件中的每一条规则都是强制规则。所有带 ⚠️ 标记的规则不可因「上下文压缩」「对话太长」等任何原因遗漏或跳过。 ## ⚠️ 规则修改入口 - **新增、修改、删除规则，必须改 `AGENTS.base.md`（源文件），禁止直接改 `CLAUDE.md` 或 `AGENTS.md`**。改完后必须执行 `node merge.js sync` 重新生成输出文件。 - ⚠️ **新增行为/指令时，先判断该放规则还是 Skill**： - **规则（Rule）**：始终生效的约束，如代码风格、命名规范、行为要求、注释规范。写入 `AGENTS.base.md`。 - **Skill**：多步骤操作流程，需按需调用，如部署、发 PR、Figma 还原、TDD 流程。新建 `skills/技能名/SKILL.md`。 - **判断标准**：「这件事每次写代码都要遵守吗？」→ 是 = 规则，否（只有特定场景才触发）= Skill。 ## 语言与内容 - 始终使用中文回答，代码注释使用中文。 - 页面 UI 内容（按钮、字段名、提示等）全部英文；如需中文在 `AGENTS.private.md` 中声明。 - ⚠️ **解释代码或技术概念时，必须通俗易懂，优先用生活中的真实例子类比，禁止纯学术式讲解。** 例：解释缓存命中——「就像冰箱里已经放好了可乐，想喝直接拿，不用每次都跑楼下超市；冰箱里没有才需要跑一趟（缓存未命中，回源数据库）。」目标是让不熟悉该领域的人也能听懂，不要只堆术语、贴定义。 ## 需求实现原则 - ⚠️ 严格按用户原话实现需求，禁止擅自添加用户未要求的限制、规则或约束。 - ⚠️ 不确定某个限制是否必要时，必须先询问用户，禁止直接添加。 ## ⚠️ 环境配置禁止推断 - ⚠️ **写代码或注释涉及环境相关的值（域名、地址、端口、密钥、外部服务 URL 等）时，禁止根据已知值类推未知值**（例如「测试是 api-test.xxx，那生产应该就是 api.xxx」）。必须从以下来源至少一处交叉确认： 1. 项目内的部署脚本、Dockerfile、CI 配置 2. 实际 DNS 解析（`dig`/`nslookup`） 3. 云平台控制台（Cloud Run 域名映射、GCLB、Ingress 等） - ⚠️ **上述来源都找不到的，就写「待确认」或留空，禁止自行补全。** 错误的推断值比留空危害更大——留空会在运行时报错、立刻暴露；错误的推断值可能静默运行数月后才被发现（如请求打到了错误的环境），排查成本极高。 - ⚠️ **代码中使用环境变量占位符（如 `process.env.XXX`）时，必须同时确认测试/生产部署脚本（或配置中心）已提供该变量的具体值。** 禁止只写占位符不落地——代码能编译不代表部署后取值非空。具体值的存放规则：敏感值（密钥、Token 等）必须配到 Nacos 配置中心，禁止写进部署脚本；非敏感值（域名、地址、端口、外部服务 URL 等）写入测试/生产各自的部署脚本。部署脚本中找不到的值仍按本规则写「待确认」或留空，禁止自行补全。 ## ⚠️ 可部署性自包含铁律（写代码之前考虑） - ⚠️ **写任何逻辑、用任何环境变量/配置值之前，必须先把"这个改动上线后部署怎么办"想清楚**：能直接写死的就写死，该放部署脚本的就放部署脚本，该配配置中心的就配配置中心。所有环境准备（建表、迁移、字段变更、初始化/导入数据、配置下发）一律内嵌到部署脚本自动完成。**达成的效果：上线时只需执行部署脚本，数据库迁移、人工改配置等一切操作全部免掉，上线后零操心。** - ⚠️ **触发时机是写代码之前，不是部署的时候。** 禁止先写代码、等要部署了再补部署脚本。每写一个涉及环境准备的改动，部署逻辑必须随之一起落地，不允许"代码完成、部署待办"的中间态。 - ⚠️ **写完涉及环境准备的改动，必须当场自查三问**（参考 DELETE 铁律格式；任一答案为「是」而部署脚本无对应逻辑 → **该改动不算完成**）： 1. **改数据库了吗？** 新增/修改表、字段或数据 → 部署脚本必须有幂等 schema 确保逻辑（如 `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`、`ensure_xxx()` 前置函数），加列/建表失败即停止部署。 2. **改配置了吗？** 新增/修改环境变量、Nacos 配置、部署脚本值 → 具体值必须已落地部署脚本或配置中心，禁止只写占位符或"待确认"。 3. **要初始化/搬运数据吗？** 需要初始化、导入、转换数据 → 必须脚本化进部署流程自动完成。 - ⚠️ **发现「部署后还需要手动补步骤」= 部署流程有缺口**：一旦某次部署发现还要人工执行迁移、导数据、改配置等步骤功能才能用，必须当场把该步骤自动化进部署脚本，禁止继续靠记性每次手动补。**人为手动步骤是上线遗漏的根源**（测试环境做了、生产环境容易忘）。 - ⚠️ **部署完成的定义 = 脚本执行完 → 功能直接可用 → 期间零人工补操作。** 未满足「零人工补操作」的部署不算完成，禁止在还需手动补步骤时宣称部署完成。 - ⚠️ **「部署可用」≠「功能已验证」**：部署自动化到位只保证环境就绪、功能直接可操作；功能是否正确，仍需按既有验证铁律用真实数据验证，两者不冲突。 ## ⚠️ 测试环境功能验证前置铁律（防止缺表报错误判为代码问题） - ⚠️ **在测试环境验证任何涉及新增表/新增字段的功能（如充值、退款、发票，不限于这些）之前，必须先确认数据库表结构已就绪。** 测试环境 AutoMigrate 默认关闭（见「Go 规则」），新表/新字段不会随代码自动创建。跳过这一步直接验证，报出的缺表/缺字段错误是环境问题，不是代码问题，极易误判。 - ⚠️ **验证前必须显式执行以下任一前置动作，禁止跳过：** 1. **临时打开 AutoMigrate 开关**，启动/重启服务完成建表后，恢复默认关闭； 2. **手动执行幂等建表/加字段 SQL**（`CREATE TABLE IF NOT EXISTS` / `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`），并确认目标表/字段已存在。 - ⚠️ **遇到缺表/缺字段类报错时，第一优先级检查表结构是否就绪，禁止直接定性为代码 bug。** 特征报错：`relation "..." does not exist`、`table ... does not exist`、`column ... does not exist`、`Unknown column`、`Unrecognized name` 等。先查表（`\d 表名` / `DESCRIBE` / `information_schema`）确认就绪后再排查代码。 ## ⚠️ 排查与协作铁律 - ⚠️ **排查「以前能用、现在不行」类问题时禁止用绕过手段掩盖问题**（改配置屏蔽报错、写同步脚本搬数据、临时禁用校验等），必须先定位根因再修复。 - ⚠️ **给出多个方案（A/B/C）供选择时，必须等用户明确选定后再执行**，禁止默认执行「推荐方案」。 - ⚠️ **用户提出模糊的调整要求**（如「再加点间距」「跟上面保持一致」「差不多就行」）时，必须先确认具体参照物和数值，禁止凭感觉直接改。 - ⚠️ **同一个问题被用户连续纠正两次后，第三次必须停下来问清楚根本原因**，禁止继续「改了又错、错了再改」的循环尝试。 - ⚠️ **修改多处复用的公共部分**（组件、配置、脚本、样式）后，必须找出所有引用/调用位置逐一验证，禁止只验证当前改动的那一处。 - ⚠️ **「数值/坐标/结构对齐」类验收，除了程序化校验外，必须额外做一次实际效果验证**（截图、真实访问、人工看一眼），不能只信数值对得上就算完成。 - ⚠️ **验证功能是否修复时，要用真实存在的数据/路径去测试**，避免用虚构的测试数据得出「失败」的假结论。 - ⚠️ **定位并修复根因后，必须清理诊断过程中留下的临时改动**（调试代码、临时开关、测试脚本），不要把绕过方案的残留物留在代码里。 - **某个工具/脚本报错时，先检查是否有残留的锁文件、临时文件、缓存导致的问题**，清理后重试；仍失败再切换备用方案，不要一遇报错就直接换路子。 - **长任务或涉及截图等大内容的操作，注意控制单次传入的数据量**（压缩、降低分辨率等），避免不必要地占满上下文。 - ⚠️ **用户反馈"看起来没生效/没写入"时，先用权威数据源核实**（直连数据库/调对应 API 查，而不是只信一次前端页面截图），前端页面可能存在多个同名视图、未展开的关联表、缓存等歧义，容易把"看错了地方"误判成"修复失败"，也可能反过来把真的失败误判成"看错了"——两种方向都要用权威数据源排除，不能靠肉眼猜。 - ⚠️ **停用/归档任何仍可能被其他配置引用的共享资源（数据库、开关、服务实例、旧接口等）前，必须先确认所有引用方已经完成切换**，禁止先下线资源、后补救引用；正确顺序是「新资源就位 → 所有引用方切到新资源并验证 → 确认无引用后才下线旧资源」。 - ⚠️ **对「只增不改」的追加型数据表（日志表、流水表）做分批消费时，禁止用「每次从头查 + LIMIT 截断 + 幂等去重」的无状态写法**。无断点的全量查询每次都会返回最早的一批行（早已消费、被幂等跳过、不产生任何效果），而新行永远排在 LIMIT 之外——扣款/同步在数据量超过单批上限后静默停滞，不报错、不崩溃，余额/进度「悄悄不涨不降」，是最阴险的静默 bug（offset-pagination 饥荒）。正确写法是带「进度断点」的增量查询：**按业务排序键（如时间+ID）记录上次消费位置（游标），下轮用 `WHERE 排序键 > 断点` 的严格排他下界续拉，消费成功后游标单调推进到批次末尾**，保证不重也不漏。判断标准：只要处理逻辑会「跳过已处理的记录」且「数据量可能超过单批上限」，就必须用游标/断点，而非从头扫。 ## ⚠️ 修复验证铁律 - ⚠️ **验证方法必须"可确定性复现"，优先选最直白的路径。** 不要依赖真实流量、后台任务或时序巧合去凑出被验证的状态（反直觉、难复现、别人无法照做）。判断顺序：先问「本次修复的唯一改动是什么」，把它精确映射成一个可手动触发的原子操作，再做 A/B 对照。例：验证"余额变更后网关缓存立即失效"，不要靠真实计费请求养缓存，而是直接 `SET` 种一个已知值 → `GET`（有值 = 修复前）→ `DEL`（= 失效动作）→ `GET`（nil = 修复后）。 - ⚠️ **报告开头必带一张「为什么这样验证成立」的原理说明卡。** 先讲清楚 bug 前后差异的本质是哪一个动作，再论证"手动模拟该动作 = 真实场景"，让不了解背景的人也能信服。配一张修复前 vs 修复后的 A/B 对照表（代码行为 / 等价操作 / 观测结果三列并排）。 - ⚠️ **每个验证步骤必须三要素齐全**：① 怎么做的（可复制粘贴的完整命令）② 结果（含可复查标识：执行 ID、时间戳、返回码）③ 这一步证明了什么（一句话点明证据含义，如"DEL 返回 1 = 删除前 key 确实存在"）。 - ⚠️ **采用「主验证 + 真实链路佐证」双证据结构。** 主验证用最简单直观的方式（如直接看值）确保人人能复现；再补一条端到端真实链路证据（如真实日志、双侧时间戳对齐），把"手动演示"和"真实业务动作"接上，二者相互印证。 - ⚠️ **截图是可视化证据，图注必须写清「这张图证明了什么」**，并标注关键行/关键数据（红框、箭头放在空白区，不遮挡原内容）。 - ⚠️ **结论用「证据并列」呈现**：逐条列出每类证据的关键数值和可复查标识（执行 ID / 时间戳），最后一句量化修复效果（如"陈旧窗口从约 30 分钟压缩到 ≈0"）。 ## ⚠️ 验证结论溯源铁律 - ⚠️ **验证结论必须基于运行时真实数据，禁止用「配置里写了这个字段」代替实际调用结果作为验证依据。** 配置字段存在 ≠ 运行时该字段有值——中间任何一层（序列化、转发、反序列化）丢弃了它，下游就是空的。正确做法：调一次真实接口 → 看返回体/日志里的实际值 → 确认数据通路完整。 - ⚠️ **数据对不上时，去代码里溯源计算逻辑，禁止凭感觉猜。** 例：Gateway 返回的某个字段值不对 → `grep` 找到该字段的赋值/计算位置 → 逐层追溯到数据源头，找到具体在哪一步被改坏或丢弃。不要跳过中间层直接猜「可能是 A 模块的问题」。 - ⚠️ **能用浏览器查看的后台页面（Log 详情、Admin 面板、监控大盘、API 文档页等），必须截图验证**，禁止只靠终端 curl 输出下结论。浏览器能看到完整的渲染结果、关联数据展开、错误详情折叠等，curl 只能看到原始文本——信息密度差一个数量级。 ## ⚠️ 页面功能验证铁律（真实数据 + 真实交互） - ⚠️ **编写 HTML 页面或前端功能后，必须用测试环境的真实数据验证，禁止用虚构/mock 数据自测。** 虚构数据只能验证「代码不报错」，无法验证「功能在真实场景下正常工作」——真实数据会暴露边界情况（空值、超长文本、特殊字符、异常关联关系等），虚构数据碰不到这些。测试环境有真实数据时优先用测试环境；测试环境数据不足时，从生产环境脱敏导出。 - ⚠️ **页面功能验证必须通过实际的页面交互操作来完成**（打开浏览器、点击按钮、填写表单、观察渲染结果），模拟真实用户操作路径。禁止只靠代码审查、单元测试断言或静态分析代替实际页面操作验证——用户最终是通过页面交互使用功能的，不是通过测试断言。能用浏览器手动操作的，就用浏览器手动操作一遍。 ## ⚠️ 可视化验证铁律（默认不写测试用例，用证据说话） - ⚠️ **AI 默认禁止主动写「测试用例」**（单元测试、Playwright E2E、API 冒烟脚本等）。写不写测试、写哪些，完全由用户显式提出（如「加测试」「写测试用例」「补一条回归用例」）才执行。AI 不得在未获明确指令时自行创建测试用例、主动建议补测试、或把「测试先行 / TDD」当作默认开发姿势。 - ⚠️ **功能验证的第一交付物是可视化证据报告，而不是测试断言。** AI 每做一个功能/修复，必须用「真实数据 + 真实交互 + 可视化证据」证明给用户看（遵循「⚠️ 修复验证铁律」「⚠️ 截图规范」）： 1. **页面/界面改动** → 打开真实页面，用真实数据走真实交互，全页截图 + 箭头标注关键改动区域； 2. **涉及 Redis**（缓存、计数器、限流、Session 等）→ 直接查看 Redis 运行时的 key/value（用 Redis for VS Code 插件页截图），A/B 对比改动前后的值； 3. **涉及数据库** → 直接查看数据库运行时数据（用 SQLTools 插件截图），A/B 对比改动前后的值。 优先让用户配合一起截图（用户是真人验证关卡：截图里的数据必须是真实的，AI 不得用 mock/虚构数据凑证据）。生成的验证报告是给用户看的，用户能一眼判断功能对不对，禁止把「AI 自己写、AI 自己看」的测试断言当作交付完成。 - ⚠️ **只有以下两类情况才允许写测试用例（有明确触发路径，非默认行为）**： 1. **时序/并发/缓存失效类逻辑**：问题出在「某个时刻的状态」，截图截不出来（如并发竞态、延迟失效），必须写测试来证明行为正确； 2. **回归事故补种**：出现「改 A 把 B 改坏」的回归事故后，当场为出问题的点补一条回归测试，防止同类问题再次悄悄发生。 - ⚠️ **禁止写测试 ≠ 允许带着基本错误交付。** AI 改完代码至少必须跑通编译 / 类型检查 / 最小冒烟，能自行发现并修复语法、类型、启动崩溃这类基本错误后再交付验证。连基本错误都发现不了就交付，比不写测试更糟。 - ⚠️ **判断标准：这个功能用户能不能在页面上操作？** - 能 → 必须用真实页面交互验证，能模拟用户手动测试就手动，并截图留证； - 不能（纯后端接口、定时任务、无页面入口的链路）→ 用运行时真实返回验证（curl/日志/查库/查 Redis），并把结果渲染成可视化证据（暗色终端风格的请求/响应对比 HTML 截图，或 Redis/SQLTools 插件截图）。 - ⚠️ **验证结论必须基于运行时真实数据，禁止用 mock/虚构数据自测。** 真实数据会暴露边界情况（空值、超长文本、特殊字符、异常关联关系等），虚构数据碰不到这些。测试环境有真实数据时优先用测试环境；测试环境数据不足时，从生产环境脱敏导出。 ## Git 规范 - 分支用 Git Flow（`feature/`、`bugfix/`、`hotfix/`、`refactor/`、`chore/`、`docs/`、`test/`），英文小写中划线分隔。 - ⚠️ **一般情况下，主分支（`main`）不允许直接提交代码**：日常改动必须先直接拉取远程主分支 → 创建功能分支 → 提交 → 推送 → PR 合并回主分支，禁止直接 commit/push 到 main（发版除外：`./release.sh` 会在 main 上生成「发布 vX.Y.Z」提交）。 - ⚠️ **从主分支拉/建功能分支之前，必须先直接拉取远程主分支（`git pull origin main`）**，确保基于最新的远程主分支拉分支，禁止基于过期的本地主分支创建分支。 - ⚠️ **可评审 PR 的合并目标永远是仓库默认分支（如 `main`/`master`），不是 `test`**。`test` 分支只用于部署测试环境，只能通过 `/deploy-test` skill 直接 `merge` 更新（见「部署规则」），不发 PR、不走 code review；`test` 分支同样禁止直接提交代码。commit 必须中文，禁止 `git push --force`。 - ⚠️ **已推送到远程的提交需要撤销时，必须用 `git revert`，禁止用 `git push --force` 覆盖远程历史。** `git revert` 会创建一条新的撤销提交，保留完整的操作记录，不影响其他协作者的本地分支；`git push --force` 会破坏远程历史，导致其他人的本地分支与远程脱节，极易引发合并冲突或丢失他人提交。 - ⚠️ **提交并推送代码后，若发现与主分支存在冲突，必须主动解决**，不能推送完就算完事、把冲突留给别人处理。 ## ⚠️ PR 冲突修复统一用临时 worktree - ⚠️ **修复 PR 与主分支的冲突时，一律使用临时 git worktree，禁止直接在当前工作副本上切换分支（`git checkout`）解题。** 原因：A-/B-/C-/M- 多副本仓库中，同一个克隆往往同时被其他开发任务占用；直接切分支会破坏别人正在进行的代码、或把自己卡在非主分支上。 - ⚠️ **标准操作流程**： 1. 在仓库根目录执行 `git worktree add ../-fix --detach`（或 `-b` 新建一个与 PR 分支同名的分支），临时分离出来用独立目录操作，当前工作副本状态完全不动。 2. 在 worktree 目录里 `git merge origin/main`（或 `git rebase origin/main`）→ 解决冲突文件 → 本地测试通过。 3. `git push` 推送回 PR 分支（须确认 push 目标为 origin 的对应 PR 分支，禁止 `--force`）。 4. 操作完成后用 `git worktree remove ../-fix` 清理临时 worktree，再回到原副本继续。 - ⚠️ **worktree 与主副本共享同一套本地 `.git`**，但工作目录、索引、当前分支状态完全独立，不会干扰正在 main 或其他分支上改动代码的协作者。 - ⚠️ **worktree 目录默认在仓库根目录同级（`../`）**，避免被误当成子文件夹进 git；进入前先确认该路径不存在同名文件夹。 ## PR 核心要求 - ⚠️ PR Title / Description / Test Plan 全部中文。 - ⚠️ **PR 必须附效果截图作为可视化证据，且逐条满足以下硬性要求（缺一不可，禁止跳过）**： - **全页图**：用浏览器真实视口（`window.innerWidth` 即截图宽度，4K 屏自然宽 3840）`fullPage` 截完整页面，禁止只截视口一屏。⚠️ **禁止强制把视口硬拉成 3840 宽**——浏览器视口宽由屏幕实际分辨率决定，硬拉宽会让内容按比例缩小（看不清），且与截图像素发生缩放错位，是标注不准的根因之一。若要更高清晰度，用 `set viewport 2`（DPR 倍率）提高渲染精度（CSS 宽不变、像素更密），而不是拉宽 CSS 视口。 - **全面多角度**：一张全页图 + 每个关键改动区域的局部放大图，多个改动点要逐个覆盖，确保 reviewer 不看代码就能看全本次全部改动。 - **箭头标注（必须标注准）**：每张截图必须用醒目箭头 + 简短文字标签标注关键改动区域/验证点（修复前红框/红箭头、修复后绿框/绿箭头），标注放在不遮挡原内容的位置，禁止只贴裸图不标注。⚠️ **标注坐标必须来自浏览器 DOM 测量（`getBoundingClientRect()` + `scrollX/scrollY`）精确换算成截图像素，禁止肉眼看图估坐标**——全页拼接/缩放截图里 CSS 坐标 ≠ 截图像素，肉眼估位是标注不准的直接原因。标注统一走 `/screenshot-annotate` skill（坐标换算方法 + `annotate.js` 统一脚本）。 - **URL 可见**：截图中必须能看到当前页面 URL，确保证据可追溯。 - **前后对比**：必须同时展示修复前与修复后。 - ⚠️ **截图必须直接内嵌在 PR Description 中，让 reviewer 打开 PR 就能看到效果图（`![](CDN_URL)` 方式渲染为可见图片），禁止只在文字里描述"改动了什么"而不放图，也禁止把截图只作为文件附件/提交到分支目录而不在 PR 正文中引用。** 原因：reviewer 看 PR 的第一眼就是看描述，如果看不到图、只能读文字，完全无法直观感知改动效果；截图不内嵌 = 等于没附。 - ⚠️ **截图必须通过 PR Description 编辑区直接上传（拖拽/粘贴/文件选择按钮），禁止走评论区 `input[type=file]` 上传后再搬运 CDN URL。** 原因：PR Description 编辑区本身支持图片拖拽上传、自动转为 `![](CDN_URL)` 内嵌，一步到位；走评论区上传需要多一步「提交评论 → 复制 URL → 粘贴到 Description」，产生的临时图片评论会留在 PR 对话里干扰 reviewer 阅读，且多了一步手动搬运、容易出错。 - ⚠️ 创建 PR 使用 `/create-pr` skill（自动生成中文内容 + 效果截图 + CDN 上传）。 - ⚠️ **PR 创建即进入可评审状态**：直接创建正式 PR（非 Draft），创建完成、冲突检查与静态编译通过后即可直接交付 review，禁止先开 Draft PR、后续再手动标记 Ready for review。 - ⚠️ **创建 PR 后必须先过 CI 再进入后续流程**：创建完成后第一时间执行 `gh pr checks `（必要时轮询直到非 `pending`）。若有任一检查 `failure`，必须先定位并修复失败项、推送新提交并复查到全部 `success`，然后才能进入循环 review、测试验证、交付 review 等后续步骤，禁止带红 CI 继续往下走。 - ⚠️ **每次修改 PR 后（含创建 PR、push 新提交、响应 review 意见重新推送等所有改动 PR 的动作之后），都必须检查与主分支（默认分支）是否有冲突**：用 `gh pr view --json mergeable -q .mergeable` 检查（`MERGEABLE`=无冲突可合并，`CONFLICTING`=存在冲突，`UNKNOWN`=GitHub 尚未判定，稍后复查）。若存在冲突，必须先解决冲突再交付 review——`git merge origin/main`（或 `git rebase origin/main`）→ 解决冲突文件 → 测试通过 → 推送，确保 PR 处于可合并状态，禁止把带冲突的 PR 抛给 reviewer。主分支随时可能前进，一个创建时无冲突的 PR 可能在后续 push 后悄悄变冲突，因此每次改动 PR 后都必须重新检查，禁止只在创建时查一次就以为高枕无忧。 - ⚠️ **每次修改 PR 后，除冲突检查外还必须检查 GitHub 静态编译是否通过，通过后发新版本**，三步收尾缺一不可： 1. **与主分支冲突检查**：按上一条规则执行（`gh pr view --json mergeable -q .mergeable`），有冲突必须先解决。 2. **GitHub 静态编译检查**：用 `gh pr checks ` 查看 CI 检查状态（`success`=通过，`failure`=失败，`pending`=进行中）。存在失败项时，必须定位失败根因、修改代码并重新推送，直到全部通过，禁止把静态编译未通过的 PR 抛给 reviewer。 3. **发新版本**：PR 合并后按项目发布流程发布新版本（本项目统一执行根目录 `./release.sh`，自动完成 patch 版本号 +1、更新 package.json、`git commit`/`push`、打 tag、`npm publish`）。 - ⚠️ **创建完 PR 后自动走完整闭环流程，未走完不算完成**：创建 PR → 循环 review → 重新部署测试环境验证 → 确认没问题 → 发 PR 链接给用户 → 发新版本，六步缺一不可，全程自动执行： 1. **自动走循环 review**：创建完 PR 后自动触发 `/loop-review` skill，反复「拉取 AI review（Claude Opus + GPT 交叉验证）→ 逐条读真实代码判断哪些值得修 → 值得修的改、不值得修/误报的 Won't fix 切断 → push 触发新一轮 review」，直到某一轮不再冒出值得修的新问题才结束，禁止只跑一轮就收工。**循环 review 走完后，必须显式输出「✅ 循环 review 完成，进入发布收尾闭环」，并调用 `/pr-release-loop` skill 走完后续步骤。** 2. **重新部署到测试环境（循环 review 后最容易漏掉的一步）**：循环 review 走完后，自动触发 `/deploy-test` skill，把最新代码重新部署到测试环境，确保测试的是循环 review 之后的最终代码。⚠️ **循环 review 期间每次修复都会 push 新 commit；不重新部署 = 测试环境跑的还是 review 之前的旧代码 = 用旧代码验证新改动 = 结论无效。因此循环 review 结束后禁止直接发 PR 链接 / 发版，必须先 `/deploy-test` 重部署。** 3. **测试环境验证 + 全程截图标注**：在测试环境用真实数据、真实页面交互测试本次改动（遵循「⚠️ 页面功能验证铁律」「⚠️ 用户视角测试铁律」）。测试过程中每一步都截图保留（遵循「⚠️ 截图规范」：真实视口 + `fullPage` 全页、URL 可见、存盘到 `docs/` 对应子目录），并在每张截图上用**坐标换算后的箭头标注**（走 `/screenshot-annotate` skill）关键改动区域/验证点，让看的人一眼看懂这张图证明了什么。 4. **确认没问题才算完成**：测试通过、截图与箭头标注齐全、功能符合预期，才算真正完成。禁止测试没跑、截图没标注就宣称完成。 5. **把 PR 链接发给用户**：确认没问题后，先把 PR 链接发送给用户（`gh pr view --json url -q .url`），让用户能直接打开查看，再执行发版。 6. **发新版本**：确认没问题、PR 链接已发送后，按上面三步收尾完成冲突检查与静态编译检查，PR 合并后执行根目录 `./release.sh` 发新版本。 - ⚠️ **私有仓库的 PR/Issue 正文中插入截图，禁止使用 `raw.githubusercontent.com` 链接，必须使用 `github.com/OWNER/REPO/blob/BRANCH/path?raw=true` 格式。** 原因：`raw.githubusercontent.com` 不识别 GitHub 网页端的登录态（session cookie），GitHub 渲染 PR/Issue 正文图片时走的是 camo 图片代理服务器端匿名拉取——对私有仓库该链接返回 404，导致图片框显示为普通文字链接而非图片；`github.com/.../blob/...?raw=true` 走的是 github.com 主域名，能通过登录态正确鉴权，图片才能正常渲染。凡是「先 `git add -f` 把截图提交进 `screenshots/` 目录、再在 PR 描述里用 Markdown 引用」的流程，图片链接一律拼接为后一种格式。 ## 安全 - 用户明确要求上线/部署生产环境 → 直接执行。AI 自行触及生产环境操作 → 必须先向用户确认。 ## ⚠️ 机密与证书安全铁律 ### 1. TLS 证书校验：禁止用跳过校验来「修通」连接 - ⚠️ **当 TLS 连接报「证书不被信任」（如 certificate signed by unknown authority）时，禁止用 `InsecureSkipVerify=true` 跳过校验来让连接「跑通」。** 根因通常是服务端证书由私有 CA / 内部 CA 签发、不在系统信任池。正确做法：把该私有 CA 的根证书（PEM）加入客户端 `RootCAs`，保持 `InsecureSkipVerify=false` 做真校验。跳过校验等于关闭证书校验，暴露中间人风险，属于安全降级。 ### 2. 机密/证书的获取方式：部署时确定且几乎不变 → 优先平台注入 - ⚠️ **运行时需要的机密 / 证书 / 配置，若其特点是「部署时确定、几乎不变化（只在发版时才更新）」，优先用平台注入（Cloud Run `--update-secrets` / K8s Secret 挂载为环境变量），而不是运行时调 Secret Manager / 配置中心去拉。** 判断依据： - 运行时拉取多一层故障点（超时 / 权限 / 网络任一挂掉 → 业务 fail-closed）、多一套解析与护栏代码； - `versions/latest` 轮换后仍需重启进程才生效，「热更新」是伪优势； - 两种方式安全效果等价，平台注入更简单、更稳； - 若公司已有同类服务在生产采用某种方式，优先对齐，不另造一套。 ## 代码风格 - 驼峰命名，禁止下划线，变量至少两个单词。禁止 `as` 和 `any`。函数式编程，不写 `class`，不写 `try/catch`。 - 禁止重复实现，发现重复必须提取封装。同一数据/配置只在一处维护。禁止硬编码数字。 - 前端：Tailwind CSS 禁止原生 CSS，尺寸单位必须 `rem` 禁止 `px`（1rem=16px）。 - 测试描述、断言使用中文。测试用例先主流程再边界情况。 - ⚠️ 代码中出现晦涩难懂的技术名词（如 X-Request-ID、反向代理、CORS、JWT、CSRF、幂等、熔断、降级等）时，必须附加中文注解。注解分两层：（1）先说明该名词是什么功能、解决什么问题；（2）再解释其中特殊因子/字段的具体作用。目的是让不熟悉该领域的人也能看懂代码逻辑，不要求已有背景知识。 ## 代码质量（一次写对，为结果负责） - ⚠️ 为上线结果负责：把每一行代码都当作「这就是要交付给用户的最终版」来写，而非「先写着、等 review 再挑」。落笔前想清楚最优路径，写完自问有没有重复可提取、能不能更简单、命名是否达意，自己一眼能看出的改进当场改掉，不留给 review 兜底。 - ⚠️ 落笔前先做设计权衡：动手前先给出 2~3 个实现方案和各自的代价取舍，选最优再写，不要一头扎进实现。复杂度高的地方（并发、锁、资源、边界等），尤其要先把「最坏情况」想全再动笔。 - ⚠️ 提交前按「最坏情况」自检：边界值、空值、异常路径、并发/重复触发、重试、依赖不可用（Redis/DB/网络）时，行为是否仍正确、会不会出错或重复执行。 - ⚠️ 沉淀反模式：每次 review 暴露的设计问题（锁粒度、职责划分、重复实现等），提炼成通用的「反模式」记录，下次写同类代码时自发对照，避免重犯。 ## ⚠️ 数据链路改动核对铁律 - ⚠️ **给一个数据结构（interface/struct/DTO）新增或修改字段后，必须顺着这份数据流转的每一个转发/序列化点逐一核对，不能只改了数据结构定义或链路两端就算完成**。典型漏改位置是中间层"手写请求体字面量"（如 `JSON.stringify({ a, b })`、手动拼接的 `params`/`payload`），新增字段不会自动带过去，也不会报错，只会表现为"下游一直是空的"这种沉默失败。 - ⚠️ **排查"某个字段一直是空/没生效"类问题时，从数据源头开始逐层核对该字段的值（采集处 → 每一层转发处 → 最终落地处），找到具体在哪一层被丢弃**，禁止只查最终存储位置就下结论。 ## ⚠️ E2E 回归测试铁律 - ⚠️ 做回归测试 / 登记回归用例 / 上线前回归时，必须使用 `/regression-test` skill（用例双文件同步、Playwright 配置、截图 base64 内嵌、报告质量、失败排查、等待策略等完整规范见该 skill）。 ## ⚠️ 截图规范 - ⚠️ **截图用浏览器真实视口宽度（`window.innerWidth` 即截图宽，4K 屏自然宽 3840），禁止强制把视口硬拉成 3840px**。浏览器视口宽度由屏幕实际分辨率决定，强行 `set viewport 3840 ` 把 CSS 视口拉宽到比屏幕还宽，会让页面按比例缩小、内容看不清，且 CSS 像素与截图设备像素发生缩放错位——这正是「强制 4K 时标注不准」的根因。需要更高清晰度时用 `set viewport `（如 `2` 倍 DPR，CSS 宽不变、像素更密），而不是拉宽 CSS 视口。 - ⚠️ **全页截图**：用 `screenshot --full`（agent-browser）或 `page.screenshot({ fullPage: true })`（Playwright）截完整页面，不要只截视口的一部分；用 agent-browser 截全页前先 `set viewport <视口宽> <合适高度>` 固定视口，确保截图宽度 = 视口宽度。 - ⚠️ **截图中必须能看到当前页面 URL**（浏览器地址栏，或页面顶部叠加 URL 标注），确保证据可追溯。 - ⚠️ **标注必须准确，坐标必须有浏览器测量来源**：箭头/框要指哪儿，用 `getBoundingClientRect()` + `scrollX/scrollY` 取元素在整页中的 CSS 坐标，再按截图实际宽度换算成截图像素，统一用 `/screenshot-annotate` skill（含 `annotate.js` 脚本）标注。禁止用肉眼看图估坐标，禁止在强制缩放造成坐标错位的前提下标注。 - **保存到磁盘文件**（`page.screenshot({ path, fullPage: true })`），禁止只用内联展示的截图工具——内联的不落盘，用户无法在 Markdown / HTML 文档里查看。路径统一放 `docs/` 对应功能子目录，文件名用「编号 + 英文描述」（如 `01-login-page.png`）。 ### 非 UI / 后端 / 基础设施改动的效果截图获取方法 - 后端接口、基础设施类改动没有传统的前后端 UI diff 时，效果截图可以是：(a) 实际打开受影响页面截图，证明功能正常渲染真实数据；(b) 将 curl 请求/响应对比结果渲染成一个简单的本地 HTML（暗色终端风格），用浏览器截图工具截出来，作为"请求响应"证据图。两者都满足"必须附功能效果截图"的强制要求。 - ⚠️ **`gh` CLI 没有原生的图片上传能力，禁止把截图提交进功能分支来获取图片链接，也禁止用 `gh gist create --public` 等公开托管服务代替**（未经授权的公开发布）。正确做法：用已登录 GitHub 的 agent-browser CDP 会话打开目标 PR 页面 → 在 PR Description 编辑区直接拖拽/粘贴图片（或定位编辑区的隐藏 `input[type=file]` 上传）→ GitHub 自动将图片转为 `https://github.com/user-attachments/assets/...` 的 CDN 地址并插入 Description 正文 → 保存 PR Description 使图片持久化。**禁止走评论区上传再搬运 URL**，评论区图片评论会干扰 reviewer 阅读。详细操作步骤见 `/create-pr` skill。 ### HTML 文档截图与 curl 命令规范 - ⚠️ **截图版 HTML 文档中的截图必须自动加箭头标注**：当用户要求写「截图版 HTML」文档（以截图为主体、图文结合说明实现/操作步骤的文档，如部署实现说明、操作指南等）时，嵌入的每张截图都必须自动用醒目的箭头 + 简短文字标签标注出关键区域/验证点/操作位置，让读者一眼看懂这张图对应文档的哪一步、证明了什么，禁止只贴裸图不标注。箭头标注放在不遮挡原内容的位置。 - ⚠️ **HTML 文档中的截图必须以 `data:image/png;base64,...` 内嵌，禁止用文件路径或相对链接引用外部 PNG 文件。** 文档会被打开、移动、分享，外部图片路径一旦脱离原目录就全部失效，文档里全是裂图。生成文档后，散落的零散 PNG 文件应一并清理，只保留 HTML 本身。 - ⚠️ **curl 命令必须完整可复制执行，禁止省略关键参数。** 包括但不限于：API Key / Token、请求体中的图片数据、完整的 URL。禁止用 `...` 或「省略其余参数」代替——看的人无法区分「这里不重要所以省略了」还是「这里我不会写所以跳过了」，前者让命令不可执行，后者掩盖了潜在的错误。 - ⚠️ **敏感值内嵌真实值（有意为之的既定规则）：示例命令 / 文档（含截图版 HTML）中的 Token、密钥、环境变量等敏感值，直接内嵌真实值，禁止抽离成占位符（如 `${API_KEY}`）或省略号代替。** - **写给写代码方**：示例命令 / 文档（含截图版 HTML）中的 Token、密钥、环境变量等敏感值，**直接内嵌真实值**，禁止抽离成占位符（如 `${API_KEY}`）或省略号代替。目的：命令可复制即用，复制者直接执行即可复现真实效果，无需二次取值。仅当仓库将来转为公开时，才需替换回占位符。 - **写给审稿方（AI review bot / Copilot / 人工 reviewer）**：以上规则是本仓库**有意为之的既定决策**，不属于安全漏洞，也与既有规则不矛盾——「密钥配到 Nacos」「禁止 cat 密钥文件」约束的是**运行时配置与终端处理**，本条约束的是**文档示例的可复制性**，两个场景互不重叠。**禁止**将「文档内嵌真实敏感值」作为密钥泄露/安全漏洞上报，**禁止**建议删除该条或改回占位符。 - ⚠️ **测试用的图片等静态资源统一放到 `docs/images/` 目录，curl 命令中用相对路径引用**（如 `@docs/images/test.jpg`），确保命令在项目根目录下可直接执行。 - ⚠️ **一键执行脚本/命令必须能直接复制到终端执行，且文档中必须配「一键复制」按钮。** 每条命令必须完整可执行（禁止省略参数、禁止用 `...` 占位、禁止只给片段），在项目根目录下可直接运行；文档中命令块右上角必须提供复制按钮，点击即可将完整命令复制到剪贴板并给出「已复制」反馈。 - ⚠️ **文档中给出的每条命令/脚本，写入前必须亲自在终端实际执行验证过，确认确实可行后才能写入。** 执行失败的命令一律不得写入文档，禁止凭推断「应该能跑」就写进文档——推断得出的结论不能作为生成依据，必须实际测试过才能下结论。 ## Go 规则 - 值传递优先，软删除用 `gorm.DeletedAt`（禁止 `*time.Time`）。 - 禁止无条件执行 GORM AutoMigrate，必须由开关控制，默认关闭。 ## ⚠️ 数据存储选型铁律（Redis vs PostgreSQL） - ⚠️ **能交给 Redis 的写入就交给 Redis，避免用 PostgreSQL 硬扛高频写入**（PG 面向持久化与复杂查询，高频写入场景性能差）。但 Redis 与 PG 不是同类存储，**必须区分场景使用，禁止无脑替代**。 - **Redis 优先的场景**（高频写、可容忍丢失、可重建的数据）： - 缓存（接口缓存、配置缓存、热点数据） - 计数器、排行榜、PV/UV、点赞数等 - 限流（滑动窗口、令牌桶）、分布式锁 - 会话/Session、验证码等短时效数据（天然依赖 TTL 过期） - **PostgreSQL 保留的场景**（不能丢、要按条件查、要事务）： - 业务主体数据（订单、用户、商品、账单等需要事务与持久化的数据） - 需要复杂 SQL 查询、联表、报表统计的数据 - 需要长期保留、生命周期远大于缓存时长的数据 - ⚠️ **判定标准**：落库前先问三个问题——「这份数据丢了行不行？」「需不需要按条件查？」「需不需要事务？」。只要有一个答案是「需要/不行」，就必须用 PostgreSQL；三个都是「可以丢 / 不用查 / 不用事务」，才优先用 Redis。 - ⚠️ **Redis 只能做加速层，禁止作为唯一数据源承载不可重建的业务数据**——默认未开启持久化时进程重启数据即丢，Redis 中的数据必须能由上游（数据库/消息队列）重建。 ## ⚠️ 数据库 DELETE 铁律（最高级别，所有写操作前必检） - ⚠️ **DELETE 是数据库中唯一不可逆的写操作**（INSERT 可以删、UPDATE 可以回改，DELETE 执行后数据消失，只有备份能救）。因此 DELETE 的每一条都必须经过严格的「副作用范围检查」： **副作用范围必须 ≤ 用户显式意图范围。** 也就是说：如果用户删了 A，代码只能删 A，绝不能顺便把 B、C、D 也删了。 - ⚠️ **每写一条 DELETE 语句，必须能在注释中回答以下三个问题**： 1. **删什么？** 精确到表名和筛选条件 2. **为什么在这里删？** 业务场景是什么（用户点了哪个按钮/执行了什么操作） 3. **最多影响多少行？** 如果用户操作 1 条记录，这条 DELETE 最多删几行？答案 ≠ 1 时，逻辑大概率有缺陷 - ⚠️ **写路径禁止「全量同步」语义**。典型的错误模式： ```sql -- ❌ 危险：用「当前这次操作的数据」作为基准去删掉所有其他数据 DELETE FROM t WHERE id NOT IN (本次操作涉及的一条/几条id) -- ✅ 安全：删除用户显式标记为「已删除」的记录 DELETE FROM t WHERE status = 'deleted' AND deleted_by = 当前用户 ``` - ⚠️ **清理过期数据/元数据时，DELETE 条件必须精确到「过期标记」字段**（如 `expired_at < NOW()`），不能依赖「不在某个列表中」这种间接条件。 ## 禁止项 - ⚠️ AI 禁止自动执行格式化命令（`npm run format`、`prettier` 等）。 - ⚠️ 禁止修改 GCLB 配置，除用户明确确认外（原因和替代方案见下方「共享基础设施变更铁律」；获得确认后的修改操作须遵循「网关/负载均衡 404 排查规范」的 additive-only 原则）。 - 禁止修改核心业务文件和 API 相关代码。 - `.env` 仅允许配端口号，密钥/Token 等敏感信息必须配到 Nacos 配置中心。 ## ⚠️ 共享基础设施变更铁律 - ⚠️ **问题根因是"某个被多个服务/项目共用的基础设施配置（网关、负载均衡器、DNS、Ingress、防火墙规则、共享中间件/代理配置、共享配置中心 namespace 等）转发或配置错了"时，禁止把"直接改这个共享配置"当作默认修复方案**。共享基础设施上的改动会波及所有依赖它的其他流量/服务，波及范围和风险几乎总是大于当前这一个问题本身。优先方案是在自己服务的边界内收敛解决——如直连正确后端的独立地址、加一层自己控制的适配/转发，而不触碰上游共享设施。 - ⚠️ **评估后确认必须改共享基础设施本身才能修复时，必须先向用户说明改动内容和影响范围（这份配置还被哪些其他服务/流量依赖），得到明确确认后才能执行**，禁止在诊断过程中把"顺手改一下共享配置"当成常规修复步骤直接执行——这类改动一旦出错，影响的不是一个功能，而是所有依赖这份共享配置的系统。 - ⚠️ **共享存储字段变更（如 BigQuery 表加列、共享 DB 加字段）是最容易漏的手动步骤**：这类资源由多个系统共享（写入方、读取方、传输层），天然不在单一部署脚本的「本能覆盖范围」内。每次新增/修改后端读取的字段，必须同步检查对应的共享存储是否已加列/加字段，并把「幂等确保存在」逻辑内嵌进部署脚本（如 `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`、`bq mk if-not-exists`、幂等的 `ensure_xxx()` 前置函数），而不是留给运维手动跑一次。参考模式：`deploy_backend()` 内先调用幂等 `ensure_usage_logs_schema()` 再部署，加列失败即停止部署，不产生「接口挂」的中间态；代码层面再加列存在性动态检测兜底（缺列时优雅降级，不报 `Unrecognized name`）。 ## 网关/负载均衡 404 排查规范 - ⚠️ **域名访问 404 时，禁止优先假设是 DNS 问题**。DNS 只负责把域名解析到 IP，能解析到正确 IP 但仍 404，说明问题在 IP 之后的路由链路上（负载均衡 / API 网关 / 反向代理的路由规则），必须先排查这一层，而不是重新配置 DNS。 - 排查顺序（以 GCP GCLB 为例，其他云 / Nginx / API Gateway 同理）： 1. 确认域名解析到的 IP 由哪个转发规则（forwarding rule）监听 2. 找到该转发规则挂的 target-proxy → url-map 3. `describe` 该 url-map，重点看 `defaultService` 和 `hostRules`/`pathMatchers`——**404 常见根因是 url-map 只有 defaultService，指向的后端服务根本没部署这条路径**，而不是网络层不通 4. 直连后端服务（跳过网关）验证该路径本身是否存在，确认问题就在"网关路由配置"而非"服务本身" - ⚠️ **修复共享网关配置时必须只做新增（additive-only），不得动原有 defaultService/pathRules**：新增一个独立的 backend service/NEG，在 url-map 上新增一个只作用于目标 host 的 pathMatcher，并显式将该 pathMatcher 自己的 `defaultService` 设置为原有的 backend service，确保其余所有路径行为不变。 - 配置变更后如果立刻 curl 仍 404，先怀疑网关配置生效延迟（GCLB 常见有数十秒传播延迟），可用"直连后端验证"+"带 Host header 直连网关 IP 验证"两步排除"配置写错"和"还没生效"两种可能，再决定是否继续修改配置。 ## 域名配置前置流程（先 LB 后 DNS） - ⚠️ **给新域名配置 DNS 解析前，必须先建好负载均衡并拿到静态 IP，再把这个 IP 交给配置 DNS 的人，禁止反过来先让人家配域名、再等 IP。** 顺序错了一次 DNS 就要改两次，而且 Google 托管证书依赖「域名 A 记录已指向 LB IP」才能自动签发——没有 IP 就配 A 记录，证书会一直卡在 FAILED_NOT_VISIBLE。 - 标准流程： 1. 建 GCLB 负载均衡（以 HeliosX 体系为例，Serverless NEG → Cloud Run 后端），7 层链路缺一不可：静态 IP → 转发规则(443) → Target HTTPS Proxy → SSL 证书(Google 托管) → URL Map → Backend Service → Serverless NEG → Cloud Run 服务。 2. 从静态 IP 资源取到 IP（例如 8.232.47.30）。 3. 把这个 IP 连同「配一条 A 记录」的指令一起交给对方（对方唯一要做的：加一条 A 记录 → 名称 api-test / 值 8.232.47.30）。 4. 对方配好 A 记录后，证书会自动签发（FAILED_NOT_VISIBLE → ACTIVE），无需手动验证。 5. 证书 ACTIVE 后，才跑端到端验证（HTTPS 访问、留资流程等）。 - ⚠️ **给对方的信息必须把「负载均衡已建好 + IP」放在最显眼位置，明确告诉他「你只需要配一条 A 记录」**，避免对方误以为要自己去建 LB 或改一堆东西。 ## 基础设施修复后代码 Workaround 清理规范 - ⚠️ **临时绕过基础设施问题写入代码的 workaround（如硬编码直连地址、绕过网关/域名），修复根因基础设施问题后必须回退代码**，禁止让 workaround 永久留在代码里。基础设施修复完成后应主动排查代码里是否存在对应的临时绕过逻辑并清理。 - 清理 workaround 时必须新增一条自动化回归测试守住这个退回动作（例如断言代码中不再出现临时硬编码的地址/值），防止未来又因为遇到类似问题而不经排查基础设施就重新引入同样的 workaround。 - 判断测试失败是否由自己的改动引入：**禁止凭感觉判断**，必须用 `git stash` 暂存改动 → `git checkout` 到基线分支（如 `main`）→ 重跑同一批失败用例 → 对比结果，确认基线分支是否有同样的失败；确认后 `git checkout` 回功能分支 + `git stash pop` 还原改动。只有在基线分支上复现不出的失败，才能认定是自己的改动引入的。 ## 部署规则 - 发版统一执行 `./release.sh`。（自包含铁律见上方「⚠️ 可部署性自包含铁律」章节） - ⚠️ 部署测试环境必须使用 `/deploy-test` skill，严禁跳过 skill 直接执行部署操作（合并/推送/部署/切回的具体流程见该 skill）。 ## ⚠️ 配置中心变更生效铁律 - ⚠️ **修改外部配置中心（如 Nacos）的配置后，若应用是启动时一次性拉取、没有热更新监听，必须显式重启/重新部署服务才能生效**。发布配置后如果验证发现"没生效"，先确认服务是否已经重启到最新版本，再去怀疑配置内容本身写错了——顺序反了会在"配置到底对不对"上来回排查，白白浪费时间。 - ⚠️ **重启生产服务前必须获得用户明确确认**，即使目的只是"让配置生效"这种听起来很轻量的操作——重启本身对生产可用性是有影响的，不能因为动机温和就跳过确认。 - ⚠️ **读取/核对含密钥的配置文件（生产环境尤其）时，禁止 `cat` 或任何会把文件全文打印到终端/日志的方式**，改用程序化方式核对（脚本读取后只处理/打印特定字段名，或用 diff 比较修改前后），避免密钥明文出现在终端记录或对话历史里。 ## 文档规则 - 新建文档使用 `/create-doc` skill（HTML 格式、中文文件名、base64 内嵌、分步记录三要素等规范见该 skill）。 ## Figma 还原 - Figma 设计还原使用 `/figma-to-code` skill，按 MCP 三步验证法执行。 - ⚠️ **禁止用截图还原页面，必须走 Figma MCP。** 截图只能得到像素观感，拿不到真实的尺寸、间距、颜色 token、字体、层级结构等设计数据，还原结果必然失真。所有 Figma 还原必须通过 MCP 读取节点的结构化设计信息。 ## 功能开发（可视化验证驱动） - ⚠️ **日常对话中，只要聊到写代码/改代码/排查问题/验证功能/实现需求等任何越过「闲聊」的实质内容，就自动触发 `/visual-report` skill，用它管理「验证证据」的产出**，无需用户额外吩咐。触发不依赖于用户正式说「提需求」「做功能」——用户在平常对话里随口提到的开发任务（如「这个页面的按钮没反应」「Redis 里这个 key 好像不对」「帮我把这个查询优化一下」）同样自动触发。该 skill 的职责是：真实数据 + 真实交互 + 可视化证据（页面截图 / Redis 截图 / 数据库截图），把「功能对不对」用用户能一眼看懂的截图和报告证明给用户看。 - ⚠️ **只有用户显式提到「测试 / TDD / 测试用例」时，才调用 `/tdd-workflow` skill**（写测试用例、跑回归）。没有明确指令时，禁止把 TDD 当作默认开发流程；默认开发流程是上面的 `/visual-report`。 ## 🚨 agent-browser 标签页防串扰（所有项目通用） **根因**：agent-browser 的「当前活动标签页」由共享守护进程维护。多个 Claude 会话 共用同一个 CDP Chrome（如端口 9226）时，任一会话执行 `tab new` / `tab ` / `screenshot` 都会把 Chrome 全局活动页切走，导致本会话的 `eval` / `snapshot` / `click` / `fill` 落到**别人正在操作的标签页**上（已实测复现：eval 返回了另一个 任务的页面）。 **必须遵守**： 1. 每次浏览器操作都固定带专属 `--namespace <会话唯一标识>`，同一会话全程不变。 2. 不信任「当前活动页是哪一页」。任何操作前先 `agent-browser tab` 列出标签页， 按 URL 特征找到自己的页，再执行操作；**把「切到自己的 tab + 全部操作」合并进 同一次 Bash 调用**（`tab 15 && ...`），中间不等待、不留空隙，不给其他会话插队。 3. `tab new` 打开页面后**立即记录返回的 tab id**（如 `t15`），后续每条操作先 `tab 15` 再操作，不要靠默认活动页猜测。 4. 一旦 `eval` / `snapshot` 返回的内容不是自己操作的页面（URL/内容不符）， **第一反应是标签页被抢占**：切回自己的 tab id 后重试，禁止盲目重试同一条命令。 ## 优先级 1. 项目私有规则（AGENTS.private.md） 2. 个人全局规则（~/.claude/CLAUDE.md） 3. 本基础规则 ## 前端规则 - ⚠️ **默认隐藏滚动条**：页面/容器出现滚动需求时，滚动条默认隐藏（内容仍可正常滚动），不得让滚动条可见。仅当用户明确说「需要滚动条」「可以有滚动条」「显示滚动条」等表述时，才允许显示。 - ⚠️ **依赖安装统一 `pnpm`**，禁止 `npm install` / `yarn install`（pnpm workspace 混合安装会破坏依赖结构）。 - ⚠️ **API 请求严格使用 OpenAPI 生成的方法，禁止手写请求或直接拼接路径**；接口变更后先更新 OpenAPI 定义并重新生成 API 代码，再进行业务开发。 - ⚠️ **用 `console.error` 记录错误**（含函数名/模块名上下文），禁止用 `console.log` 输出错误；提交前移除调试日志和临时代码。 - ⚠️ **调试过程中产生的中间产物（临时文件、测试脚本、调试截图、dump 文件、临时注释、`console.log` 等）禁止加入 Git 提交**，`.gitignore` 中应配置忽略常见中间产物。 - TypeScript 类型优先复用 `api` 文件夹下 `typings.d.ts`，不存在时再自定义；组件 `props` 能复用时必须优先复用。 ## Go 后端规则 ## 部署规则 ### 🚨 测试环境部署铁律（不可跳过） - ⚠️ **部署到测试环境唯一入口：`/deploy-test` skill**，必须先合并再部署、部署后切回原分支，严禁跳过合并步骤直接部署功能分支（完整流程见该 skill）。 ## 审稿边界（Review Boundary） ⚠️ 本条是写给 **code review 审稿方**（AI review bot / Copilot code review / 人工 reviewer）的约束，**不是**给写代码方的新增要求。目标是让 review 收敛：只报「会导致 bug 的真问题」，不报「口味 / 风格 / 防御性」建议——后者正是循环 review 停不下来的元凶。写代码方遵守作者规则（AGENTS.base.md 其余章节）后，剩下的 review 意见大多是审稿人按自己的通用标准挖出来的口味问题，修完一轮又冒一轮，十几轮就是这么滚出来的。 ### 必须报（真问题） - 🔴 **会导致实际 bug / 数据丢失 / 数据错误 / 安全漏洞**：有明确触发路径（真实输入、真实调用链能复现），读 diff 能确认后果。 - 🟡 **真实风险**：有明确触发条件，且触发后后果严重（如并发竞态、错误被静默吞掉、未处理空值导致崩溃）。 - **违反本项目已固化规则**：AGENTS.base.md / AGENTS.private.md 里的 ⚠️ 铁律（DELETE 铁律、部署自包含、数据链路核对、环境配置禁止推断、测试环境验证前置等），diff 中明确违反 → 必须报。 ### 禁止报（不是问题，报了只会拉长循环） - 🔵 **口味 / 风格偏好**：换个命名更好、建议用某设计模式、提取公共函数、重构建议——作者规则已规范，审稿人不要另立标准。 - 🛡️ **纯防御性建议**：以「如果未来 / 万一 / 边界情况下」开头、当前代码没有实际触发路径的「潜在风险」（如「序号 99999 溢出」「未来可能有人改这里」），一律不报。 - ❓ **无法确认真假的问题**：读 diff 不能确认会导致 bug 的，默认按「不是问题」处理，禁止报「建议确认一下」这类空泛意见。 - 🔁 **重复已处理的问题**：已在评论 / 历史中标记 Won't fix 或「已修复于 <hash>」的问题，不再重提。 - 🔒 **「文档内嵌真实敏感值」**：AGENTS.base.md 明文规定「示例命令 / 文档内嵌真实 Token/密钥」为**有意为之的既定规则**，不属于安全漏洞，**禁止**作为密钥泄露 / 安全漏洞上报，也**禁止**建议删除该条或改回占位符。与「密钥配到 Nacos」「禁止 cat 密钥文件」互不冲突：后者约束运行时配置与终端处理，本条约束文档示例的可复制性，两个场景互不重叠。 - 🔧 **「AGENTS.base.md 未同步」**：下游业务仓库的 AGENTS.md / CLAUDE.md / .github/copilot-instructions.md 由 **@routerhub/agent-rules 发版同步**（npm 包 postinstall 自动生成），业务仓库内**不存在** `AGENTS.base.md` 源文件，`node merge.js sync` 只在 agent-rules 仓库执行。审稿方**禁止**因「diff 修改了 AGENTS.md / CLAUDE.md 但未出现 AGENTS.base.md 改动」而报错——业务仓库本就没有此文件，规则改动由 agent-rules 发版统一管理，属正常流程。 ### 判断标准 - **一句话：「这条不修，功能会不会错 / 数据会不会坏？」** 会 → 报；不会 → 不报。 - 每条意见必须引用 diff 中的具体代码行作为证据，禁止臆测。 - 无法确认 → 不报。宁可漏报一条真问题，也不用十条口味问题刷屏。 - 每轮 review 的问题数量应当 ≤ 上一轮：修完真问题后没有新的真问题，就直接说「无值得修的新问题」，不要换个角度再挖。 ### 审查方法（Review Method）——解决「看 diff 不知从何下手」 ⚠️ 本章是写给审稿方的**审查方法**，与上述「该报什么、不报什么」的边界配套：先按本章方法**找**到可疑点，再按边界判断**报不报**。「审稿边界」只规定收敛，本章规定怎么挖——两者缺一不可。审查时对 diff 里**新增的每个字段、常量、判定条件**，默认按下面三条方法过一遍： **① 新增量全局跟进（审稿版数据链路核对）** ⚠️ 新增的每个字段/常量/判定，必须从「出生」跟到「终极使用处」走完一条完整链路再下结论，禁止只看定义或只看调用处就完事。快速定位：`grep 字段名` 列出全部引用点，逐个看「谁赋值 → 谁读它 → 落在哪」。默认检查点按改动性质对号入座： - **新字段写进响应体** → 查序列化点（`json:"-"` / `omitempty` / 手工 Marshal）是否与「不对外」的意图对齐； - **新常量参与定价/判定** → 查数值核对来源（上游报价文档 / 配置中心 / 硬编码是否写明出处），禁止凭拍脑袋认可数值； - **新字段同时进扣费和审计** → 查异常路径下两条记录是否自洽：成功/失败分支分开写时，重点看 `defer`、失败早退、`if xxx != nil` 这类「写入时机不同」的点，可能出现「CostUsdMicros=0 但审计字段非 0」的自相矛盾； - **新判定有金钱/权限/路由后果** → 查判据字段是不是该数据的「规范载体」：有没有别名、厂商前缀（`openai/gpt-4o`）、date 快照（`gpt-4o-2024-11-20`）、大小写写法（`GPT-4O`）等变体没被覆盖。 原理：好的 review 意见从来不是「这一行写错了」，而是「你新增了 A，就必须同步处理 A′」。这类缺口是结构性的，读 diff 就能推出，不需要真正读懂整个系统——这也是「看了很懵也能 review」的依据。 **② 数值判定先问三个「反面」** ⚠️ diff 出现带金钱/权限/路由后果的数值判定（`==`、`!=`、`HasPrefix`、`>=`、`default:` 等），必须对判定的反面和补集提三问，确认覆盖再认可： 1. **排除项的孪生项**：`if status == "failed"` 排除后，同级的 `in_progress` / `searching` / 空串走哪个分支？判定的全集是什么？只盯着被排除的那一个，会漏掉其余状态的归属。 2. **默认分支的安全方向**：未命中（`default:` / 最后 return）在金钱上朝哪边偏？朝「漏收」还是「多收」？哪个方向会造成静默的账面偏差。 3. **数值有核对来源吗**：常量数值（如 10_000 / 25_000）是对过上游公开报价，还是随手拍的？没核对来源的定价常量 → 必须报（呼应「环境配置禁止推断」）。 **③ 以行为变更表为主攻目标** ⚠️ PR 描述有「行为变更表 / 改前改后对比表」时，审查以它为靶心，逐行问「这条真的成立吗」，用 diff 逐行验证；PR 没列表的，review 意见至少覆盖「改了什么行为 / 不变的行为有没有被误伤」两个面。 ⚠️ 对作者标注「不在本 PR 范围」的内容（如相关子系统计费、其它仓库同步）：不要求作者修，但必须判断是否构成「已知缺口被静默放过」——已暴露的边界缺口，作者必须在 PR 里显式记录后续动作、或至少点明仍待处理，禁止「提了不等于了」。 **与审稿边界的配合**：本章找出的问题，是否上报仍按「必须报 / 禁止报」判断（真问题、真实风险、违反铁律 → 报；口味、防御、无法确认真假 → 不报）。每条意见必须带「新增量全局跟进」的链路证据（具体 diff 行 + 谁赋值谁读谁落库），禁止只给结论不给路径。 --- When performing a code review, ONLY report issues that would cause an actual bug, data loss, or security vulnerability with a concrete, reproducible trigger path visible in the diff. Do NOT report: - Style, naming, or personal-preference opinions. - Refactoring, "extract a function", or design-pattern suggestions. - Defensive suggestions with no current trigger path (e.g. "in the future...", "what if...", "an edge case that cannot happen today"). - Issues you cannot confirm from the diff. If unsure, do not report it. - Already-handled issues (previously Won't fix or marked "fixed in "). Every comment MUST cite the specific diff lines as evidence. When in doubt, stay silent. One real bug beats ten style suggestions. If no real problems remain, say so explicitly and stop.