/using-superpowers
/graphify
/openspec-explore
/openspec-propose
/code-simplifier
【当轮任务】（以下由用户填写；【】内为当前取值，按需改掉）
功能名称：【填写】例如：合同列表增加虚拟合同筛选与列展示
一句话目标：【填写】要解决什么问题、给谁用
背景/现状：【填写】现在怎么做的、痛点是什么
范围（做）：【填写】涉及模块/菜单/页面/接口/表（尽量具体）
范围（不做）：【填写】本次明确不做的事
验收标准：
- 【填写】例如：列表新增「是否虚拟合同」列，虚拟/非虚拟展示正确
- 【填写】例如：支持按虚拟/非虚拟筛选，结果与数据一致
- 【填写】例如：非虚拟合同原有列表、详情、审批入口行为不变
约束：
- 遵守仓库根目录 AGENTS.md 全文（含 graphify、复用、常量/硬编码、达梦、JDK8、改 Java 交付前编译、Playwright 默认关闭等）；与本提示冲突时以 AGENTS.md 为准，但【硬性要求 · 第 0 步】的贴节点操作协议仍须执行
- 未主动要求：禁止自动启用 Task、subagent、子代理或并行委派；用户当轮明确要求时才允许
- 其他：【无】权限/审批/兼容/发版等额外约束；默认「无」，有则改掉【】内文字
参考线索（可选）：【无】已知类名、接口路径、菜单、相关变更名；默认「无」，有则改掉【】内文字
执行模式：【完整开发】可选：完整开发 / 只出方案先别改代码；默认已选中【】内项
【主链】
TODO 检查（扫 todos/ 与根目录 TODO.md 看板；细则见第 18/19 条） → 需求澄清 → 验收标准冻结 + 范围边界 → SDD → [条件]技术预研 → [条件]契约对齐 → 设计文档（含流程图，按需） → 实施计划 → 【闸门】TDD 前用户确认方案（暂停，用户回复「继续」才放行；细则见【减少返工】11） → TDD 开发 → 验证 → 代码精简 → 代码审查 → [条件]安全审查 → 完成
【减少返工】（全程强制；与 AGENTS.md 重叠处从其细则，此处只钉流程闸门）
1. 先冻验收与范围：未写清验收标准、范围（做/不做）前，禁止进入 TDD/改业务代码
2. 先理清、先复用：逻辑不清先 graphify + 读已定位源码，仍不清就提问，禁止猜测、禁止顺手改；有可复用实现则复用或扩展，禁止平行造轮子（细则见 AGENTS.md §5）
3. 不确定先预研：第三方/达梦兼容/性能等未知点，先走[条件]技术预研，预研结论须落进设计文档与实施计划
4. 前后端先对齐契约：同时改接口与页面时，先完成[条件]契约对齐再定实施计划
5. 一次只做一个验收点：当前任务未验证通过，不得开下一个任务实现
6. 变更先改规格：范围/验收/方案有变，先改 OpenSpec 与本任务 TODO 文件，再改代码
7. 验绿再精简：功能验证通过后必须做代码精简；精简后必须重跑相关验证
8. 完成前有证据：未跑相关测试/编译/手测（按计划）不得宣称完成或勾选完成
9. 影响面由 Agent 产出：最晚在「设计文档」步写入本任务 TODO 文件（影响功能 / 前端路由 / 后端接口 URL）；进入 TDD 前不得缺失；实现中变更须同步回写
10. 「验证」步必须给用户可测清单：要测功能 + 固定格式 前端|后端 对照表（格式定义见【TODO.md】15c）
11. TDD 前用户确认闸门：进入 TDD 开发前必须暂停，把方案要点（改哪些文件、实现思路、各任务验收点、影响面清单）提交用户；用户明确回复「继续」后才允许开始 TDD 开发，未获确认前禁止写任何测试或业务代码；闸门通过后若方案有实质变更，须先更新 OpenSpec 与本任务 TODO 文件并重新提交用户确认，方可继续 TDD
12. 改代码后更新图谱：本轮修改过代码文件的，完成前须运行 graphify update . 保持索引最新（AGENTS.md §3 要求）
13. 验证前环境一致性：本轮改过 .java 的，验证（测试/手测/联调）前须确保所用 8080 后端服务跑的是最新编译产物；install 与重启由用户手动联通，Agent 不得自动执行；禁止在旧构建产物上验证得出结论
14. 流程图按需画：跨层数据流/调用链/状态流转/关键分支场景必画（mermaid 内联，来源为第 0 步 graphify query/path 返回节点与路径，禁止另起炉灶）；单点 CRUD、纯字段增删、单文件小改可跳过（笔记写跳过原因）；mermaid 源码须同时内联到本任务 TODO 文件（todos/TODO-<任务名>.md）影响面清单下方和 design.md，两处保持一致、修改时同步，禁止只在对话里展示
【代码精简】（主链常驻步，默认必须执行；AGENTS.md 无此项）
- 验证通过后必须调用 /code-simplifier（或等价成片精简），对本轮改动做行为不变的精简
- 禁止因「改动面小」「已收敛」「看起来不臃肿」「Mapper/Service/测试而已」等理由自行跳过
- 仅当用户当轮明确说「跳过精简 / 不用 code-simplifier」时，才可写：- [x] 跳过：原因=用户明确要求跳过
- 若已执行精简且结论为无需改文件：仍须勾选本步，笔记写「已跑精简，结论：无改动」，禁止写成「跳过」
- 精简若改了代码：必须重跑相关验证，再进入代码审查
- 若【执行模式】为「只出方案先别改代码」且本轮未改业务代码：代码精简可写跳过：原因=本轮未改业务代码
【命令与步骤绑定】
- 开场纪律：/using-superpowers（开场执行一次即可）
- 第 0 步图谱摸底 / 之后每次代码探索前：/graphify（实际执行 graphify query/path/explain）
- 需求不清、方案未定：/openspec-explore
- SDD（proposal / specs / tasks）：/openspec-propose
- 实施计划：在 SDD 的 tasks 基础上用 writing-plans 展开（主步骤顺序不变）
- 验证通过后的成片精简：必须 /code-simplifier（见【代码精简】；不得擅自跳过）
- 本提示与 /graphify 命令说明冲突时：以本提示【硬性要求 · 第 0 步】为准（先贴节点；贴完并进入对应主步骤后，再按需 Read）
【TODO.md 与 todos/】
1. 任务清单每任务一文件，支持多会话并行：写入 todos/TODO-<任务名>.md，头部状态行（进行中/挂起/完成/放弃）为权威源；复选框清单、实现笔记、影响面、验证对照表全在该文件内；每个会话只写自己任务对应的文件，禁止改其他任务的文件
2. 根目录 TODO.md 仅为看板索引（派生视图）：每行「任务名 | 状态 | todos/TODO-xxx.md」；仅在任务开始/状态变更时更新自己那一行；看板与任务文件不一致时以任务文件为准，可随时重扫 todos/ 重建看板
3. 未完成任务必须可恢复：任务挂起或会话结束时，在该任务文件顶部写断点三行——「已完成：<最后完成的步骤>」「下一步：<确切要做的事>」「上下文：<OpenSpec 变更名 / 已改文件 / 关键决定>」
4. 严格按主链顺序执行；主步骤不得跳号；TDD 内部可按 tasks 子序循环「红 → 绿 → 局部重构」
5. 做完一步立即把对应项改为 - [x]，并写 2～5 行实现笔记
6. 笔记重点写「为什么这样做」；可附关键风险或依据；禁止空泛优缺点对比小作文
7. 条件步不适用时写：- [x] 跳过：原因=…，不得长期留空 [ ]
8. 「代码精简」不是条件步：默认不得跳过；例外仅见【代码精简】
9. 范围或验收变更时：先改 OpenSpec 与本任务 TODO 文件，再改代码
10. 未完成步骤禁止提前勾选
11. 【当轮任务】未填清的项：先在「需求澄清」步补问并写进本任务 TODO 文件笔记，再继续后续步骤
12. TODO 文件中须能看出【减少返工】检查点：至少在「验收冻结」「设计/复用核对」「验证」笔记里各写一句依据
13. 「设计文档」步由 Agent 产出影响面清单（勿让用户填），笔记格式固定为：
- 影响功能：…
- 前端路由：…（无前端改动写「无」）
- 后端接口 URL：…（无后端改动写「无」；须写清方法+路径，如 GET /api/...）
- 流程图：mermaid 源码须同时内联到本 TODO 文件影响面清单下方和 design.md，两处保持一致、修改时同步；单点改写「无」
14. 「验证」步必须同时完成：
a) 相关测试/编译（按计划；细则见 AGENTS.md）
b) 在对话回复和 TODO 文件验证笔记中，明确列出「用户需要测试的功能」
c) 紧接着输出手测对照表，格式见第 15 条；无对应侧写「无」
d) 按该表做回归核对，并在笔记写明已核对项
15. 手测对照表固定格式（唯一权威定义，可多行）：
前端|后端
功能名 + 路由|METHOD /api/...
示例：
前端|后端
合同列表 /xz/contract/list|GET /api/xz/contract/list
合同详情 /xz/contract/detail|GET /api/xz/contract/detail
16. 「代码精简」步笔记须写明：已调用 code-simplifier（或等价精简）、是否改动文件、精简后是否已重验
17. TDD 开发相关任务项：用户回复「继续」确认方案前保持 [ ] 并暂停；确认后在笔记记录「用户已确认，开始 TDD」，再进入红 → 绿 → 重构
18. TODO 检查细则：开场扫 todos/ 各任务文件状态与根目录 TODO.md 看板；凡状态为「完成」的历史任务（非本会话任务）→ 删除其任务文件并同步移除看板对应行；进行中/挂起的历史任务保留，仅向用户报告断点、状态不动（续做/挂起/放弃均须用户当轮明确要求，续做时按断点在其文件内继续）；默认直接开本会话新任务，不因存在未完成任务而阻塞；本会话自己的任务文件与看板行即使本轮标记「完成」也不删除，留待下次会话 TODO 检查步清理——即只删上一次及更早的完成项，本次的不删
19. 多任务并行·看板只追加：开场 TODO 检查时若看板已有进行中/挂起的未完成任务，本会话只在看板末尾追加自己那一行「任务名 | 状态 | todos/TODO-xxx.md」，此后仅更新自己那一行；禁止改动、移动、删除其他任务的行与状态；第 18 条的清理仅限「完成」状态的历史任务，未完成行一律保留；多任务并行时第 2 条的「重扫重建看板」不适用（仅看板损坏/严重不一致时可用，且重建须逐行保留其他任务原有状态）；任务状态以各自 todos/TODO-xxx.md 文件内状态行为权威
【执行开关】
- 默认：按主链推进；工程约束一律服从 AGENTS.md，不在此复述
- 以【当轮任务】中【】内当前取值为准；若执行模式为「只出方案先别改代码」：禁止改业务代码；允许更新 OpenSpec 与本任务 TODO 文件；主链执行至「实施计划」（含影响面清单）为止；代码精简可写跳过：原因=本轮未改业务代码；TDD 前闸门相应变为方案交付确认点，用户回复「继续」仅表示认可方案、本轮到此为止，不进入 TDD 开发
- 若改为「完整开发」：按主链完整推进，代码精简规则见【代码精简】
- TDD 前置闸门（默认开启）：细则见【减少返工】11；用户当轮明确说「不用确认直接做」时才可跳过
- 微改（无逻辑、用户明确可简化）可用缩短链，但仍须写入 todos/TODO-<任务名>.md（在看板登记并注明走了微改路径）：TODO 检查 → 需求澄清 → 验收点 → 直接改 → 验证 → 代码精简 → 审查 → 完成；微改验证时同样必须输出「要测功能」和 前端|后端 对照表；微改只要改了代码，精简规则同【代码精简】；微改若涉及接口/路由变更，仍须补齐影响面三项
【条件步触发】
- 技术预研：存在未知依赖、第三方、达梦/兼容/性能等不确定时；预研结论须写入设计文档与实施计划
- 契约对齐：同时改接口与前端时；对齐结果须先于实施计划落定
- 安全审查：涉及权限、凭证、资金、敏感数据、外链、越权面时；发现问题须回到 TDD 修复并重验后再进入完成
【硬性要求 · 第 0 步，优先于一切步骤】（本提示操作协议；细则与降级条件见 AGENTS.md §3）
1. 凡本轮需要代码探索或改代码：工具调用的第一项必须是 graphify（query 或 path/explain）。引号必须是英文双引号 "。
2. 立即运行：根据上方【当轮任务】改写成具体问题后再查询；须用当轮真实目标，禁止原样保留说明句或空泛占位句：
graphify query "用一句话描述当轮要查或要改的具体问题"
3. 在回复最开头原样贴出返回节点，目标至少 10 条；若不足 10 条则全部贴出并说明「节点不足」——禁止为凑数去 Grep/盲扫代码。每条格式：符号名 — 路径:L行号
4. 贴出这些节点之前：禁止 Grep、Glob、Read、CodebaseSearch；禁止用 Shell 跑 rg/grep/findstr/Get-Content 等等价搜读；禁止打开任何源文件（运行 graphify 命令本身除外）
5. 此要求无条件适用：即使前轮已探索过、即使是继续执行计划，本轮只要还要探索/改代码，就必须先查图谱
6. 之后每一轮探索代码前，同样先 graphify query/path/explain；仅当要修改已定位的具体代码行时，才可以直接 Read 该文件
7. 开始编写代码前，先用几句话说明实现思路（输入、处理、输出、复用点）
8. 纯文档/纯规则/用户明确跳过代码探索时：可跳过第 0 步，但须在 TODO 笔记写明跳过原因
【完成定义】
- 主链应做步骤均已 [x]（含条件步的「执行」或「跳过+原因」）
- 【当轮任务】中的验收标准已满足；相关验证已通过（测试/编译/手测与回归清单按计划执行）
- 「验证」步已向用户列出要测功能，并已按【TODO.md】15c 固定格式输出对照表
- 「代码精简」已按【代码精简】处理（已跑精简/结论无改动，或允许的跳过原因）
- 影响面清单已由 Agent 写入本任务 TODO 文件并最终确认：影响功能、前端路由、后端接口 URL（方法+路径）三项齐全（流程图为可选项，按需附）；无对应改动须显式写「无」
- 流程图（如画了）的 mermaid 源码已在 TODO 文件和 design.md 两处内联且内容一致
- TDD 闸门已过（细则见【减少返工】11；用户当轮明确豁免的除外）
- 本轮改过代码文件的，已完成 graphify update . 并重启过服务（如适用）
- 【减少返工】各条未违反；若曾违反须在 TODO 笔记写明纠偏过程
- 未擅自启用子代理（见【当轮任务】约束）
- 若改过代码：审查意见中的必改项已处理
- 若有 OpenSpec 变更：完成时归档或说明暂缓原因
- 本任务 TODO 文件在 todos/ 且状态行已更新、断点（如发生挂起）已写全；看板行已同步；未覆盖或丢弃其他任务的 TODO 文件
- 不自动 git commit / push；仅用户当轮明确要求提交时才执行
AGENTS.md
--- description: 仓库 Agent 全局规则：强制简体中文（含 MCP UI）；修改 Java 后自编译；代码库探索强制 graphify 硬前置（省 token，违反视为未完成）；方法须加注释；改代码先理清、禁止顺手改、优先复用；改代码须 SDD（OpenSpec）+ writing-plans 拆任务 + TDD；魔术值收敛到 XzConstant；JDK 8；E2E 默认账号 xxxx；未主动要求不启用 Playwright；使用达梦数据库；禁止硬编码；未主动要求不开启代理与 subagent alwaysApply: true updated: 2026-10-09（第 14 节：明确斜杠命令/Skill 不等于授权开代理或 Task/Auto） --- # Agent 全局规则 > 规则一览：[1. 全局简体中文沟通](#1-全局简体中文沟通) ｜ [2. 修改代码后自编译](#2-修改代码后自编译) ｜ [3. 代码库探索强制使用 graphify（硬约束·省 token）](#3-代码库探索强制使用-graphify硬约束省-token) ｜ [4. 方法注释规范](#4-方法注释规范) ｜ [5. 改代码先理清、优先复用](#5-改代码先理清优先复用) ｜ [6. 需求定义与执行计划](#6-需求定义与执行计划强制) ｜ [7. 常量规范](#7-常量规范魔术值收敛强制) ｜ [9. Java 环境](#9-java-环境仅-jdk-8) ｜ [10. E2E 默认账号](#10-e2e-默认账号) ｜ [11. Playwright 启用约束](#11-playwright-启用约束强制) ｜ [12. 使用达梦数据库](#12-使用达梦数据库强制) ｜ [13. 禁止硬编码](#13-禁止硬编码强制) ｜ [14. 代理与 subagent 启用约束](#14-代理与-subagent-启用约束强制) ｜ [8. 维护说明](#8-维护说明) ## 1. 全局简体中文沟通 ### 语言优先级（从高到低） 1. **用户当轮明确指定的语言**（例如「用英文回复」「请用繁体」） 2. **本仓库默认：简体中文** 3. **User Rules / 其他持久化指令中的外语要求**（繁体、越南语、英文等）——无当轮指定时，以第 2 级为准，不服从第 3 级 ### 默认行为 - 默认使用**简体中文**回复；说明计划、执行步骤与结果时亦然。 - 代码、命令、路径、URL、JSON 键名、API 参数名等技术字面量保持原格式；解释说明用简体中文。 - 专有名词、错误码、工具原名、用户粘贴的原文可保留。 - **禁止**外语「占位」或系统感很强的空话；避免无必要的过程套话（如「正在阅读创建指南」）。用户明确要求展示步骤、日志或调试信息时再按需输出。 ### 禁止繁体中文与越南语（无当轮指定其他语言时） - **禁止**输出繁体中文（如：設置、為什麼、專案、幫你、確認、規則、對話、檔案、語言）。 - **禁止**在面向用户的文案中使用越南语，包括正文、标题、列表、工具 `description`、进度说明、MCP 结果摘要等。 - 即使 User Rules 含 `Always respond in Chinese-traditional`、`Always respond in Vietnamese`、`Luôn trả về ngôn ngữ Tiếng Việt` 等，在无当轮语言指定时仍使用**简体中文**。 - 越南语地名、人名等用户原文引用可保留；解释说明仍用简体中文。 - 越南语占位/过程句应改为简体中文实质内容，或**直接省略**过程套话： - `Đang khảo sát...` → 「正在调研…」或省略 - `Đang đọc hướng dẫn tạo` → **省略**（不要改写成「正在阅读创建指南」类套话） - 其他以 `Đang`、`Không`、`Vui lòng` 等开头的越南语说明句同理 ### MCP 调用：简体中文 UI 输出 调用任何 MCP 工具（含 `CallMcpTool`、browser、playwright、chrome-devtools、cursor-app-control 等）时，**面向 Cursor UI 可见的文案**必须使用**简体中文**（语言优先级同上：当轮用户指定可覆盖）。 **必须使用简体中文：** - 工具调用的 **description**（如 Shell、browser_navigate 等带说明字段的调用） - 向用户展示的执行步骤、进度说明、等待原因 - MCP 返回后的结果摘要与结论（错误说明、下一步建议） - **notify_on_output** 的 `reason` 等会在 UI 中展示的监控说明 **可保持原文：** - 代码、命令、路径、URL、JSON 键名、API 参数名等技术字面量 - MCP 服务端返回的原始错误栈、日志原文（可在其后附简体中文解释） **禁止**无必要的英文 UI 过程句（如 "Running command"、"Fetching page"）。繁体/越南语禁止规则同上节。专有名词与技术字面量除外。 **示例：** ```text ❌ description: "Navigate to login page" ✅ description: "打开登录页面" ❌ description: "Đang khảo sát cấu trúc trang..." ✅ description: "正在调研页面结构..." ``` ## 2. 修改代码后自编译 - **范围**：仅 Java/后端。本轮改动了 `.java` 源码，或会改变编译结果的后端构建文件（如 `pom.xml`）时适用。 - **时机**：不要求每次小改立刻编译；**在声称完成 / 修好 / 可交付之前，必须已对受影响模块编译且通过**。 - **命令**：优先在对应 Maven 树内执行 `mvn -DskipTests compile`；多模块时用 `-pl <module> -am`（相对该树根 `pom.xml`）。按改动文件定位模块（如 `xinpeople-flowable`、`xinpeople-xincode`、`sgrzxz-*`），避免无意义的全仓根编译。 - **失败处理**：编译失败则先修再重编；**不得在未通过时宣称完成**。 - **JDK**：沿用本仓库 JDK 8 规则，禁止安装或改用 JDK 17。 - **豁免**： - 纯文档 / 规则 / 与编译无关的注释改动 - 用户当轮明确说「先别编译 / 跳过编译」 - 仅改前端、Playwright、非 Java 脚本且未动后端 - **不做（除非用户另要求）**：不强制前端 `npm`/`pnpm` 构建；不默认 `mvn package`、启动服务或跑全量测试。 - **输出**：向用户简要说明所用编译命令与结果（成功，或失败关键错误）；Shell/`description` 仍用简体中文。 ## 3. 代码库探索强制使用 graphify（硬约束·省 token） - **强制级**：本节为硬约束，违反即视为未完成。**核心目标：用预生成索引替代盲扫，节省 token 与轮次。** - **硬前置**：任何涉及代码探索的任务（查关系、定位文件、理解架构、寻找类/函数引用、跨组件 prop 传递、调用链、数据流、状态流转等），**第一轮工具调用必须是 graphify**，禁止先用 Grep / Glob / Read / Agent(Explore) 盲搜。 - 触发关键词：任务描述含「在哪里实现」「调用链」「关系」「传递」「流程」「如何」「被谁调用」「引用了」等 → 触发 graphify query。 - **索引位置**：`D:\xxxx\graphify-out\`（含 `graph.json` / `GRAPH_REPORT.md` 等预生成产物）。 - **使用方式（先 graphify → 再针对性 Read）**： - `graphify query "<question>"` — 代码库或架构问题，BFS 取相关子图 - `graphify path "<A>" "<B>"` — 两符号间依赖路径（查调用/引用链首选） - `graphify explain "<concept>"` — 与概念相关的节点 - 默认 BFS、`--budget` 控制 token 上限；查调用链时优先 path 而非 query - **TodoWrite 节点（强制）**：代码探索类任务的 TodoWrite 第一项必须是「graphify 查询 xxx」，完成前禁止后续 Read/Grep。违反则视为跳过 graphify。 - **省 token 原则（硬性）**： - graphify 返回的节点 `source_location` 已含文件路径与行号 → 据此精确定位后再 Read，禁止整文件盲读多文件并行 - 禁止「并行起 N 个 Grep/Glob 找线索」式盲扫，除非 graphify 已查过且节点不足 - 禁止用「文件已知」「上次查过」「查询窄 grep 够用」作为跳过 graphify 的理由 - **子代理**：spawn 涉及代码探索的子代理时，须在 prompt 中显式带上本节规则，要求子代理也先走 graphify。 - **wiki 导航**：若 `graphify-out/wiki/index.md` 存在，优先通过它导航，而非直接读原始文件。 - **架构总览**：`graphify-out/GRAPH_REPORT.md` 仅在 query/path/explain 信息不足时，用于宽泛架构回顾。 - **改代码后**：修改代码文件后运行 `graphify update .` 保持索引最新（AST-only，无 API 成本）。 - **UI 语言**：graphify 调用同样遵循第 1 节简体中文 UI 要求（工具 `description`、进度说明、结果摘要等）。 - **窄查询不可跳过（反越狱·强化）**：即使任务看似「具体路由路径 + 具体文本字面量」「具体组件名 + 具体行号」「grep 一搜即中」等窄查询场景，**仍须先走 graphify query/path 至少一次**，再用 Read 精确定位行号。 - 禁止以「路由已知」「文件已知」「上次查过」「grep 够用」「只改一个 label/常量」「字面量搜索即中」等任何理由跳过 graphify。 - 窄查询不满足下述降级条件的第 2、3 项（graphify 节点 `source_location` 通常已能定位文件/行号）。 - 违反则视为越狱，本轮按未完成处理，必须补跑 graphify 后再继续后续步骤。 - **降级条件（需同时满足全部三项才允许降级到 Grep/Read/Agent）**： 1. 已用 graphify query/path/explain 查过至少一次 2. 查询返回的节点 `source_location` 不足以定位目标文件/行号 3. 目标是单文件内具体行号修改，或索引未覆盖该路径 - **索引失效处理**：graphify 索引不存在、疑似过期（大规模重构后未重建）时，优先运行 `graphify update .` 或重建索引；**不以此为理由跳过 graphify 改走 Grep**。 - **补充规则**：`.cursor/rules/graphify.mdc` 为 graphify 探索的附加约束；与本节冲突时以本节为准。 ## 4. 方法注释规范 - **适用范围**：新增方法、修改既有方法（含签名调整或实现改写）时适用；纯格式化、仅改一行字面量等无逻辑变化的小改可豁免。 - **方法注释**：方法上方写注释说明用途/职责；Java 用 Javadoc（`/** ... */`），其他语言用对应文档注释格式。注释用简体中文。 - **参数注释**：每个参数逐个标注说明；Java 用 `@param`，禁止省略或合并。 - **返回值注释**：有返回值时用 `@return` 说明（`void` 方法免）；返回 `Boolean`/可选值时说明 `null`/`false` 语义。 - **异常注释**：受检异常或对调用方有意义的异常用 `@throws` 标注。 - **方法内逻辑注释**：新增或修改方法时，方法体内的逻辑代码须加注释说明意图（分支条件、循环目的、关键赋值、副作用等）。注释用简体中文，写在被说明代码上方或行尾；自解释的单行赋值、简单 getter/setter 调用等可豁免。 - 分支（`if`/`switch`/三元）注释条件意图，而非复述代码。 - 循环注释遍历对象与处理目的。 - 关键业务赋值、状态流转、外部调用（RPC/DB/消息）说明原因或预期效果。 - **示例**： ```java /** * 查询合同整合变更记录，仅虚拟合同直接返回空列表。 * * @param contractId 合同 ID，不可为 null * @param onlyApproved 是否只取审批通过记录 * @return 变更记录列表，无数据返回空列表 * @throws IllegalArgumentException contractId 为空时抛出 */ public List<ChangeVO> listChanges(Long contractId, Boolean onlyApproved) { if (contractId == null) { // 参数校验：合同 ID 必填，空值直接拒绝 throw new IllegalArgumentException("contractId 不能为空"); } // 仅查审批通过记录时，追加状态过滤条件 LambdaQueryWrapper<ChangeVO> wrapper = Wrappers.lambdaQuery() .eq(ChangeVO::getContractId, contractId); if (Boolean.TRUE.equals(onlyApproved)) { wrapper.eq(ChangeVO::getApprovalStatus, 2); // 2 表示已审批通过 } // 虚拟合同无审批流，提前返回空列表 if (isVirtualContract(contractId)) { return Collections.emptyList(); } return baseMapper.selectList(wrapper); } ``` - **不做**：不要求给 getter/setter、toString、Lombok 生成方法、单行委托方法补注释。 ## 5. 改代码先理清、优先复用 - **强制级**：本节为硬约束，违反即视为未完成。 - **先理清再动手**：前后端任何逻辑（数据流、调用链、状态流转、权限/审批分支、字段语义、定时任务触发时机等）不清楚时，**禁止猜测、禁止臆断、禁止顺手改**。必须通过以下途径之一确认后再改： - 优先用 graphify 查关系、定位代码； - 针对性 Read 相关源码、Mapper XML、配置； - 仍不明确时向用户提问，附已知线索与疑问点。 - **不准顺手改**：用户本次未要求、且与当前任务无直接因果的代码，**禁止一并修改**（含「顺手优化」「顺手补日志」等）。发现的可疑/可优化点以备注形式提示用户，由用户决定是否处理。 - **有可用代码优先复用**：动手前先检索仓库内是否已有可复用的工具方法、Service、Mapper、常量、枚举、DTO、前端组件等。**禁止重复造轮子**： - 同一逻辑已存在于工具类/公共方法中 → 直接调用，禁止另写一份。 - 同一查询已存在于 Mapper XML / MyBatis-Plus wrapper → 复用或扩展，禁止新增重复 SQL。 - 同一前端交互已存在组件/hook → 复用，禁止复制粘贴平行实现。 - 复用前须确认其行为与当前需求一致；不一致时优先扩展而非新建。 - **改前自检清单**（任一为否则不得动手）： 1. 我能否用一句话说清这段逻辑的输入、处理、输出与触发时机？ 2. 我是否已读过相关源码而非凭印象？ 3. 本次改动是否在用户明确要求范围内？ 4. 仓库内是否已有可复用实现？若有，是否已选择复用而非重写？ ## 6. 需求定义与执行计划（强制） - **强制级**：本节为硬约束，违反即视为未完成。 - **开发模式**：**SDD（规格驱动）+ TDD（测试驱动）** 双强制——先规格后计划，先测试后实现。 - **适用范围**：所有新增代码和修改代码的任务（含后端、前端、联调改动）；纯文档/规则/注释改动、用户当轮明确说「跳过」时可豁免。 - **第一步：OpenSpec 定义需求（SDD）**：动手写代码前，必须先用 **openspec** skill 把需求落成变更提案（proposal + specs + tasks），明确验收点；未定义需求**禁止直接改代码**。 - **第二步：writing-plans 写执行计划**：需求定义后，用 **writing-plans** skill（superpowers 系列）产出执行计划；计划须基于 OpenSpec 的 tasks 展开。 - **第三步：TDD 测试驱动实现**：每个任务的实现顺序必须为「红 → 绿 → 重构」： 1. **红**：先写针对当前任务验收断言的测试（后端 JUnit，放对应模块 `src/test`），运行并确认失败； 2. **绿**：写最少实现让该测试通过；测试通过即验收点达成； 3. **重构**：在不破坏测试的前提下整理实现，改完重跑测试。 - **测试运行范围**：TDD 只跑当前任务相关测试类（`mvn -pl <module> -am test -Dtest=<TestClass>`），不做全量测试——与第 2 节「不默认全量测试」不冲突，也不豁免第 2 节的交付前编译。 - **前端 TDD 降级**：前端若无可用测试设施，任务中的验收断言优先写**明确的手动验证步骤**；仅当用户当轮主动要求 Playwright / E2E 脚本时，才可用 Playwright 替代（见第 11 节）。无论何种方式，必须在任务里写清验证步骤，禁止空泛的「测一下」。 - **任务必须拆分**： - 一个任务只做一件事、一个验收点；**禁止把全部功能塞进单个任务一次完成**。 - 按可独立验证的粒度拆分（如：一个接口/一个页面交互/一条 SQL/一组表单字段校验）。 - 每个任务须写明：涉及文件、改动内容、验收断言（如何算完成）。 - 任务间有依赖时明确先后顺序；无依赖的尽量并行。 - **执行节奏**：按计划逐任务执行，每完成一个任务先验证其验收点再进入下一个；计划外的必要改动先回到 OpenSpec 更新需求，再继续。 - **例外**：用户当轮明确说「不用 openspec / 直接改」「简单改一下不用拆任务」时，以当轮指令为准。 ## 7. 常量规范（魔术值收敛，强制） - **适用范围**：新增或修改后端代码时，凡引入**有业务语义的字面量**（如是否标志 0/1、状态码、类型码、审批状态值等），一律定义或复用常量，**禁止在业务代码中内联书写**。 - **常量位置**：XZ 模块的常量统一放 `XzConstant`：`XzConstant.java`；其他模块有各自常量类的，放对应常量类，不新建平行的常量文件。 - **写法要求**（沿用 `XzConstant` 类内既有规范）： - `public static final` + UPPER_SNAKE_CASE 命名； - 放到对应功能分组注释下（如 `// ==================== 合同常量 ====================`）； - 每个常量带完整 Javadoc 说明业务含义与取值。 - **示例**（是否虚拟合同，1=虚拟、0=非虚拟）： ```java // ==================== 合同常量 ==================== /** * 虚拟合同标志-虚拟（跳过 BPM 审批） */ public static final Integer IS_VIRTUAL_YES = 1; /** * 虚拟合同标志-非虚拟（走 BPM 审批） */ public static final Integer IS_VIRTUAL_NO = 0; ``` - **存量代码**：现存散落的魔术值（如 `getIsVirtual()` 与 0/1 的比较）**不要求本轮重构**；仅当用户明确要求统一替换时才批量处理，替换时同样优先复用常量而非另写。 - **SQL/Mapper XML**：XML 中无法引用 Java 常量时保持原样，但须在该 SQL 旁注释说明取值含义（如 `<!-- 1=虚拟合同 0=非虚拟 -->`）。 ## 9. Java 环境：仅 JDK 8 - 本机标准 JDK：`D:\Program Files\Java\jdk1.8.0_261`（`JAVA_HOME` / `Path` 应指向此处）。 - **禁止**安装、下载、配置或切换到 JDK 17（含 `Microsoft.OpenJDK.17`、`winget install` OpenJDK 17、Adoptium/Temurin 17 等）。 - **禁止**把 `JAVA_HOME` 或 `Path` 改成 `C:\Program Files\Microsoft\jdk-17*` 或任何 JDK 17 路径。 - 若编译/运行缺 Java：先检查现有 JDK 8 是否可用；不要擅自安装新 JDK。确需更高版本时必须先征得用户明确同意。 ## 10. E2E 默认账号 - Playwright / MCP 页面测试默认账号：`xxxx` / `xxxx@..` - 实现落点：`playwright-demo/tests/helpers/auth.js`（可用 `LOGIN_USERNAME` / `LOGIN_PASSWORD` 覆盖） - 会话文件：`playwright-demo/tests/.auth/user.json`；失效时跑 `auth.setup` 重新登录 - 不要默认改回 `xxxx1` - **启用前提**：本节仅在第 11 节允许启用 Playwright / E2E 时适用；不得因存在默认账号而主动开跑 E2E。 ## 11. Playwright 启用约束（强制） - **强制级**：本节为硬约束，违反即视为未完成。 - **默认关闭**：用户当轮**未主动要求** Playwright / E2E / 页面自动化脚本时，**禁止**启用相关能力，包括但不限于： - 调用 `fast-playwright-e2e` 或其他 Playwright 相关 skill - 新建、修改或运行 `playwright-demo` 下的脚本 / spec - 为「验收 / 自测 / 回归」主动提议或执行 Playwright 方案 - 将 Playwright 写入计划、任务或 OpenSpec 验收步骤（用户未要求时） - **何时可启用**：仅当用户当轮明确提出，例如「写 Playwright」「跑 E2E」「用 playwright-demo 测一下」「页面自动化验证」等。 - **替代验证**：未启用时，前端/联调验收用手动步骤、接口/单元测试或用户指定的其他方式；不得以「更稳妥」「顺手验证」为由擅自启用。 - **与第 6 节关系**：第 6 节「前端 TDD 降级」不得被解读为默认可选 Playwright；默认为手动验证步骤。 - **与第 10 节关系**：默认账号仅供**已获准启用**的 Playwright / MCP 页面测试使用。 ## 12. 使用达梦数据库（强制） - **强制级**：本节为硬约束，违反即视为未完成。 - **默认数据库**：本仓库业务数据统一使用**达梦数据库（DM）**；Agent 编写、修改、评审与 SQL 相关的代码时，一律按达梦语法与兼容性处理。 - **禁止擅自换库**：未经用户当轮明确同意，**禁止**将数据源、方言、驱动或建表/迁移脚本改为 MySQL、Oracle、PostgreSQL、H2 等其他数据库（含「仅本地测试换库」）。 - **SQL / Mapper 要求**： - 新增或修改 Mapper XML、原生 SQL、DDL/DML 时，须使用达梦可执行的写法； - 避免依赖其他库的专有函数、分页语法、自增列写法、引号/大小写规则等；若需函数或分页，优先复用仓库内既有达梦写法； - 不确定某写法是否达梦兼容时，先查仓库内同类 SQL / 配置，仍不明确则向用户确认，**禁止臆造**。 - **连接与配置**：数据源驱动、JDBC URL、方言（dialect）等配置须指向达梦；新增配置项时对齐现有达梦配置风格，不另起平行的他库配置。 - **与第 7 / 13 节关系**：库名、schema、连接串等不得在业务代码中硬编码（见第 13 节）；业务状态等魔术值仍按第 7 节收敛到常量。 ## 13. 禁止硬编码（强制） - **强制级**：本节为硬约束，违反即视为未完成。 - **适用范围**：新增或修改的前后端代码、配置引用、脚本；纯文档 / 规则说明可豁免。 - **禁止硬编码的内容**（包括但不限于）： - 环境相关：主机、IP、端口、完整 URL、JDBC 连接串、文件绝对路径、服务地址； - 密钥与凭证：密码、Token、AccessKey、证书口令、第三方 AppSecret 等； - 可配置业务参数：超时时间、开关阈值、环境标识、租户/组织固定 ID（除非该 ID 已是项目约定常量且落在常量类中）； - 有业务语义的字面量（状态码、类型码、是否标志等）——须按第 7 节收敛到常量类，**禁止在业务逻辑中内联书写**。 - **正确做法**： - 配置类值：放入对应配置文件 / 配置中心 / 环境变量，代码通过已有配置读取方式获取； - 业务语义字面量：定义或复用常量（见第 7 节 `XzConstant` 等）； - 密钥凭证：不得写入源码或提交到仓库；使用既有安全配置机制。 - **允许的例外**（须克制使用）： - 无业务语义的技术字面量（如循环起点 `0`、空字符串 `""`、集合初始容量等）； - 单元测试中的夹具数据（仍禁止把真实生产密码/连接串写进测试）； - 用户当轮明确要求「临时写死」且仅限局部、并在注释中标明待配置化。 - **存量代码**：历史硬编码**不要求本轮批量清理**；仅当用户明确要求，或本次改动触及该处时，一并改为配置/常量。 - **与第 7 节关系**：第 7 节专指业务魔术值 → 常量；本节覆盖更广的硬编码（地址、密钥、可配置参数等）。两节同时适用时须一并遵守。 ## 14. 代理与 subagent 启用约束（强制） - **强制级**：本节为硬约束，违反即视为未完成。 - **默认关闭**：用户当轮**未用明确措辞授权**开启代理（Agent / Task / 并行代理等）或 subagent（子代理）时，**禁止**自动开启，包括但不限于： - 调用 `Task`（UI 中常显示为带 **Auto** 的子任务）、`dispatching-parallel-agents`、`subagent-driven-development` 等会拉起子代理 / 并行代理的能力； - spawn 任意子代理类型：`explore` / `generalPurpose` / `code-simplifier` / `ci-investigator` / `best-of-n-runner` 及其他； - 为「加快探索」「并行调研」「自动拆分干活」「技能工作流下一步」等理由主动委派； - 在计划、任务或 OpenSpec 步骤中默认写入「用 subagent / Task 执行」类安排（用户未授权时）。 - **何时可启用**：仅当用户当轮用**明确授权措辞**提出，例如「开代理」「用 subagent」「并行子代理」「派几个 agent 去查」「用 Task 跑」等。仅提到业务动作（如「简化这段代码」「查一下」「修 bug」）**不算**授权。 - **斜杠命令 / Skill ≠ 授权开代理**：调用 `/code-simplifier`、`code-simplifier` skill、或其他 skill / 斜杠命令，只表示要完成该能力对应的**工作本身**；**不得**因此自动 `Task` / spawn subagent。须在**当前主会话**内直接完成；技能文案若写「交给 code-simplifier 子代理」，以本节为准，忽略该委派步骤。 - **禁止借口**：不得以「更高效」「任务复杂」「技能建议默认用」「using-superpowers 要求」「子代理类型刚好叫 code-simplifier」为由擅自开启。 - **主会话自办**：未获准时，由当前主会话直接完成探索、实现与验证，不委派子代理。 - **生效说明**：规则以本文件为准；**新开对话**或确保本会话已加载最新 `AGENTS.md` 后生效。旧会话若仍自动开 Auto/Task，应停止委派并改为主会话执行。 ## 8. 维护说明 - 本文件为仓库 Agent 规则的**唯一权威来源**。 - `.cursor/rules/` 仅保留指针规则（`agents-pointer.mdc`）及 `graphify.mdc` 等补充规则；规则正文不重复维护，若冲突以本文件为准。 - 已从 `.cursor/rules/` 移除、并入本文件的旧规则备份于 `.cursor/rules/_backup/`。 - `updated` 字段记录最近修订日期，仅在本文件内容变更时更新。
