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