73 lines
8.1 KiB
Markdown
73 lines
8.1 KiB
Markdown
---
|
|
name: align-plan
|
|
description: 仅用户指定 align-plan 时启用；对齐工程目标与边界，生成待审阅计划，不实施代码。
|
|
---
|
|
|
|
# 对齐目标并生成计划
|
|
|
|
完成条件：目标和关键决策已对齐，自包含的 plan.md 已保存并经用户确认，可交给新会话执行。具体调查方法与深度按任务选择，不要求完整仓库扫描。
|
|
|
|
## 定位与资产
|
|
|
|
- 读取项目约束、Git 状态和 `.agent/MEMORY.md`。资产根目录优先用用户本次明确指定位置，否则复用已有定位；没有则在首轮询问，期间可只读调查。
|
|
- 根目录默认在代码库外，一目录对应一系统。计划可存于根目录下的 `<日期-计划主题>/`，不插入项目层；已指定计划目录则直接使用。根目录未知时询问，不推断父目录；系统不符或位置冲突先澄清。复用同一计划目录，新计划避免覆盖同名目录。
|
|
- MEMORY 仅记录 `讨论资产目录：<绝对根目录>` 等定位，保留其他内容。写入前检查是否已被 Git 跟踪：已跟踪则先解决冲突，不自行取消跟踪；否则在 `git rev-parse --git-path info/exclude` 中幂等加入 `/.agent/MEMORY.md`，不改共享忽略规则。非 Git 项目说明无法排除。
|
|
- 规划只写讨论资产及必要定位信息。目录不可用或宿主禁止写入时报告，不回退代码目录、不宣称已保存。
|
|
|
|
所有生成资产（含 MEMORY）以此 YAML 开头，未知字段留空，特殊值加引号：
|
|
|
|
```yaml
|
|
---
|
|
系统: 系统名称
|
|
时间: YYYY-MM-DD
|
|
目标: 资产对应目标
|
|
---
|
|
```
|
|
|
|
时间使用用户当地决策日期；草稿先记创建日期、确认后更新，进度与排版不改日期。
|
|
|
|
Markdown 正文按内容排版：代码、命令及多行配置用带语言标记的围栏代码块，标识符与路径用行内代码，原文引用用 `>` 并注明来源。顶部 YAML 直接保留，不把全文包进代码块；排版不增加原本不需要的内容。
|
|
|
|
## 系统约束与讨论状态
|
|
|
|
先读根目录 `CONTEXT.md`，再调查相关代码；不扫描历史计划。首次无 CONTEXT 时，从首条已确认长期约束开始创建。
|
|
|
|
- `CONTEXT.md`：只按业务约束、技术约束记录当前有效规则，可注明适用模块及必要原因。确认且无需实施的约束直接更新；尚未生效的改造只留在当前讨论和计划中。冲突先确认，替换时删除废弃内容，不保留决策过程、历史计划路径、任务、代码、日志或局部实现偏好。目标为“保存系统当前业务与技术约束”，时间为最近确认决策日期。
|
|
- `<计划目录>/current.md`：每轮更新目标、验收、确认决策与原因、事实来源、约束、不做事项、未确认假设和问题；删除失效内容，不累计讨论历史。
|
|
- 新会话或压缩恢复时读取 CONTEXT 与当前状态，按未决问题补读相关代码；出现矛盾时只复核相关资料，其余复用无变化内容。确认状态以真实回答为准，沉默和推荐都不算批准。
|
|
|
|
## 调查与提问
|
|
|
|
- 调查限于当前目标所需的代码、调用链和测试；只有涉及架构、数据或上线时才补读相应资料。外部查证须能解决具体未决问题，保留来源和必要版本，不为走流程搜索。
|
|
- 每轮共 1–3 个影响目标、验收或取舍的问题，不能用子问题变相扩充。可查事实不问用户，依赖未决答案的问题后置；有提问工具则使用，否则直接问。
|
|
- 简述证据与推荐理由，不用装饰性 emoji。纠正错误事实，区分假设与偏好；用户提出想法不等于确认方案。
|
|
- 在满足下述可读性与模块边界的前提下，优先复用现有能力，控制改动范围。出现独立子目标或明显扩大的改造时，说明扩大点、建议分阶段，由用户选择；未确认前保持原范围。
|
|
- 目标、边界、关键取舍和验收明确后停止提问。
|
|
|
|
## 设计原则与逐项检查
|
|
|
|
- **Codex 可读性永远摆在第一位**：让业务入口容易定位，职责和接口契约清晰，调用与数据流容易追踪；不以最少行数、最少文件或最小 diff 代替可读性，也不为缩小改动继续堆叠旧逻辑。
|
|
- **功能模块化设计**：围绕业务职责划分模块，同一业务规则有明确归属，跨模块调用方只依赖公开接口，不感知内部实现，保持高内聚、低耦合。遵循单一职责和开闭原则，通用架构能力不绑定具体业务；区分合理协作与业务规则散落，不把整个业务链路强塞进一个模块。
|
|
- 接受模块化初期一定程度的过度工程化，包括为清晰边界增加接口、文件和结构；不因暂时只有一个实现就否定接口。新增结构应能解释其职责及可读性、隔离或演进收益，不为套模式增加无关抽象。
|
|
- 每个功能或优化点在确定方案前，局部检查相关模块及调用、依赖关系的 **Codex 可读性、循环依赖、复杂度、架构健康度**。健康度按上述模块职责与接口边界判断，循环依赖须有实际闭环依据，复杂度关注理解和修改成本；复用仍有效的证据，不机械重复全仓扫描，也不自动调用其他 skill。
|
|
- 发现与本次目标相关的优化空间时，先给出代码证据、沿用现状继续开发的影响、优化方向、收益、成本及范围，纳入当轮 1–3 问确认是否本次处理。已批准的优化不重复确认；未确认的优化不纳入实施范围，无问题时直接推进。
|
|
- 用户确认本次不优化后，在 `current.md` 和 `plan.md` 记录本次任务、适用模块、跳过的检查维度及用户确认依据。此任务不再检查或追问该“模块 × 维度”，其他组合继续；范围不明确时澄清，不自行扩大。新会话或压缩恢复须继承，新任务默认重置，本任务仅用户明确调整才恢复。跳过决定不写入 `CONTEXT.md`，也不免除必要代码阅读、功能正确性验证和已批准验收。
|
|
|
|
## 写入、审阅与交接
|
|
|
|
只维护 `<计划目录>/plan.md`，先写入并标为“待确认”；修订覆盖同一文件，只描述最新方案，不保留版本副本、旧方案或变更历史。正文自包含，可合并章节，但须有：
|
|
|
|
1. **定位**：项目及必要仓库标识、资产根目录与 CONTEXT 绝对路径、Git 基线（无提交则注明）、相关工作区变化、确认状态/依据。
|
|
2. **目标与决策**：原始目标、当前/目标行为、保留行为、不做事项；决策理由、业务/接口/架构变化或不变；相关系统约束快照及状态、已确认假设；本次已批准的优化及按模块、维度跳过检查的决定与确认依据，供实施继承。
|
|
3. **修改范围**：新增/修改/删除的文件、各自目标和原因、必要依赖顺序及对应验收。允许必要测试/配置配套文件并记录，其他范围变化重新确认。
|
|
4. **验证**：从原始目标推导正常、边界、异常及保留行为场景，明确预期结果和对应验收；列测试、运行目录/命令与必要环境。不能仅按变更代码列用例，预期行为须独立于实现，能发现偏离目标的结果。
|
|
5. **兼容与上线**：评估受影响的接口、数据、配置及新旧版本兼容性；明确是否需要迁移、特殊上线步骤或先后顺序，必要时说明回退限制。无特殊要求则注明，未知项列为待核实。
|
|
|
|
不预写详细实现代码；仅核心算法可附少量审查片段，执行 agent 可自主选择满足已批准约束的实现。
|
|
|
|
写完重读，检查遗漏、矛盾及隐含决策；缺关键决定则继续提问。确认文件可读后，对话只给目标、范围、重要影响与验证摘要，以及文件绝对路径链接，供用户阅读确认；除非用户要求，不贴全文。
|
|
|
|
用户确认当前文件内容后记录批准依据与日期。实质修订直接更新 plan.md，清除旧批准依据并重置为待确认，再给摘要与链接；重新确认前不执行变化。写入或摘要不代表批准。
|
|
|
|
确认后给出新会话提示：`$execute-plan 执行 /绝对路径/plan.md`，结束规划。不要自动实施或声称已清空上下文。
|