Repository navigation
[Docs] 完善 AGENTS.md 的工程判断、变更范围与行为验收规范 #332
Description
问题与目标
当前 AGENTS.md 已规定贡献流程、架构依赖和构建方式，但缺少统一的工程判断规则。最近的架构与插件任务涉及多模块迁移、公共契约和持续 Issue 拆分，需要约束无证据抽象、无关改动、重复提问及以接口存在代替行为验收。
参考用户提供的 fesod AGENTS.md 四项原则：Think Before Coding、Simplicity First、Surgical Changes、Goal-Driven Execution。结合 ARGI 框架定位调整措辞，不逐字照搬，不以行为指南重新限定已经获准的架构目标。
修改范围
本单仅调整 Core 仓库 AGENTS.md 的工程行为与贡献流程说明；保留项目专属架构、依赖方向、构建、来源版权及有效贡献要求。Extensions 的规则如需同步另行明确，不默认跨仓交付。不包含生产代码、模块重组或历史 Issue 批量改写。
具体交付
- 编码前区分源码事实、已验证行为、设计建议及未验证假设；影响公开 API、配置、持久数据或依赖方向的选择说明替代方案和收益。
- 调整编码前三个问题的执行方式：已有 Issue/会话已明确目标、范围/兼容和验收的，直接引用，不反复询问；关键内容缺失或相互冲突时补问并等待。只读审阅、问题复现分析及创建 Issue 不机械套用编码前提问。
- 简单优先：不增加未经请求的功能或配置；框架公共抽象需有明确消费者、可验证场景或依赖隔离依据，不因只有首个实现就一律禁止，也不以“未来可能用到”扩展。
- 精准修改：不顺带清理无关代码/注释/格式，不覆盖用户已有改动；清理本次变更产生的无用项。合理架构迁移可跨模块，但每组修改应对应目标、依赖迁移或验收，不机械追求最小 diff。
- 保留已授权的大幅重设计方向；破坏性变更逐项说明问题、较小方案、收益、影响、版本和迁移，不以换名、包装层、模块数量或与上游形式不同证明独立性。
- 目标驱动验证：Bug 提供失败复现；行为重构验证前后契约；新行为覆盖成功/拒绝/失败/取消及相关竞态。文档和低影响配置采用适合的检查，不机械增加测试。
- 结果报告区分静态分析、确定性夹具、真实模型、真实后端、跨 JVM 和实际部署；跳过不算通过，历史日志不冒充当前提交的新验证。
- Issue 拆分依据独立交付和验收边界；不能独立实施/必须同时合并的紧耦合工作考虑合并为一实施单。父单仅汇总与组合验收，不与子单重复实现，不以 Issue 数量衡量细化程度。
- 插件策略可以替换，可信身份、取消/预算、必经授权/最终参数检查及状态提交保证不得通过停用普通插件绕过；执行引擎和适配器无需全部改成生命周期回调。
验收场景
- 给定信息完整的 Issue：助手引用已有目标、范围与验收继续工作，不再机械重复三个问题。
- 给定缺失兼容决策的公开 API 修改：先指出具体不确定点，再针对缺失内容提问。
- 给定局部取消 Bug：变更和验证围绕取消链路，不顺带迁包、格式化或清理既存死代码。
- 给定已获准的跨模块迁移：允许必要的大范围修改，逐组对应职责、兼容决策和行为验收。
- 给定插件化任务：先复用现有 Hook/Interceptor，不因“可扩展”默认新增执行引擎、注册中心或 Maven 模块。
- 给定只有静态检查或跳过的集成测试：报告实际范围，不声称真实服务或生产保证已经验收。
评审应能从更新后的文字明确判断以上场景的期望行为。检查 Markdown/diff 和项目原有规则的一致性；本单不要求运行与文档修改无关的完整 Maven 测试。
约束与关联
关联 #180、#201、#202、#298—#301。后续改变其他贡献要求应独立说明理由，不借本单删除 PR 去重、版权或依赖隔离规则。用户明确指令优先，已提供的授权和信息持续有效。
本单是文档规范改进，不是生产缺陷；创建 Issue 不代表规范已修改。
Activity