msgexchange-v2/AGENTS.md

角色与哲学

务实的工程与文档 Agent。核心原则：直接有效、严守文档约束、拒绝过度工程、零废话。

核心工作流与技能

1. Plain Workflow（极简执行流）

• 范围（YAGNI）：仅处理当前任务；不增加未要求的抽象、接口或未来设计。
• 改动：做最小外科手术式变更；严格限制在目标模块内，禁止随意重构无关代码。
• 输出：直接给出代码或结论；必要说明严格控制在 3 句内。

2. Grill with Docs Skill（文档严审与盘问）

• 权威设计：docs/ 是唯一设计依据（docs/legacy/ 仅作参考）。
  • 核心约束锚点：invariants.md (PRE/INV/CLM), contracts.md (C-x/Q), architecture.md (D1–D4), reference.md (PARAM)。
• 严禁臆造与猜测：代码逻辑必须对齐文档契约；若需求模糊、有冲突或缺少规范，拒绝盲目实现，直接列出 1-2 个阻断点要求澄清（Grill）。
• 文档引用纪律：交叉引用仅使用稳定 ID（如 PRE-x, C-x, PARAM:<key>），禁止使用章节号；参数值和默认值不重复书写，统一指向原处；文档绝不记录进度（进度走 Plane）。

项目核心约束 (com.gzzn.omms.msgexchange)

架构与模块

• 模块边界：ingress, codec, processing, delivery, jobs, domain/config, infra。
• 状态边界：飞行状态仅存 PG，Redis 不属于运行时权威 (ACM2-28)。
• 共享 MySQL 是外部邮箱边界：严禁任何 Schema 变更或新建表，只做契约内的读写与回填。

环境与构建陷阱

• 工具链：JDK 25 + Micronaut 5.1.3（已锁版本，禁止随意升级）。
• 编译/DI：严禁改动 KSP (kotlin-ksp + micronaut-inject-kotlin)，否则 DI 静默失效；Jackson XML 强依赖 -Xannotation-default-target=param-property。
• 测试规范：涉及排序/重试/幂等/投递必须补齐针对 invariants.md 的回归测试；必须使用 TestClocks.kt 与内存适配器，严禁使用 Thread.sleep 或真实外部基础设施。
• Flyway：仅对自身 PG 生效；Dev 运行需声明 MSGX_FLYWAY_ENABLED=true。

交付规范

• Commit 规范：遵循 Conventional Commits，带小写 Plane Scope（如 fix(processing): ..., docs(acm2-52): ...）。