Add architecture review skill and readability guidance

2026-09-18 15:19:25 +08:00
parent 9901bca1ec
commit 8d7aa3f2ec
5 changed files with 119 additions and 21 deletions
@@ -12,7 +12,7 @@ description: 仅用户指定 execute-plan 时启用；实施已批准计划，
 ## 读取与核对

 1. 完整读取用户指定计划；路径不明则询问。从计划定位或 `.agent/MEMORY.md` 确定根目录并读 `CONTEXT.md`，再按任务核实代码、测试与项目约束；架构、数据、部署资料仅在涉及对应改动时读取，不扫描历史计划，避免无关的全仓库扫描。定位冲突或系统不符先澄清，不猜根目录；无 CONTEXT 时依靠计划与代码。
-2. 核对计划批准依据、目标、范围与验收。基线变化先调查影响，无关更新不阻塞；关键缺口、未批准或实质冲突先澄清。已批准的规则迁移按计划执行，不因仍有旧规则重复确认。
+2. 核对计划批准依据、目标、范围与验收，继承本次已批准的优化和按模块、维度跳过检查的决定。基线变化先调查影响，无关更新不阻塞；关键缺口、未批准或实质冲突先澄清。已批准的规则迁移按计划执行，不因仍有旧规则重复确认。
 3. 记录仓库身份、分支、HEAD（或无提交）及暂存/未暂存/未跟踪状态，足以区分用户已有修改。保护用户内容；重叠且不能隔离时先解决，不回退或混合提交。

 宿主禁止实施时遵从限制；新会话是使用约定，不能假称清空了上下文。
@@ -42,12 +42,15 @@ Markdown 正文中代码、命令和多行配置用带语言标记的围栏代
 ## 实施边界

 - 每项改动对应批准任务或验收；优先复用现有能力，自主决定具体代码及内部组织，不要求计划提供详细代码或逐字照抄算法示例。
- 在最小改动范围内遵循单一职责、开闭原则，按需应用设计模式；避免功能模块耦合及通用架构能力依赖业务规则，降低扩展与审查复杂度，不为模式引入无必要抽象。
- 不为缩小 diff 堆叠旧逻辑。发现本次目标相关且计划未覆盖的复用提取或模块解耦机会时，说明代码依据、收益、成本和影响范围，向用户确认；确认纳入后按范围变更流程更新 plan.md 再实施，不擅自重构或重复确认已批准方案。
+- **Codex 可读性永远摆在第一位**：业务入口容易定位，职责与接口契约清晰，调用和数据流容易追踪；不以最少行数、最少文件或最小 diff 代替可读性，不为缩小改动堆叠旧逻辑。
+- 围绕业务职责模块化，同一业务规则有明确归属，跨模块调用方只依赖公开接口，不感知内部实现，保持高内聚、低耦合；遵循单一职责、开闭原则，通用架构能力不绑定具体业务。区分合理协作与规则散落，不将整个业务链路塞进一个模块。接受模块化初期一定程度的过度工程化，不因只有一个实现就否定接口；新增结构须有清晰职责和可读性、隔离或演进收益，仍受批准范围约束。
+- 每个功能或优化点开始实施前，对相关模块及调用、依赖关系局部检查 **Codex 可读性、循环依赖、复杂度、架构健康度**。健康度按上述职责与接口边界判断，循环依赖须有实际闭环依据，复杂度关注理解和修改成本；复用仍有效的规划证据，先排除本次已跳过的组合，不机械重复全仓扫描，也不自动调用其他 skill。
+- 发现与本次目标相关且计划未覆盖的优化空间时，先说明代码证据、沿用现状继续开发的影响、优化方向、收益、成本及范围，再确认是否本次处理。确认纳入后按范围变更流程更新 `plan.md` 再实施；已批准的优化不重复确认，未确认的不擅自实施，无问题时直接推进。
+- 用户确认本次不优化时，将本次任务、适用模块、跳过的检查维度和确认依据记入计划、执行记录及已有的 `current.md`；仅记录拒绝决定不扩大实施范围，也不要求重新批准未变的方案。此任务不再检查或追问该“模块 × 维度”，其他组合继续；范围不明时澄清，不扩大解释。恢复会话时继承，新任务默认重置，本任务仅用户明确调整才恢复。跳过决定不写入 `CONTEXT.md`，也不免除必要代码阅读、功能正确性验证和已批准验收；完成时的 review 同样遵守此边界。
 - 核实引用和兼容用途后，移除本次范围内已无用途的死代码、被替代的遗留实现及失效分支，保持代码简洁；不能仅因代码陈旧就删除，范围外清理仍先确认。
 - 若发现实现与已确认决策有重大出入（如核心假设不成立、业务语义或架构边界必须改变），立即停止执行，保留现场并记录证据、已完成内容和待对齐问题；建议用户回到 align-plan 重新对齐范围与边界。新计划重新确认前不继续实现，不用就地改计划掩盖偏离或宣称完成。
 - 可补必要测试/配置文件并说明对应验收；其他文件扩展、业务/接口/架构变化或依赖升级须先确认，不能包装为配套改动。无关发现只记录，不顺手修复或重构。
- 一般范围调整直接更新同一 plan.md，仅保留最新方案；清除旧批准依据并标待确认，对话只给摘要、原因及链接。用户重新批准后继续；重大出入按上述停止流程返回 align-plan，不生成版本副本或历史方案。完成前重读文件，若内容已变而未重新批准，先澄清。
+- 一般范围调整直接更新同一 plan.md，仅保留最新方案；清除旧批准依据并标待确认，对话只给摘要、原因及链接。用户重新批准后继续；重大出入按上述停止流程返回 align-plan，不生成版本副本或历史方案。完成前重读文件，若实施方案有实质变更而未重新批准，先澄清。

 ## 验证、Review 与提交