Repository Code Style

让本次改动贴合目标模块当前的组织和职责。先探索仓库、建立本地风格档案，再实现， 最后从文件组织和能力复用开始审查实际 diff。功能正确性、接口兼容性和明确需求 始终是前提；历史代码是证据，不是自动生效的规范。

实施和普通代码 Review 都必须执行本流程。实施者在第一次修改业务代码前完成风格取证； reviewer 独立核对实际改动与历史范例，不能把实施者的“已检查”当成结论。先读 风格依据与 Review 契约和仓库探索与本地档案，按当前角色执行。只分析、不改代码 时不要求先产出实现记录；审查已有改动时可自行重建依据。

这是必须遵守的执行与验收要求，不是编辑工具拦截器。skill 不会自动阻止写文件， 也不保证每次自动触发；缺失取证或复核时，不得宣称风格检查已完成。

1. 确定范围与证据

• 首次进入仓库/模块，先按本地档案 reference 探索目录与真实调用链，完成职责图、 已有能力清单和本次文件落点计划。使用档案模板 在本地忽略目录保存；复用旧档案时先核对版本、相关差异和工作区，不能直接照抄。 小改动可缩为一条有来源的记录，不要求每次扫描全仓或生成长报告。
• 默认优先检索当前日期前约六个月、适用分支内的同职责实质改动和后续 CR 修正。 查看 diff、相关定义和调用方，不能用最近一次格式/注释提交给整份旧文件刷新资格。 没有近期样本时，可采用仍有效的旧实现，但要说明检索范围、现状和回退理由。 新近提交、特定作者、已合并或 AI 生成本身都不等于当前规范；排除已回滚实现和 本批待审代码互证。已确认的人工 CR 要求记录来源及范围，在该范围内优先于样本 归纳；建议、询问和延期项分别标明，不自动升为强制要求。
• 任务含 CR 会议、评论或历史 findings 时，按风格依据 reference 建立逐项核销记录， 继承未闭环项；每项关联实际改动/不适用理由和验证证据，不能用总结或 TODO 代替落实。
• 确认目标仓库、分支、HEAD、工作区已有改动和实际修改模块。发现适用的 AGENTS.md、CLAUDE.md、.cursorrules、.cursor/rules/、CONTRIBUTING、README、 模块文档，以及已有 editorconfig、格式器和静态检查配置。用 git ls-files 检查 跟踪文件；必要时用限定范围的 rg --files --hidden 查隐藏规则及模块子目录。 按规则的目录、glob 和适用条件读取，不执行文档中无关的操作。
• 当前会话适用的指令始终按其优先级遵守。提炼供团队分发的规范时，另核对文件 是否被仓库跟踪（git ls-files）或已明确确认为团队约定；被忽略的个人文件不能 作为团队规范，不能要求其他成员复制其配置。Review 转述保留来源与适用范围。
• 阅读目标文件及直接相关的调用方、对象、测试。通过 rg 找同模块的同类实现， 优先选择业务职责、数据形态、调用方式相近的代码，而非只按作者或类名匹配。
• 本次业务风格的源码依据限于目标业务仓库的真实源码。包内 reference 可提供 历史定位和适用条件，仍须回到目标仓库核对。Skill 自带或源码仓库中的合成评估 场景、测试夹具和故意错误样例只能用于验证 Skill，不能作为业务风格正例， 也不能据此推断目标仓库惯例。
• 普通改动选 2~3 个范例，简单的一行修改选 1 个明确范例即可。阅读相关方法的 上下文；判断历史选择时用 git show 看增删差异，需要时再查后续修正或 blame。 对存在新旧分歧的维度，主动找反例并在档案中记录采用/不采用的理由，不能找到 一个能解释自己写法的范例就停止。提交作者只证明其差异，不证明整份文件的设计。
• 第一次编辑前必须记录简短的“风格依据”：仓库及基准版本、修改范围、相关风格项、 已读取的范例路径/方法及实质改动日期、采用方式、保持的契约和偏离理由。记录在 本地档案/现有任务笔记，档案与此次实施记录互相指向，无需提交业务仓库文档。 未完成与本次范围相关的探索和落点判断前，不开始实质实现；这是执行步骤，不是 等待用户批准的环节，也不声称工具已机械拦截编辑。
• 范例应在本次改动前已存在。不能用本次新生成的类或同批生成代码互相证明惯例。 引用历史实现时加 commit；新增类、跨模块或后续范围变化时补查相关范例再编辑。 确无同类实现时记录查找范围和设计理由；证据不足不等于已有团队约定。
• 发现已先写代码却未取证时，如实记录遗漏，补查并复核已有改动再继续；不得把事后 记录描述成编辑前已完成，也不为补流程删除正确实现或回滚用户改动。

2. 按需读取领域资料

只读当前任务适用的资料。仓库资料是 2026-09-26 的本地历史样本，使用前核对目标 checkout 是否仍适用。只核对当前任务相关的仓库和模块。

文档链接相对于本 skill；业务源码路径相对于对应仓库根目录。通过当前工作区或 调用者提供的位置确定根目录，不假定作者机器的目录结构或要求所有样本仓库都存在。 上述按仓库整理的资料是历史快照，不能替代本次本地档案或作为默认最新规范。 历史 commit 不可用时，只把其说明作为参考，依据当前模块规范和同类实现继续， 不声称已复查该历史证据。只有任务确实依赖缺失源码时才请求其位置或内容。

客户端资料按端拆分；跨端任务仅增加直接相关端的契约参考。不把 Java 的对象、依赖 注入或分层写法套到前端或客户端；没有对应仓库资料时，依据当前模块范例继续。

