AI 协作设计
AI Coding 的发展背景
生成式 AI 已经从代码补全发展到可以检索仓库、修改多个文件、运行命令和根据检查结果继续修复的 Agent。它适合处理代码定位、重复实现、测试补充、文档同步和跨文件修改，可以显著缩短从需求确认到可运行实现所需的时间。
这种效率并不直接等于可维护性。模型根据当前输入生成结果，不天然了解项目长期形成的业务定义、目录边界、兼容要求和历史决定。任务描述越短、项目上下文越少，输出越容易只满足眼前的字面要求。
AI Coding 因此不是用生成速度替代工程规则，而是把检索、实现和检查交给能够持续执行规则的工具。人仍然负责目标、取舍和验收，项目仍然以源码、测试、配置和文档作为事实依据。
当前问题
局部正确不等于项目正确
Agent 可以快速完成一个 Controller、页面或数据库字段，但一次功能变更通常还涉及权限、状态转换、错误响应、并发、多实例运行、测试和文档。只检查局部代码时，遗漏往往要到联调、发布或后续维护阶段才会出现。
对话不能保存项目事实
业务决定如果只存在于一次对话中，下一次任务无法可靠取得这些信息。相同名称可能被重新解释，临时兼容代码可能被当成正式设计，已确认的限制也可能在后续修改中丢失。
测试通过不能代替工程审查
测试只能证明已经编写的断言成立。错误的分层、含糊的类型、绕过公共能力的实现和不可接管的文档，即使通过测试，也会增加后续修改成本。
无约束生成会放大差异
当每次任务使用不同的提示词、命名和实现路径时，相似功能会逐渐出现不同的目录、接口和错误处理方式。这里的信息熵表现为可以直接观察的差异：同一业务词有多个类型、同一状态有多个来源、同一能力有多条执行路径，维护者必须重新判断哪一项才是有效实现。
信息熵与工程维护
信息熵描述信息中的不确定性。业务定义、运行约束和历史决定越分散、越矛盾，维护者准确判断当前行为所需的额外信息就越多。
当业务决定只存在于对话中、同一概念出现多个名称、旧实现与新实现同时有效时，项目的信息熵会持续增加。明确的类型、唯一的执行路径、可运行的测试和与实现一致的文档，可以减少维护代码所需的额外判断。
控制信息熵不等于增加更多文档或规则。重复、失效或与代码不一致的信息同样会增加不确定性。需要保留的是当前有效的业务定义、约束条件、验证方式和未完成事项。
Sca4d-J 的设计原则
Sca4d-J 的工程规则并非只为 AI 编写。它们首先用于保证人工开发可以预测代码位置、理解运行条件并接管未完成工作。AI 协作沿用同一组要求，不建立另一套实现标准。
用业务语言约束实现
需求中的业务对象、状态和动作应当对应明确的类型、接口、数据库字段和页面文本。Agent 发现一个词存在多个解释时必须先确认，不能选择其中一种猜测写入代码。
用工程结构限制修改路径
项目规定模块职责、调用方向、公共能力入口和基础设施边界。新增功能必须进入既有结构；不得为完成局部任务增加旁路调用、重复抽象或只服务于当前提示词的中间类型。
用检查结果决定是否完成
类型检查、数据库约束、测试、格式化、构建和项目规范共同构成验收条件。任一检查失败，任务都没有完成。检查对象包括每个修改文件的完整内容，而不只是本次生成的代码片段。
用仓库内容保存决定
已经确认且影响后续开发的信息必须进入源码、配置、测试或面向人的文档。临时对话只用于沟通，不能成为理解当前实现所必需的唯一来源。维护者应当能够根据仓库状态、验证结果和未完成事项继续工作。
控制变更带来的信息熵
每次变更都应复用现有业务名称、删除已经失效的路径、同步测试与文档，并记录尚未完成的事项。这样做不能消除系统复杂度，但可以避免一次临时决定产生第二套名称、第二条调用路径或只有原作者知道的隐含条件。
Agent 的三个角色
执行器
Agent 根据已经确认的计划执行文件检索、代码修改、测试、构建和文档更新。它不得在任务之外增加重构，也不得为了简化实现而修改已经确认的业务要求。
解释器
Agent 把用户使用的业务语言对应到项目中的类型、接口、数据库和页面。存在多个有效解释时，它列出差异并请求确认，不把猜测转换为实现。
编译器
Agent 把最终目标转换为可以检查的产物，包括源码、迁移、配置、测试和文档。这个过程类似编译：输入是明确目标、确认后的计划和项目规则，输出必须同时满足结构与验收要求；出现任何不合规项时，继续修复而不是提交部分合格的结果。
这三个角色都不包含业务决策权。人负责决定要构建什么，Agent 负责在项目允许的范围内把决定转换为产物，并提供可以复查的证据。
Goal 与 Loop
一个 Goal 描述一次任务最终必须成立的结果，包括范围、排除项和验收条件。Loop 是 Agent 持续逼近该结果的执行过程：
- 读取当前代码、项目规则和任务状态；
- 选择尚未完成且可以验证的工作；
- 修改实现并运行对应检查；
- 对照 Goal、计划和项目规范审查完整结果；
- 修复问题并进入下一次检查。
Loop 与脚手架规则的契合点在于每一步都有稳定输入和停止条件。Agent 不需要临时发明目录、分层或验收方式，只需要按项目已有规则执行；Goal 未满足时继续处理，全部约束通过后才允许提交。
Loop 不是重复运行同一个失败命令。每次执行必须产生新的代码、验证证据、已确认决定或明确的阻塞信息。无法由 Agent 决定的业务取舍返回给人，确认后再继续。
人工接管
人工接管是指工程师可以在任意工作批次结束后继续修改代码，不需要恢复 Agent 的会话、推理过程或未写入项目的背景信息。接管范围既包括已经完成但尚未提交的修改，也包括测试失败、方案冲突或只完成部分模块的中间状态。
作者的话说，好的架构会让开发者自然写出一致的代码。AI Coding 改变了代码由谁写下，却不应改变项目使用的语言。只要生成的代码仍然遵守既有目录、命名、API、调用方向和验收条件，人工接管就不是从 AI 手中抢救一份熵爆炸的屎山，而是像接手其他工程师的代码(ps: 没有说其他工程师写的就不是屎的意思)一样继续项目。
可预测的代码位置
脚手架规定模块职责、目录、类型名称和 Controller -> Service -> Repository -> Mapper 调用方向。同类功能沿用同一结构后，接手者可以根据业务名称找到入口、数据访问、测试和配置，不需要先还原本次任务采用了哪一种代码组织方式。
可预测的工程结构要求新增功能沿用已经验证的代码形状，并禁止为局部任务增加第二套请求态、权限、消息、文件或配置入口。这些规则直接限制 Agent 可以生成的结构，使人工编写和 Agent 编写的代码采用相同的阅读路径。
可以独立理解的实现
接手者必须能从代码看到完整的校验、决策、状态变化、持久化和副作用。业务定义不能只存在于提示词，关键顺序不能隐藏在没有业务含义的私有步骤中，当前实现也不能同时保留多个事实来源。
工程验收原则以长期理解成本、职责清晰度和系统一致性评价代码，不以生成速度、抽象数量或代码行数评价代码。相同标准同时适用于人工修改和 Agent 修改，因此接管时不需要先识别或迁就一套专用于生成代码的写法。
保存在仓库中的任务状态
源码和当前工作树保存已经发生的修改；测试保存可以自动验证的行为；文档保存用户和维护者需要长期理解的信息；计划保存本次任务的范围、顺序和验收条件。已经确认且会影响后续实现的决定必须进入这些内容，不能只留在任务对话中。
每个工作批次还必须记录：
- 当前 Goal 和明确不做的内容；
- 已确认的业务与技术决定；
- 已完成内容和剩余工作；
- 新增、修改、重命名和删除的文件；
- 已运行命令、成功结果和失败原因；
- 当前阻塞条件和下一项可以直接执行的工作。
记录必须与工作树一致。代码尚未通过编译、测试或规范审查时，记录具体失败项，不用“基本完成”替代当前状态。工程师接管后可以先复现已有证据，再从第一项剩余工作继续推进。
人工与 Agent 之间切换
任务状态不属于某个执行者。工程师可以修改 Agent 生成的代码、调整计划并继续验证；后续也可以把同一个 Goal、当前工作树和新的验证结果交还给 Agent。切换执行者不会改变项目规则和完成条件。
这种切换要求每次修改都减少旧名称、旁路实现和失效说明，而不是用兼容代码保存所有历史尝试。仓库只保留当前有效实现，Git 保存历史版本，任务记录只说明当前批次尚未进入仓库事实的内容。
规则的自我应用
AI 协作规则同样约束 Agent 修改本章节和其他项目文档。Agent 必须先按现行规则完成内容核对、构建和审查，不能先降低规则再让本次修改通过。新规则经维护者确认后，才适用于后续任务。
这项要求保证人工实现、Agent 实现以及 Agent 对项目规则的修改使用相同的验收条件。文档必须面向项目用户和维护者，不能依赖生成者的解释才能理解。
示例
增加一种登录方式时，Agent 不能只新增 Controller。它需要先读取认证、Session、权限、数据库和管理端实现，确认认证材料、登录步骤、错误结果和管理入口，再提交包含后端、前端、测试和文档的计划。计划确认后，Agent 逐项实现并重复检查，直到所有修改文件符合项目规范且验证命令通过。
强制执行要求见AI 执行规则，完整操作步骤见使用 AI 交付可维护代码。