求一个后端（Java、Python）的Claude.md

问题描述：

求一个后端（Java、Python）的Claude.md
感谢佬~

网友解答：

---

--【壹】--：

蹲一个!

---

--【贰】--：

蹲一下！

---

--【叁】--：

牛的佬，抄作业了

---

--【肆】--：

## Repo Coding Conventions - Prefer `pydantic` models or `TypedDict`-style typed structures over passing raw untyped `dict` objects through the system. - Avoid `getattr` for normal application flow. Prefer explicit typed fields, dedicated adapter/helper methods, or small boundary objects. Reserve `getattr` for true dynamic interop boundaries such as plugin hooks, third-party SDK objects, or narrowly scoped test shims. - Prefer `class` + `@staticmethod` helper organization over scattered free functions when the logic belongs to a parser, loader, or service domain. - Reuse existing repository patterns and elegant implementations before introducing a new parsing or loading approach. - If a behavior, intent, or tradeoff is unclear, ask the user instead of guessing. The user is willing to clarify. - Favor object-oriented structure for runtime and service code. - Prefer imports at the top of the file unless a local import is required to break a real circular dependency or avoid an unusually heavy startup cost. Prefer explicit module imports over relying on `__init__.py` re-exports. - After finishing a change, run targeted `pytest` coverage and `uvx ty check` before handing off.

基于我个人习惯的python编码规范

---

--【伍】--：

已严肃复制

---

--【陆】--：

接入了Superpowers的。佬可以看看，然后最好根据自己的项目做修改，

AGENTS.md