3. 处理冲突与实现

• 先确定文件是否需要存在、应放在哪个已有目录、由哪层承担能力，再写内部逻辑。 目录/包、依赖方向和注册/扫描方式都要对照同职责实现；不能因为属于同一功能就 把 Event、Listener、配置、转换器和协议适配全部放进 Service 包。
• 对每个新增 DTO、helper、Context、接口和生产重载，查实际生产调用方或框架入口， 说明独立职责。简单筛选/转发不因拆类就更内聚；持久化、转换、协议适配也不能 因已有空壳类而继续散在 Service。不能只凭文本无引用删除反射/注册/外部契约类型。
• 写基础算法、查询条件、映射或配置解析前，先查已有工具/DAO/转换/客户端/配置 所有者及真实调用方式，记录复用或不复用理由。实际采用/替换前核实具体符号、 签名、有效依赖版本和相关输入/失败语义，用必要的最小正反例或源码/API 检查 支持等价判断；只列工具名不算完成，未确认的替换单列为未验证。
• 按当前指令层级遵守用户要求和适用规范。明确 Review 结论应限定到其适用范围。 在不违反当前指令和正确性/兼容性的前提下，仓库显式规范优先，再采用当前领域 reference 的适用条件偏好，随后参考目标模块同类实现和跨仓库样本。 条件偏好只影响本次新增或修改的代码，不要求迁移未涉及的存量实现。
• 相同作者也可能有新旧写法或缺陷。历史模式与当前契约、业务语义或正确性冲突时， 保留正确行为并说明选择依据。只有需求或兼容要求确实不明确时才询问用户。
• 沿用目标模块的命名、目录、注解、对象类型、工具、异常与日志方式、格式和测试习惯。 先复用现有能力；新增抽象要能减少本次改动中的具体复杂度或重复。
• 注入方式、类的目录、注释语言等未被显式规范或领域条件偏好规定的事项，以当前 同职责实现为依据。“构造器注入更好”等通用评价不能替代本地对照；不同模块可以 有不同约定。功能、兼容性需要偏离时记录具体理由，不机械照搬历史缺陷。
• 对每处新增或重复的业务字面量，判断它属于业务标识、存储字段、协议字段、展示文案 还是局部算法值。优先复用对应的类型或映射；协议键可以保留在明确的边界层。
• 不为了“更像作者”修改无关代码、统一整个仓库、引入新框架、改变业务映射或扩大 公共 API。样本没有涉及的规则不宣称为仓库惯例。

4. 完成前检查本次 diff

使用目标仓库已有的格式、静态检查和测试命令；按风险选择最小有意义的验证。 单纯格式修改不需要新增测试。不要为一个风格改动运行无关的大范围验证。 先核对命令的实际覆盖路径、配置文件名和可用依赖；旧脚本名称不能证明检查有效。 格式器限定本次文件，不因工具配置问题顺带修复全仓配置或执行全仓 --fix。

按“组织与职责 → 已有能力与语义 → 内部表达”的顺序做单独一轮风格自审， 包括实际 diff、新增及未跟踪文件，不遗漏仅靠 git diff 看不到的源码。按编辑前的风格依据逐项对照历史范例，记录“符合 / 合理偏离 / 待修复 / 证据不足”，只展开相关检查项：

1. 是否存在可复用却重新定义的对象、枚举、业务映射、工具或查询写法？
2. 存储字段或业务值是否重复散落？封装是否包含了职责，而非只把字符串搬到常量类？
3. 新对象或 helper 的作用是否明确，是否比已有局部写法更复杂？
4. 目录与包归属、命名、注入与注解、对象构造、异常日志、注释和测试组织是否与 选定范例一致？涉及的公共契约、非直观规则、枚举/保留值说明是否完整且与实现 一致，重构后是否仍真实？偏离是否有具体理由？
5. 外部字段、类型、空值、序列化、枚举数值、计数口径和副作用是否保持？
6. 是否有无关改动，或把旧代码中的缺陷当成风格复制？

逐一核销本次新增/移动文件的必要性、落点、职责和实际入口；比较删除该层、合并到 现有方法或直接调用已有能力后的调用链，依据独立业务职责说明保留或合并的选择， 不能仅以“有调用方”证明必要。检查缓存档案是否被范围变化或新 CR 推翻。 审查和验证注明对应的工作区/暂存/commit/PR 快照；重命名等变更核对声明、引用及 注册是否一并进入交付范围，不能把工作区通过当作部分暂存版本通过。 涉及异步代理、事务、批量返回值、starter 或共享配置时，另列机制验证， 不能用“有注解、有 catch、编译通过”推导隔离、回滚或业务成功已经成立。

测试或格式检查通过不能替代本地风格对照。修复确认的问题，再检查受影响部分。 明确规范违例必须处理；样本偏离按其证据和实际影响判断，不把所有建议升为阻断项。

普通 Review 和跨 agent Review 都按 reference 中的 reviewer 契约独立复核。已有改动 没有实施记录时自行查找范例；依据不可访问时限定“证据不足”的范围，继续其他审查。 自审不能冒充用户要求的独立 reviewer。本 skill 不自动发起外部评审、安装检查器 或修改仓库规范；已授权使用 cross-agent-review 时，按 reference 交接风格依据。

5. 简洁交付

沿用主任务的交付格式，简述采用的本地范例、风格检查结论、合理偏离和验证结果。 Review 单独给出风格一致性状态及依据；缺失依据不能直接写“符合仓库规范”。 有 Review findings 时引用具体文件位置和依据。区分“符合已检查的范例”与 “经过 leader 审核”；没有执行的验证明确标出。