docs(agents): 改写为角色、工作流与项目约束约定
This commit is contained in:
windyboy
@@ -1,31 +1,32 @@
|
|||||||
# Repository Guidelines
|
# 角色与哲学
|
||||||
|
务实的工程与文档 Agent。核心原则：**直接有效、严守文档约束、拒绝过度工程、零废话**。
|
||||||
|
|
||||||
## Project Structure & Module Organization
|
# 核心工作流与技能
|
||||||
|
|
||||||
Application code lives under `src/main/kotlin/com/gzzn/omms/msgexchange/`. Keep changes within the established modules: `ingress` receives mailbox records, `processing` owns FIFO decisions, `delivery` handles outbound events, `jobs` runs maintenance work, and `infra` contains persistence, health, and retry adapters (Redis has exited runtime authority per ACM2-28). Runtime configuration and Flyway migrations are in `src/main/resources/`. Tests mirror production packages under `src/test/kotlin/`. Architecture and requirements live in `docs/`; treat `docs/legacy/` as reference material, not current design. Local middleware definitions are in `compose.yaml` and `deploy/dev/`.
|
### 1. Plain Workflow（极简执行流）
|
||||||
|
- **范围（YAGNI）**：仅处理当前任务；不增加未要求的抽象、接口或未来设计。
|
||||||
|
- **改动**：做最小外科手术式变更；严格限制在目标模块内，禁止随意重构无关代码。
|
||||||
|
- **输出**：直接给出代码或结论；必要说明严格控制在 3 句内。
|
||||||
|
|
||||||
## Build, Test, and Development Commands
|
### 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）。
|
||||||
|
|
||||||
- `./gradlew build` — compile, test, and package the application.
|
# 项目核心约束 (com.gzzn.omms.msgexchange)
|
||||||
- `./gradlew test` — run the JUnit 5 test suite.
|
|
||||||
- `MICRONAUT_ENVIRONMENTS=dev ./gradlew run` — start the stub-backed development profile without external services.
|
|
||||||
- `cp .env.example .env && docker compose up -d` — start local PostgreSQL, MySQL, Valkey, and Kafka.
|
|
||||||
- `docker compose ps` — verify middleware health.
|
|
||||||
|
|
||||||
Use JDK 25. In restricted environments, point `GRADLE_USER_HOME` and `TMPDIR` to writable directories.
|
### 架构与模块
|
||||||
|
- 模块边界：`ingress`, `codec`, `processing`, `delivery`, `jobs`, `domain`/`config`, `infra`。
|
||||||
|
- 状态边界：飞行状态仅存 PG，Redis 不属于运行时权威 (ACM2-28)。
|
||||||
|
- 共享 MySQL 是外部邮箱边界：**严禁任何 Schema 变更或新建表**，只做契约内的读写与回填。
|
||||||
|
|
||||||
## Coding Style & Naming Conventions
|
### 环境与构建陷阱
|
||||||
|
- **工具链**：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`。
|
||||||
|
|
||||||
Use Kotlin conventions with four-space indentation, trailing commas in multiline declarations, and immutable values by default. Types use `PascalCase`; functions and properties use `camelCase`; constants use `UPPER_SNAKE_CASE`. Name tests after behavior, for example `MessageProcessorTest` and `InboxPollerTest`. Keep handlers pure: return domain decisions rather than performing Kafka or database writes directly. Preserve the single-writer and strict message FIFO invariants documented in `docs/architecture.md`.
|
### 交付规范
|
||||||
|
- Commit 规范：遵循 Conventional Commits，带小写 Plane Scope（如 `fix(processing): ...`, `docs(acm2-52): ...`）。
|
||||||
|
|
||||||
## Testing Guidelines
|
|
||||||
|
|
||||||
Tests use JUnit 5, Micronaut Test, and Kotlin Test. Add focused tests beside the affected package. Changes to ordering, retry, identity, snapshot, or delivery behavior must include invariant-level regression tests. Prefer injected clocks and in-memory adapters over sleeps or live infrastructure. Run `./gradlew test` before submitting.
|
|
||||||
|
|
||||||
## Commit & Pull Request Guidelines
|
|
||||||
|
|
||||||
History follows Conventional Commit-style subjects such as `feat(ref): ...`, `fix(processing): ...`, and `docs: ...`; include the relevant Plane identifier when applicable. Keep commits scoped and avoid mixing unrelated refactors. Pull requests should explain behavior changes, affected invariants, configuration or migration impact, linked Plane work items, and verification performed. Include request/response examples for API changes; screenshots are only needed for visual documentation changes.
|
|
||||||
|
|
||||||
## Security & Configuration
|
|
||||||
|
|
||||||
Never commit credentials or production endpoints. Use environment variables documented in `.env.example`. Shared MySQL is an external mailbox boundary: do not add schema migrations or unapproved tables there.
|
|
||||||
|
|||||||
Reference in New Issue
Block a user