legacy-lands-library: Instructions file for Codex

✅ 开发与协作规范（学习与编程行为指南）

本规范适用于你参与的全部开发任务，条款为强制性，除非用户显式豁免，任何条目都不得忽视或删减。

• 每次输出前必须深度理解项目背景、用户意图和技术栈特征；
• 当回答依赖外部知识或信息不确定时，先查询至少一份权威资料（官方文档、标准或源码）再作结论；
• 引用外部资料须在回复中注明来源；可使用链接或版本号，保证可追溯；
• 若用户需求含糊，先用一句话复述已知信息，并列出关键澄清问题，待用户确认后再继续；
• 同一次回复中的术语、变量名、逻辑描述保持一致；发现冲突必须立即修正；
• 仅回答与问题直接相关内容，避免冗余、无关扩展或教程式铺陈；
• 面对复杂需求，先拆分为若干可管理子任务，在输出中按子任务顺序呈现，便于用户跟进；

所有技术输出必须建立在准确、思考过的基础之上，拒绝机械生成与无脑填充。 如果你已经了解所有的规范，你需要在用户第一次进行对话时先说明 "我已充分了解开发与写作规范。"，随后再执行用户需求。

1. 当你尝试编写一个新功能、添加新类或书写 Javadoc 时

1. 你需要先查看其他类的实现，尤其是相同模块中的类；
2. 主动学习、模仿现有代码的结构与风格，包括：
   • 缩进与换行格式；
   • 命名习惯；
   • Javadoc 注释风格。
3. 多使用 serena MCP 完成可能的操作。

2. 你必须制定清晰的 ToDo 任务清单，并在开发完成后遵循以下规则：

1. 使用 Gradle 的 shadowJar Task 尝试打包；
2. 若出现编译错误，必须修复后重新编译，直至编译通过；
3. 编写测试前，先熟悉 foundation 模块以及 net.legacy.library.annotation.test 包中已提供的测试示例；
4. 编写基于功能的集成测试，测试内容不得流于无意义断言，需覆盖核心业务逻辑与边界条件；
5. 测试通过后，在当前模块的 Launcher 中注册新测试入口，参考 net.legacy.library.annotation.AnnotationLauncher 的实现方式；
6. 若需要为当前模块引入其他模块作为依赖：
   • 先检查是否会造成循环依赖；
   • 若无循环依赖，则使用 compileOnly 方式声明；
7. 编译全部通过后，将完整测试流程交由用户执行，由用户反馈日志进行进一步调整，你不能自己执行任何的测试，包括 javap 等指令；
8. 除非用户有明确说明，否则你不应撰写任何示例（example）或额外文档。

3. 命名规范（类、字段、变量、方法）

1. 命名应清晰、准确、语义明确：
   • ✅ 正确示例：Exception exception，Throwable throwable，IOException exception
   • ❌ 错误示例（过于简单化）：Exception e，Throwable t
   • ❌ 错误示例（过于复杂化）：Exception exceptionWhenFailedToInitializeXxx
   • ❌ 错误示例（无意义）：Cache whatIsThis = ...
2. 出现命名重复时，应提升语义层级，而非简单加数字：
   • ✅ 正确示例：Cache cache; Cache redisCache
   • ❌ 错误示例：Cache cache; Cache cache2

4. 数据处理优先使用 Stream API（尤其是过滤、映射、聚合等操作）

• 避免使用传统 for 循环完成可以用 stream 完成的链式操作；
• 确保代码简洁、函数式、可读性强。

5. Lambda 表达式需保持简洁，避免冗余语法

1. ✅ 正确用法（单行时省略 {} 与 return，可使用方法引用）：
   • () -> "something"
   • list.forEach(CustomExecutor::shutdown)
2. ❌ 错误用法（冗余、过度包装）：
   • (x) -> { doSomething(x); } → 简化为 x -> doSomething(x)
   • () -> { return "something"; } → 简化为 () -> "something"
   • list.forEach(x -> { CustomExecutor.shutdown(x); }); → 应使用方法引用