# 全局 Agent 规则 本草案基于原始 `AGENTS.md` 的章节结构进行精简，并将 superpowers 集成进主流程中。 # 指令优先级 - 指令优先级从高到低： 1. 当前会话中用户的明确要求 2. 仓库自身的规则、文档与约定 3. 相关 superpower / skill 的流程定义 4. 本 `AGENTS.md` 的个人补充规则 - 默认优先使用 superpowers 作为主要工作流引擎。 - 本文件保留个人硬门禁、环境约束、交付偏好与沟通方式，不再重复展开 superpower 已经定义的完整细节流程。 - 若本文件某项规则被明确视为“个人硬门禁”，则即使使用 skill，也仍需满足该门禁。 - 对于仅涉及审查、分析、解释或方案讨论而不修改仓库文件的任务，可不进入完整实现流程，但仍应保持推理清晰、结论可追溯。 - 如果用户明确要求 `continue nonstop`，则默认持续推进，直到满足验收标准或出现真实阻塞。 # Step by Step Reasoning Workflow - 如果需求模糊，应先澄清目标、约束、验收标准与边界条件。 - 为跟踪进度，请维护一个可见的任务列表。 - 在其中列出先前任务的状态和待办事项，以及项目所需的计划行动（对于简单的问答可以跳过此步骤）。 - 对多步骤任务，任一时刻仅保留一个 `in_progress` 步骤，在开始新步骤之前及时标记已完成的步骤，并避免在消息中重复完整的计划。总结变更内容并突出显示下一步。 - 回答时优先给出最相关结论，再补背景、依据与权衡。 - 在任务推进过程中，遇到新信息时应主动修正先前判断中的错误或不一致。 - 多步任务优先使用 `update_plan` 或同等方式维护高层进度，不重复输出冗长计划。 # How to Set up the Environment - 本节作为推荐默认项，而非默认阻断门禁。 - 当仓库依赖虚拟环境、依赖安装或本地工具引导时，推荐先完成环境初始化。 - 如果仓库没有明确环境要求，可直接按当前任务所需执行最小准备。 说明： - 上述命令为通用示例，实际以仓库文档和当前平台为准。 - 在 Windows 环境下，优先使用 PowerShell 兼容方式与 `.venv\Scripts\...` 路径。 # Command Verification Rules - 不得虚构已运行的命令、退出码或验证结果。 - 如果一个关键验证命令无法执行，必须明确说明原因。 - 在缺少验证证据时，不得声称“通过”“完成”“可提交”“可合并”。 - 如果用户或仓库要求特定验证命令，应优先执行该命令。 - 若关键验证被阻塞，应如实报告当前状态，并根据阻塞程度决定是否继续实现或先与用户确认。 # Change Validation Workflow 本节保留为全局验证闸门，用于承接 superpower 实现阶段之后的统一质量检查。 在声明完成、准备 `commit`、准备 `push`、准备发起 PR 之前，应满足以下要求： 1. 运行与本次变更直接相关的最新测试，并如实报告结果。 - **默认要求 Agent 自己执行**：优先跑受影响模块 `mvn -pl ... -am test`（必要时兜底 `mvn test`），并在交付说明中给出所跑命令与结果摘要（如 `Tests run`/`BUILD SUCCESS`）。 - 若因环境/权限/依赖导致无法执行，必须明确说明阻塞原因，并告知用户需要其代跑的命令与需要回传的关键输出。 2. 若任务属于功能开发、bug 修复或行为变更，应确认本次工作遵循默认 TDD 路径。 3. 仓库存在 `pre-commit` 时，推荐执行，尤其适用于： - 较大变更 - 准备 PR 前 - 用户明确要求时 4. `pre-commit` 默认不是阻断门禁，除非用户或仓库规则明确要求。 5. 若仓库要求更重验证，例如构建、集成测试、冒烟测试或特定脚本，应优先遵循仓库规则。 6. 如果某项关键验证无法执行，应明确说明，并降低完成度表述。 补充原则： - 测试是硬门禁。 - `pre-commit` 是推荐实践，不是默认阻断项。 - 更重的验证以仓库规则和用户要求为准。 - 本仓库的测试与联调规范见：`./.ai/TESTING.md`。 ## Java / Maven 验证（本仓库） 本仓库为纯后端（Java + Maven 多模块）。`Change Validation Workflow` 中的“测试”默认指： - 跑**受影响模块**的 Maven 测试（包含编译 + 单测/集成测；即使当前模块暂无测试用例，也至少保证编译与门禁通过）。 - **不要求每次都做手工冒烟**（例如 `curl`、启动全套服务）。若变更涉及认证/网关/配置等高风险链路，优先补充 Spring Boot 测试覆盖关键路径；确有必要时再做手工冒烟，并在任务卡/说明里写清楚步骤与预期。 推荐命令（按改动模块选择其一；优先用 `-pl ... -am` 限定范围）： - 改动 `auth/**`：`mvn -pl auth -am test` - 改动 `visual/*/**`：`mvn -pl visual/<子模块> -am test` - 多模块同时改动：`mvn -pl <module1>,<module2> -am test`（兜底：`mvn test`） 备注： - 本仓库在 `validate` 阶段启用了 `spring-javaformat-maven-plugin`，因此运行上述命令会同时执行代码格式门禁。 ## SQL / DB 变更交付物（本仓库） 当需求涉及数据库结构或初始化数据变更时，**仅改 Java 类/Mapper 不够**，必须同时交付可执行的 SQL（便于评审、落库与回滚）。 最低要求： - **更新基线初始化脚本**：`db/auth.sql`（以及需要时的 `db/config.sql`），保证新环境/新同事一键拉起仍可用（`db/Dockerfile` 会把这两个文件放进 MySQL 的初始化目录）。 - **提供升级脚本**：新增 `db/patches/*.sql`（建议按时间+语义命名），用于把“已有旧库”升级到新版本（因为 MySQL 初始化脚本只在首次建库时执行，已有 volume 不会自动应用新 `auth.sql`）。 - **说明是否包含数据迁移**：若有 DML（更新/补数据），需说明幂等性与执行前置条件；避免不可逆或大范围破坏性操作。 建议命名与内容： - 文件名：`db/patches/YYYYMMDD_HHMM_<short-desc>.sql` - 文件头部写清楚：影响的库/表、前置版本、变更原因、回滚建议（可选）。 本地验证建议： - 优先在本地 MySQL 先执行 `db/patches/*.sql` 并验证（尤其是唯一索引/幂等/事务行为），再进入联调/上线。 ### 新表建模 & CodeGen（停留点规则） 当需求涉及**新增表/改表**且后续需要生成 CRUD 代码时，按以下流程推进（避免手写与生成风格混用）： 1. **先停留（DDL 先行）**：Agent 必须先交付建表/改表 SQL（DDL），并明确影响的库/表/索引；不要直接在仓库里手写 `controller/mapper/service/entity`。 2. **用户本地建表**：由开发者在本地 MySQL 执行 DDL（或应用 `db/patches/*.sql`），确认表结构与索引 OK。 3. **用户生成 CRUD**：使用 `visual/codegen` **直接根据表结构**一键生成 `controller/mapper/service/entity`（以及对应 XML/DTO 等，按模板配置）。 4. **Agent 负责集成**：把生成代码整理进对应模块，并在其基础上补业务逻辑、权限、参数校验与联调改造。 ### 模块分库约定 新增业务模块默认使用**独立数据库**（例如 `player`），并交付： - 基线脚本：新增 `db/<module>.sql` - 升级脚本：新增 `db/patches/*.sql` 避免把该模块的业务表结构直接追加到 `db/*.sql`（除非是全局共用表/跨模块表）。 # Core Development Workflow ## 默认总线 1. 需求模糊、需要设计澄清时： - `brainstorming -> writing-plans` 2. 已有计划文档并开始执行时： - `executing-plans` 或 `subagent-driven-development` 3. 进入具体功能、bug、行为变更实现时： - `test-driven-development` 4. 阶段性完成、准备提交或准备交付前： - `Change Validation Workflow` 5. 合并前： - `requesting-code-review` 6. 开发结束后的分支收尾与交付： - `Commit Workflow -> finishing-a-development-branch` ## 文档维护 - 每当以下任何一项发生变化时，请更新 `<path/to/plan.md>` ：计划、目标、约束/假设、关键决策、经验教训、步骤、进度状态（已完成/进行中/下一步）。写计划前可使用`brainstorming`。 - 将复杂任务分解为有效的子任务：在开始实现代码之前，评估工作量的大小，包括你需要完成任务所需的时间，以避免在任一迭代中承担过多。如果任务复杂，将其分解为范围受限的更小子任务，保持因果依赖。将第一步子任务的范围设定为具有挑战性但在约 5-10 分钟内可完成。将其余任务推迟到下一次迭代，输出到步骤 8（“迭代”）的待办事项中。跟踪待办事项和所选的（第一）子任务。 - 迭代：报告尚未完成或目前仍在待办事项中的任务，并为下一个任务/待办项从第 1 步重新开始工作流程（不等待新的用户消息）。 ## 开发原则 1. 对功能开发、bug 修复、行为变更，默认采用 TDD。 2. 对复杂任务，将其分解为范围受限的更小子任务，保持因果依赖。将第一步子任务的范围设定为具有挑战性但在约 5-10 分钟内可完成。将其余任务推迟到下一次迭代，输出到迭代的待办事项中。跟踪待办事项和所选的（第一）子任务。 3. 若用户只要求分析、评审或解释，则不强制进入实现总线。 4. 复杂任务需求，询问用户是否启用开发分支进行开发。 # Commit Workflow ## 前置条件 - 在 `commit`、`push`、`PR` 前，应先满足 `Change Validation Workflow`。 - 在 merge 前，应先完成 `requesting-code-review` 或使用`/review`命令进行变更审查流程。 ## 默认行为 - superpower 工作流可在适当时机执行 `commit`、`push`、`PR`、merge 或分支收尾。 - 如果仓库自身存在更明确的 Git 规范或发布流程，应优先遵循仓库规范。 ## 提交粒度 - 推荐保持提交边界清晰、可审查。 - 尽量避免将无关格式化、调试痕迹和功能改动混在同一提交中。 - 推荐优先选择小而可审查的提交，而不是一个过大的混合提交。 ## 提交流程偏好 - 推荐先查看 `git status`，理解改动范围。 - 推荐只添加与当前任务相关的文件。 - `pre-commit` 在可用时推荐执行，但默认不作为阻断门禁。 ## Commit message 偏好 使用使用符合形式的`<type>(scope): summary`完成提交。 - 提交类型 | 类型 | 说明 | | -------- | ------------------------ | | init | 项目初始化 | | feat | 新功能 | | fix | 错误修复 | | docs | 文档变更 | | style | 代码格式化（不影响逻辑） | | refactor | 代码重构 | | perf | 性能优化 | | test | 测试相关 | | build | 构建系统或外部依赖 | | ci | CI 配置 | | chore | 辅助工具变动 | | revert | 撤销提交 | - scope 使用模块/目录，无明确范围可省略。 - summary 使用中文、动词开头，长度 ≤ 50 字，不加句号。 - 对于复杂的提交，提交信息的正文应说明提交的作用、存在的理由以及实现方式。可选地，也可以包含任何其他相关的上下文信息。 - 破坏性变更 - 在 type 后添加 `!`，或在正文写明 `BREAKING CHANGE: ...`。 - 明确写出受影响范围与升级指引。 如果仓库采用不同的提交规范，以仓库规范为准。 # 后端进程治理 - 当任务需要启动本地后端、dev server、watcher、proxy、bridge 或其他长生命周期进程时，默认目标是最少新增、优先复用、结束即回收。 - 启动新后端前，先检查： - 是否已有同类服务在目标端口运行 - 是否已有当前任务可复用的现成会话或进程 - 是否其实只需要一次性命令，而不是常驻服务 - 若启动长生命周期进程，应记录最小必要信息： - 启动命令 - 工作目录 - 监听端口 - 进程 PID 或 session id - 对于本次任务由 agent 启动的长生命周期进程，除非用户明确要求保留运行，否则在任务结束前应主动清理。 - 不应把“服务已启动”直接视为成功，必须确认其真实可访问、响应正常、不是旧残留进程在工作。 - 只清理由当前任务启动的进程，不顺手终止来源不明的同类进程。 # Guidelines and Best Practices 指南和最佳实践 ## How to Report Bugs - 清晰描述 bug 的现象、触发条件、预期行为与实际行为。 - 给出尽量稳定可复现的步骤。 - 说明真实影响范围与严重程度。 - 清晰地解释真实世界中的后果，使用具体、详细、现实的用例，并关联影响严重程度和修复优先级（ `High` 、 `Medium` 、 `Low` ）。 - 描述已知的解决方法并概述潜在的解决方案。 - 同时，收集任何有助于诊断 bug 的额外上下文信息，例如使用模式、错误信息、堆栈跟踪、日志文件、环境/配置文件以及软件版本。 ## How to Find and Fix Bugs - 默认优先使用 `systematic-debugging` 进行排障与根因分析。 - bug 修复默认仍应进入 TDD 路径，而不是直接猜测式修补。 - 分析复杂 bug 时，应结合日志、近期改动、测试覆盖与实际行为，而不是只看表面报错。 - 在宣布 bug 已修复前，必须回到 `Change Validation Workflow`。 ## How to Write Tests 如何编写测试 - 测试优先覆盖关键路径、边界情况和错误路径。 - 测试应具体、可读、稳定，避免脆弱测试。 - 测试必须“自解释”：测试类写 JavaDoc 概述被测对象/覆盖范围；测试方法用 Given-When-Then 命名或 `@DisplayName` 标明“场景/预期”。 - 对 `assertEqual` 类断言，优先遵循“expected 在前，actual 在后”。 - 若任务属于功能开发、bug 修复、行为变更，默认采用 TDD。 ## How to Write Code 如何编写代码 - 遵循 SOLID、DRY、关注点分离与 YAGNI。 - 命名应清晰、抽象应务实。 - 仅在关键或不直观逻辑处添加简短注释，避免注释噪音（指行内/块注释；不包含方法级 JavaDoc）。 - **JavaDoc 规范（强制）**：对外 API（`public/protected`）、Controller/Service/Feign 等入口方法必须写 JavaDoc（`/** ... */`），说明“做什么/关键约束”，并补齐 `@param/@return/@throws`（如有）；`@Override` 可用 `{@inheritDoc}`，并在需要时补充差异说明。 - JavaDoc 禁止使用 HTML 标签（如 `<p>`、`<ul>`、`<li>` 等前端标识），统一使用纯文本分段、简短句子或普通换行表达结构。 - JavaDoc 模板（示例）： /** * 方法用途（做什么/关键约束）。 * @param foo 参数含义 * @return 返回值含义 */ - 修改行为时，优先移除死代码和明显过时的兼容路径，除非用户明确要求保留。 - 明确处理边界条件，不要隐藏失败。 - 关注时间复杂度和空间复杂度，尤其在高 IO 或高内存路径上。 - 新增文档字符串时，保持简洁，说明目的、关键假设与实现理由。 - 除非没有更合理方案，不主动添加大范围 linter 抑制注释。 - 代码指标（硬性上限） - **函数长度**：≤ 50 行（不含空行）。超过立即抽取辅助函数。 - **文件大小**：≤ 300 行。超过按职责拆分。 - **嵌套深度**：≤ 3 层。用早返回/守卫语句压平结构。 - **参数数量**：位置参数 ≤ 3。更多则改用配置/选项对象。 - **圈复杂度**：每函数 ≤ 10。超过拆分分支逻辑。 - **禁止魔法数字**：提取为具名常量（例如 `MAX_RETRIES = 3`，不要裸写 `3`）。 ## How to Refactor 如何重构 - 默认优先保持行为不变，再提升结构质量。 - 重构应在测试保护下进行，必要时先补测试再重构。 - 如果检测到循环导入，请将共享逻辑提取到新工具模块中——或提取到现有模块中，以保持依赖图无环——而不是添加深层导入链。 - 对较大的重构，优先先拆分计划，再按步骤推进。 - 重构完成后，仍需回到 `Change Validation Workflow` 与 code review 流程。 ## Safety Rules 安全规则 - 不要运行破坏性命令，例如 `git reset`，除非用户明确要求。 - 不要使用非 Git 工具操作 `.git` 目录。 - 避免危险删除命令，除非其作用范围被明确限制在临时产物。 - 不要将密钥、凭证、API Key 硬编码进源码文件。 - 数据库访问应使用参数化查询。 - 不要通过拼接不可信输入来构造 shell 命令或 SQL。 - 在系统边界校验并清理外部输入。 - 除非用户明确要求，否则不要终止非当前任务启动的进程。 ## 沟通风格 ### 语言约定 - 默认使用简体中文回答，可混用英文技术术语。 - 代码标识符使用英文。 - 代码注释优先简体中文，保持简洁清晰。 ### 技术内容规范 #### 代码与数据展示 - 多行代码、配置、日志，优先使用带语言标识的 Markdown 代码块。 - 示例代码聚焦核心逻辑，省略无关部分。 - 需要强调变更时，可使用 `+ / -` 辅助表达差异。 - 仅在确有必要时使用表格。 #### 结构化数据与图示 **呈现优先级**： 1. **列表** - 默认首选，适用于绝大多数场景 2. **表格** - 仅用于需严格对齐的结构化数据（如参数对比、配置项） 3. **ASCII 图示 ** - 当纯文本难以清晰表达结构 / 流程 / 层级关系时使用 **ASCII 图示使用规则：** - **适用场景**： - 结构类：架构图、文件树、数据结构（树 / 图 / 链表） - 流程类：状态机、时序图、流程图、生命周期 - 关系类：类图、ER 图、依赖关系、网络拓扑 - **常用符号**：`├──`、`└──`、`│`、`→`、`┌┐└┘`、`[节点]`、`●` - **核心原则**：保持简洁（避免超过 20 行或过度复杂） - 必须配文字说明，辅助理解 - 优先使用 UTF-8 框线符号（更美观） - 仅在必要时使用（非装饰性） ## 🛠️ Mandatory Tool Usage Policy (工具调用绝对准则) **CRITICAL INSTRUCTION (核心指令):** 文档位置：`./.ai/TOOL.md`。 你的工具使用权限受到严格管控。**绝对禁止**凭猜测或习惯随意调用工具（如 `fast-context`, `context7`, `shrimp-task-manager` 等）。 在决定调用任何工具之前，你 **必须 (MUST)** 文档规范。 1. **阅读准则**：如果你对当前该用哪个工具、或者是否该用工具存有任何疑虑，必须优先查阅文档中的触发条件 (Triggers) 和禁用场景 (Anti-patterns)。 2. **强制规范**：如果用户的请求命中了文档中的“禁用场景”，立刻停止调用该工具，并尝试用已有上下文或直接回答。 3. **快捷路径优先**：当需要查阅 Vue、Supabase 或其他常用库的文档时，文档中缓存有硬编码库 ID（如 `supabase/supabase`），则优先使用该ID进行查询，若ID失效，再调用搜索功能进行查询，且修改改ID。 4. **文档维护原则**：当使用context7的搜索功能查询了指定id库的文档，及时更新添加我们的专属文档与库 ID 缓存规则，保证下次可以用到缓存。 **你的行动准则**：将文档视为你的“工具操作说明书”，一切工具调用逻辑以此文档为最高准则 ## 个人硬门禁 ### 1.1 Codex 子代理只读护栏 - 在 `Codex` 中，子代理**允许使用**，默认分为两类安全任务：1）只读任务：代码/文档检索、日志排查、只读比对、规格审查、代码审查、方案分析、事实收集；2）无命令改动任务：在主代理预先圈定的文件范围内，直接修改代码/测试/文档，但不承担命令执行与最终验证。 - 在 `Codex` 中，子代理默认不得承担带副作用的执行任务；尤其禁止直接执行安装/重装依赖、删除/清理目录、`git add/commit/push/checkout/reset`、打开 GUI、越权写目录、联网下载、构建、E2E、全量门禁、以及任何其他高概率触发审批或沙箱提权的命令。 - 在 `Codex` 中，子代理的 `shell_command` 仅允许用于只读查询；默认禁止用子代理执行会修改工作区、写缓存、调用外部程序链或依赖 `sandbox_permissions=require_escalated` 的命令。代码落地优先通过补丁编辑完成，测试、构建、提交与提权统一由主代理执行。 - 对 `superpowers` 工作流的收口规则：`spec reviewer`、`chunk reviewer`、`code reviewer`、日志/代码探索类子代理仍可使用；`subagent-driven-development` 这类实现型子代理默认不用，除非该子任务已被明确约束为“限定文件改动 + 不跑命令 + 不提权 + 不提交”的安全子任务。 - 如果子代理在执行过程中发现下一步需要提权、审批、写入或其他副作用动作，**不得直接申请审批并继续执行**；必须停止在当前边界，向主代理返回结构化交接信息，由主代理决定是否向用户发起审批，并由主代理亲自执行该动作。 - 子代理上报给主代理时，至少要包含：触发原因、拟执行命令、是否必须执行、预期影响、建议的 `justification` / `prefix_rule`（如适用）、以及若不执行会阻塞哪一步。 - 原因：当前已确认 `Codex + superpowers` 路径下，子代理一旦卷入 `Approval needed in <agent>` / `Waiting for <agent>`，用户体感上容易表现为“子代理卡死”；因此本仓库默认策略不是禁用子代理，而是把子代理收敛为低风险的“只读 + 无命令改动”角色，把审批、验证与其他副作用收回主代理。 ## 技能（Skills） - 开始任务前，应优先判断是否存在匹配的 superpower 或 skill。 - 若任务命中 skill，阅读其 `SKILL.md` 并按流程执行。 - 本文件默认采用以下主干整合方式： - `brainstorming / writing-plans / executing-plans / test-driven-development` - `-> Change Validation Workflow` - `-> requesting-code-review` - `-> Commit Workflow` - `-> finishing-a-development-branch` - 在回复中声明本次使用了哪些技能。 ### 输出结尾建议 - **简短总结**：复杂内容后附简短总结，重申核心要点。 - **引导下一步**：结尾给出实用建议、行动指南或鼓励进一步提问。

