作者的话

项目起源

Sca4d-J 起源于作者的博客文章。文章讨论的不是如何使用更多设计模式，而是如何让不同工程师在不同时间进入项目后，仍然能够写出一致、清晰并且可以继续维护的代码。

因为一个系统最难的地方，不是让最聪明的人写出一段漂亮代码，而是让不同经验、不同水平、不同时间进入项目的人，都能持续写出风格一致、概念一致、命名一致、质量稳定的代码。
真正优秀的软件，不应该长期依赖维护者的个人能力。
它应该依赖设计本身。

这篇文章中的判断后来成为 Sca4d-J 的设计来源。脚手架不只提供可以启动的代码，也规定模块位置、调用方向、业务命名、数据边界、测试和文档，使后续功能能够沿着已经确定的路径继续开发。

但是真正的优雅，是可预测，是一目了然，神清气爽。

可预测首先表现为工程师能够根据现有项目回答具体问题：新功能放在哪个模块，对象如何命名，API 从哪一层进入，数据在哪一层读取，以及修改需要通过哪些检查。

Sca4d-J 使用固定的工程目录、明确的模块职责和 Controller -> Service -> Repository -> Mapper 调用方向保存这些答案。同类功能沿用相同结构，特殊情况必须说明现有结构无法表达的具体差异。

API 不是实现细节。
API 是项目内部的业务语言。

方法、类型、字段和路由共同描述项目中的业务对象与动作。准确的名称让调用方不进入实现也能理解代码；同一概念只有一个名称，也能避免不同模块逐渐形成互不兼容的表达。

项目因此拒绝使用 process、handle、execute 等泛化动词掩盖业务行为，也拒绝用没有业务含义的 Context、Options 或 Payload 隐藏必要输入。具体规则见核心编码规则和命名、类型与显式契约。

目录结构重复。
API 风格重复。
命名方式重复。
调用方式重复。
这些重复，都是架构的一部分。
它们让新人知道一个功能应该放在哪里，让维护者知道一个模块应该如何扩展，让项目在多人协作中仍然像一个人写出来的。

这里的重复不是复制业务逻辑，而是复用已经验证的代码形状。Request、Service、Repository、Mapper 和 View 在同类模块中承担相同职责，权限、消息、文件和配置使用项目已有入口。工程师可以根据一个已完成模块预测下一个模块的组织方式。

这种一致性也使人工开发和 AI 协作使用同一种代码语言。执行者可以变化，目录、命名、调用方向和验收条件不随任务变化。

架构本身，就是团队经验的积累。
一个好的架构，会让开发者自然写出一致的代码。
它不需要每个人都理解全部设计思想。
它只需要让人沿着既定路径走下去时，不容易犯错。

Sca4d-J 把已经确认的决定写入代码结构、类型、项目规范、测试和文档。源码只保留当前有效实现，Git 保存历史版本；测试保存可以自动验证的行为，文档保存用户和维护者需要长期理解的信息。

这些内容共同降低接手项目时需要重新判断的事项。工程师不需要恢复原作者的开发过程，就能从仓库中找到当前事实、修改位置和完成条件。工程验收原则定义代码是否达到这一要求，AI 协作设计说明 Agent 如何在相同约束下持续执行并允许人工接管。