/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 §53. 不确定先预研第三方/达梦兼容/性能等未知点先走[条件]技术预研预研结论须落进设计文档与实施计划4. 前后端先对齐契约同时改接口与页面时先完成[条件]契约对齐再定实施计划5. 一次只做一个验收点当前任务未验证通过不得开下一个任务实现6. 变更先改规格范围/验收/方案有变先改 OpenSpec 与本任务 TODO 文件再改代码7. 验绿再精简功能验证通过后必须做代码精简精简后必须重跑相关验证8. 完成前有证据未跑相关测试/编译/手测按计划不得宣称完成或勾选完成9. 影响面由 Agent 产出最晚在「设计文档」步写入本任务 TODO 文件影响功能 / 前端路由 / 后端接口 URL进入 TDD 前不得缺失实现中变更须同步回写10. 「验证」步必须给用户可测清单要测功能 固定格式 前端|后端 对照表格式定义见【TODO.md】15c11. TDD 前用户确认闸门进入 TDD 开发前必须暂停把方案要点改哪些文件、实现思路、各任务验收点、影响面清单提交用户用户明确回复「继续」后才允许开始 TDD 开发未获确认前禁止写任何测试或业务代码闸门通过后若方案有实质变更须先更新 OpenSpec 与本任务 TODO 文件并重新提交用户确认方可继续 TDD12. 改代码后更新图谱本轮修改过代码文件的完成前须运行 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- SDDproposal / 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]并写 25 行实现笔记6. 笔记重点写「为什么这样做」可附关键风险或依据禁止空泛优缺点对比小作文7. 条件步不适用时写- [x] 跳过原因…不得长期留空 [ ]8. 「代码精简」不是条件步默认不得跳过例外仅见【代码精简】9. 范围或验收变更时先改 OpenSpec 与本任务 TODO 文件再改代码10. 未完成步骤禁止提前勾选11. 【当轮任务】未填清的项先在「需求澄清」步补问并写进本任务 TODO 文件笔记再继续后续步骤12. TODO 文件中须能看出【减少返工】检查点至少在「验收冻结」「设计/复用核对」「验证」笔记里各写一句依据13. 「设计文档」步由 Agent 产出影响面清单勿让用户填笔记格式固定为- 影响功能…- 前端路由…无前端改动写「无」- 后端接口 URL…无后端改动写「无」须写清方法路径如 GET /api/...- 流程图mermaid 源码须同时内联到本 TODO 文件影响面清单下方和 design.md两处保持一致、修改时同步单点改写「无」14. 「验证」步必须同时完成a) 相关测试/编译按计划细则见 AGENTS.mdb) 在对话回复和 TODO 文件验证笔记中明确列出「用户需要测试的功能」c) 紧接着输出手测对照表格式见第 15 条无对应侧写「无」d) 按该表做回归核对并在笔记写明已核对项15. 手测对照表固定格式唯一权威定义可多行前端|后端功能名 路由|METHOD /api/...示例前端|后端合同列表 /xz/contract/list|GET /api/xz/contract/list合同详情 /xz/contract/detail|GET /api/xz/contract/detail16. 「代码精简」步笔记须写明已调用 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 §31. 凡本轮需要代码探索或改代码工具调用的第一项必须是 graphifyquery 或 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违反视为未完成方法须加注释改代码先理清、禁止顺手改、优先复用改代码须 SDDOpenSpec writing-plans 拆任务 TDD魔术值收敛到 XzConstantJDK 8E2E 默认账号 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 ListChangeVO listChanges(Long contractId, Boolean onlyApproved) { if (contractId null) { // 参数校验合同 ID 必填空值直接拒绝 throw new IllegalArgumentException(contractId 不能为空); } // 仅查审批通过记录时追加状态过滤条件 LambdaQueryWrapperChangeVO 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** skillsuperpowers 系列产出执行计划计划须基于 OpenSpec 的 tasks 展开。 - **第三步TDD 测试驱动实现**每个任务的实现顺序必须为「红 → 绿 → 重构」 1. **红**先写针对当前任务验收断言的测试后端 JUnit放对应模块 src/test运行并确认失败 2. **绿**写最少实现让该测试通过测试通过即验收点达成 3. **重构**在不破坏测试的前提下整理实现改完重跑测试。 - **测试运行范围**TDD 只跑当前任务相关测试类mvn -pl module -am test -DtestTestClass不做全量测试——与第 2 节「不默认全量测试」不冲突也不豁免第 2 节的交付前编译。 - **前端 TDD 降级**前端若无可用测试设施任务中的验收断言优先写**明确的手动验证步骤**仅当用户当轮主动要求 Playwright / E2E 脚本时才可用 Playwright 替代见第 11 节。无论何种方式必须在任务里写清验证步骤禁止空泛的「测一下」。 - **任务必须拆分** - 一个任务只做一件事、一个验收点**禁止把全部功能塞进单个任务一次完成**。 - 按可独立验证的粒度拆分如一个接口/一个页面交互/一条 SQL/一组表单字段校验。 - 每个任务须写明涉及文件、改动内容、验收断言如何算完成。 - 任务间有依赖时明确先后顺序无依赖的尽量并行。 - **执行节奏**按计划逐任务执行每完成一个任务先验证其验收点再进入下一个计划外的必要改动先回到 OpenSpec 更新需求再继续。 - **例外**用户当轮明确说「不用 openspec / 直接改」「简单改一下不用拆任务」时以当轮指令为准。 ## 7. 常量规范魔术值收敛强制 - **适用范围**新增或修改后端代码时凡引入**有业务语义的字面量**如是否标志 0/1、状态码、类型码、审批状态值等一律定义或复用常量**禁止在业务代码中内联书写**。 - **常量位置**XZ 模块的常量统一放 XzConstantXzConstant.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 - 本机标准 JDKD:\Program Files\Java\jdk1.8.0_261JAVA_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子代理时**禁止**自动开启包括但不限于 - 调用 TaskUI 中常显示为带 **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 字段记录最近修订日期仅在本文件内容变更时更新。