TESTING.md

# Testing 规范（Java / 纯后端 / 多模块） > 目标：让 Agent 在“上下文不足 + 微服务启动顺序复杂”的情况下，仍能用**小范围可验证**的方式交付高质量变更。 ## 1. 验证原则（硬门禁） 1) **只跑相关模块**：默认禁止全仓库大规模测试/构建；优先用 Maven 的 `-pl ... -am` 限定影响范围。 2) **优先写测试用例**：纯后端项目一般不要求每次手工冒烟（curl/起全套服务）；用 JUnit/Spring Boot 测试覆盖关键路径即可。 3) **数据相关变更必须测数据**：涉及 Mapper/SQL/事务/唯一约束/幂等逻辑时，必须提供可验证的“数据层测试”（见第 3 节）。 ## 2. Maven 推荐命令（按改动范围选择） > 用例：在 `Change Validation Workflow` 中作为默认验证命令。 - 改动 `auth/**`：`mvn -pl auth -am test` - 改动 `visual/<子模块>/**`：`mvn -pl visual/<子模块> -am test` - 多模块同时改动：`mvn -pl <m1>,<m2> -am test` 如果测试耗时过长或环境不允许（例如 CI 资源限制），至少保证： - `mvn -pl <module> -am -DskipTests package` 通过（仍会编译 + 跑 `validate` 门禁）。 ## 3. “数据测试”怎么做（推荐） 适用场景： - 新增/修改表结构、索引、唯一约束 - 修改 Mapper SQL / MyBatis 映射 - 修改幂等逻辑（例如“查不到就创建”、并发唯一键冲突回查） 推荐测试类型（从轻到重）： 1) **Service 逻辑单测（最常用）** - 用 Mockito 等方式 mock 掉外部依赖（Feign/缓存/时钟），验证业务分支与异常语义。 2) **Mapper/事务集成测试（数据变更必选）** - 目标：验证 SQL 与事务行为（唯一约束、并发冲突、回滚）符合预期。 - 选择其一： - 本地 MySQL（开发机/CI 提供）：测试用例里用独立 schema/前缀表名避免污染 - Testcontainers（如未来引入）：更贴近 MySQL 行为，适合微服务数据层 最小要求： - 每个“新增/变更”SQL 行为至少 1 条成功用例 + 1 条失败/冲突用例（例如唯一键冲突）。 ### 3.1 本地 MySQL 验证（推荐） 你们本地开发环境通常已经有可用的 MySQL 库，因此数据相关变更建议优先在**本地 MySQL**完成验证，再进入联调/上线： 建议流程（尽量轻量）： 1) 在本地库执行本次的升级脚本：`db/patches/*.sql`（必要时同步更新 `db/*.sql` 基线）。 2) 跑受影响模块的测试：`mvn -pl <module> -am test`（至少保证编译+门禁通过）。 3) 若脚本包含 DML/迁移，建议在本地先备份或使用独立 schema/测试库验证，避免污染日常开发数据。 ## 4. 多模块/微服务联调（仅在必要时） 当变更属于“跨服务行为变更”（例如鉴权链路、Feign 契约、网关路由/鉴权）时，仅靠单模块单测可能不足；此时做**最小联调**： ### 4.0 Nacos 是否必须？ - **跑单测/数据测试（不启动服务）**：通常不需要 Nacos。 - **启动服务做联调/手工验证**：通常需要 Nacos。 - 现有多个服务（例如 `-auth``visual`）在 `application.yml` 使用了 `spring.config.import: nacos:...`（非 optional），没有可用 Nacos 时会直接启动失败。 - 因此：联调环境建议直接启动 `register`（Nacos）或使用外部可用的 Nacos；不建议为了“省 Nacos”在联调时临时改成另一套配置来源（容易与真实环境偏离）。 - 可以尝试按顺序启动服务，若测试多次都是失败，可以让用户来启动 ### 4.1 启动顺序（必须） 1) `register`（Nacos） 2) `auth` 3) `upms` 4) `gateway` > 说明：基础设施（MySQL/Redis）需提前可用；联调时尽量只启动“与本次变更相关”的服务，避免全量启动。 ### 4.2 联调要求（尽量轻） - 优先用自动化测试覆盖跨服务契约（例如 Feign 入参/返回 DTO、错误语义）。 - 若必须手工验证，固定为“最小成功路径 + 最小失败路径”，并在任务说明里记录验证步骤与预期（避免临时口口相传）。

TOOL.md

# 工具调用规范（仓库级） > 目的：避免 Agent 随意调用不必要/高副作用工具，导致验证成本飙升或卡在审批流程。 ## Core Directives (核心原则) 作为 AI Agent，你配备了多种强大的工具，但**绝对禁止**在每次对话中无脑调用它们。在调用任何工具之前，必须进行以下思考： 1. **当前上下文是否已足够？** 如果问题可以通过已有代码片段、常识或推理解决，**不要**调用工具。 2. **工具是否匹配当前场景？** 严格按照下述各工具的专属场景进行调用。 3. **保持静默**：如果不需要工具，直接回答用户，不要解释你为什么不调用工具。 4. 如果工具失效，无法调用，则跳过该工具的使用，进行降级处理。 --- ## Tools Breakdown & Triggers (工具调用场景详解) ### 1. `fast-context` (Windsurf 快速代码查找) * **用途**：在本地代码库中快速定位文件、类、函数或特定代码片段。 * **何时使用 (Triggers)**： * 当用户要求修改特定文件，但你当前上下文中没有该文件时。 * 当需要追踪某个函数或组件在 Vue 生态或其他前端框架中的定义和引用时。 * 当遇到未知的报错，需要查看报错堆栈中提到的具体本地文件时。 * **何时不准用 (Anti-patterns)**： * 用户已经贴出了需要修改的代码。 * 询问通用编程知识（如“Vue 的生命周期是什么”）。 #### 工具优先级 1. **已知函数名/类名** → `Grep` 2. **理解业务逻辑 / 探索代码 / 查找实现** → `Augment search_context`（返回完整代码片段，语义理解强） 3. **Augment 结果不足** → `Fast-Context`（返回文件路径+行号，附带 grep 关键词建议） 4. **Fast-Context 返回 grep keywords** → 立即用 `Grep` 二次精确搜索 5. **仍未找到** → 组合 Glob + Read + Grep ### 2. `context7` (深度上下文/记忆检索) * **用途**：获取更广泛的项目背景、架构文档或跨文件的深度依赖关系。 * **何时使用 (Triggers)**： * 在进行大规模重构、架构设计或需要理解整个项目（如命令行工具或全栈项目）的设计模式时。 * 当 `fast-context` 找不到足够信息，需要补充项目的历史背景或全局状态时。 * 需要查阅特定技术栈的官方文档或 API 接口时。 * 无需我明确要求，当我需要库或API文档、生成代码、创建项目基架时或配置步骤时。 * **何时不准用 (Anti-patterns)**： * 只需修改单行代码或修复简单的语法错误。 * 已经知道具体的本地文件路径（此时应使用 `fast-context`）。 * 专属文档与库 ID 缓存规则： * **Supabase (后端/BaaS)**: `supabase/supabase` * **Vue 3 (前端核心)**: `vuejs/core` * **Vue Router (前端路由)**: `vuejs/router` * **Pinia (前端状态管理)**: `vuejs/pinia` * **Vite (构建工具)**: `vitejs/vite` * **Node.js (后端/CLI 环境)**: `nodejs/node` * **TypeScript (类型系统)**: `microsoft/TypeScript` * **Tailwind CSS (样式框架)**: `tailwindlabs/tailwindcss` ### 3. `shrimp-task-manager` (任务拆解与管理) * **用途**：将复杂的大型需求拆解为可执行的子任务。 * **何时使用 (Triggers)**： * 用户提出了一个宏大或多步骤的需求（例如：“帮我从零开发一个新的全栈功能”、“重构数据库结构并更新前后端”）。 * 需要在长期任务中保持进度追踪。 * **何时不准用 (Anti-patterns)**： * 单步操作或简单的问答（例如：“帮我写一个正则表达式”、“优化这个函数的性能”）。 ### 4. `sequential-thinking` (深度思考链) * **用途**：进行复杂的逻辑推理、系统设计或疑难 Bug 排查。 * **何时使用 (Triggers)**： * 遇到难以定位的诡异 Bug，需要逐步验证假设。 * 设计复杂的算法、数据流或状态管理方案。 * **何时不准用 (Anti-patterns)**： * 常规的 CRUD 代码生成。 * 直接可得出结论的简单任务。 ### 5. `mcp-server-time` (时间感知) * **用途**：获取当前的现实时间。 * **何时使用 (Triggers)**： * **仅在**用户的需求强依赖于当前系统时间时调用（例如：“在今天的日志文件中添加一条记录”、“生成一个以当前时间戳命名的文件”）。 * **何时不准用 (Anti-patterns)**： * 其他所有不涉及具体时间的常规编码和问答。**绝对不要**在每次对话开头习惯性获取时间。 ### 6. `mcp-deepwiki` (Wiki 知识检索) * **用途**：搜索外部 Wiki 中的名词解释或事实性知识。 * **何时使用 (Triggers)**： * 遇到你的训练数据中缺乏的专有名词、内部协议或特定的百科知识时。 * **何时不准用 (Anti-patterns)**： * 解答常规的编程问题或处理本地代码逻辑。 ### 7. `playwright` (浏览器自动化 - 当前可能处于停止状态) * **用途**：自动化操作浏览器，进行 UI 测试或页面抓取。 * **何时使用 (Triggers)**： * **仅在**用户明确指令要求“测试这个页面”、“抓取某个网站的数据”或“模拟用户点击”时。 * **何时不准用 (Anti-patterns)**： * 仅需要编写前端 UI 代码但不需要实际运行测试时。 --- ## ⚖严格边界限定 (Strict Tool Boundaries) ### `fast-context` vs `context7` 的终极抉择 这两个工具极其容易混淆，你在调用前必须遵循以下强制逻辑： * **第一优先级：明确目标 -> `fast-context`** * **触发条件**：只要用户提供了**具体的文件名**（如 `App.vue`）、**具体的函数名**（如 `fetchUserData`）或**明确的报错堆栈路径**。 * **强制动作**：必须优先使用 `fast-context` 进行“精确打击”。 * **第二优先级：模糊探索 -> `context7`** * **触发条件**：用户提出了**概念性需求**（如“我们项目里是怎么处理鉴权的？”）、**跨文件逻辑**（如“帮我理清整个登录流程”）或当你使用 `fast-context` 找不到关键信息时。 * **强制动作**：此时才能升级调用 `context7` 进行“大范围扫描”。 * **绝对禁止 (Red Line)**： * 禁止在知道具体文件路径的情况下使用 `context7` 去读取该文件。 * 禁止连续两次使用不同的参数盲目调用这两个工具。如果第一次检索没有找到关键信息，必须停下来**思考 (sequential-thinking)** 或**询问用户**。 --- ## 复杂任务的工具链编排 (Tool Chaining Logic) 当你面对一个复杂需求时，不要随意穿插使用工具，必须按照以下标准工作流（SOP）执行： 1. **需求降维 (Task Breakdown)**： * 收到超大需求（如“开发一个新页面并联调接口”）时，**第一步必须且只能**调用 `shrimp-task-manager` 将任务拆解为 3-5 个清晰的子步骤。 2. **背景摸排 (Context Gathering)**： * 进入具体的子任务后，如果缺乏背景，先用 `context7` 了解全局，再用 `fast-context` 定位到需要修改的具体代码行。 3. **疑难排查 (Troubleshooting)**： * 如果代码运行报错，且报错信息十分诡异（涉及多层异步或环境配置），**必须先调用** `sequential-thinking` 列出至少 3 种可能的错误原因，然后再用 `fast-context` 去查看对应文件验证你的假设。 --- ## 故障保护与死循环预防 (Fail-Safe & Anti-Loop) 为了防止你（Agent）陷入无意义的计算消耗，严格遵守以下熔断机制： 1. **重复调用限制**：如果你对同一个工具（特别是检索类工具或网页搜索 `mcp-deepwiki`）连续调用 **2 次**均未获得有效信息，**立即停止调用**，并向用户报告缺失的信息或请求帮助。