# AGENTS.md 本文件定义 AgentAdmin 仓库中 AI 代理（尤其是 Codex）与人类协作者共同遵守的工程约束。 它不是通用贡献指南，而是本项目的 **AI 开发宪法**。 所有自动化代码生成、重构、修复、脚手架补全、接口调整、文档更新与联调支持，都必须遵守本文件。 --- ## 0. 文档真源与优先级 本仓库采用“文档真源 + 执行约束”双层治理。 ### 0.1 真源文档 以下文档属于项目真源（source of truth），AI 在实施前必须优先遵守： - `00-document-system-index.md`：文档系统入口、阅读顺序、真源规则、文档更新规则 - `01-project-overview.md`：项目定位、目标用户、系统边界、MVP 范围、非目标 - `02-system-overview.md`：总体架构、双平面边界、核心链路、部署基线、跨层约束 - `03-backend-development-architecture.md`：后端模块边界、状态流转、安全规则、实施顺序 - `04-frontend-development-architecture.md`：前端路由、页面、分层、状态管理、权限、SSE 交互 - `05-api-specification.md`：REST、SSE、分页、过滤、能力表达、接口兼容规则 - `06-data-model-specification.md`：核心实体、表边界、关系模型、JSON 字段策略、冷热数据规则 - `07-enum-and-state-definitions.md`：术语、状态机、运行枚举、事件名、能力码前缀 - `08-error-code-specification.md`：错误响应结构、错误码前缀、核心错误码、处理语义 - `09-common-fields-and-naming.md`：数据库/API/前端命名规则与通用字段 - `10-frontend-backend-collaboration.md`：前后端职责划分、接口变更流程、并行开发边界、交付要求 - `11-integration-and-acceptance.md`：联调顺序、必测场景、验收证据、缺陷分级 - `12-development-plan.md`：阶段计划、并行轨道、里程碑、推荐开发顺序 - `13-pre-development-checklist.md`：开发前必查项、高风险变更检查、停机点、接力交接模板 ### 0.2 优先级规则 发生冲突时，遵守以下优先级： 1. 当前任务明确要求 2. `AGENTS.override.md` 3. 本文件 `AGENTS.md` 4. 真源文档系统（00~13） 5. 现有代码实现 6. AI 自行推断 ### 0.3 真源优先原则 如果： - 代码实现与真源文档冲突 - 两个模块的局部实现互相矛盾 - 命名、枚举、错误码、接口结构与规范不一致 默认以文档真源为准，不得擅自以“代码现状”为借口继续扩散错误实现。 如发现文档已明显过时，必须在输出中明确指出，而不是静默绕过。 --- ## 1. 项目身份 AgentAdmin 是一个面向 **Java 业务系统** 的 Agent 接入与治理平台。 它的定位不是： - 聊天应用 - 通用 AI 工作流画布 - Prompt playground - Dify / Langflow / Coze 的 Java 复刻版 它的定位是： - 为现有业务系统提供 **外挂式 Agent 能力接入** - 将已有业务能力沉淀为 Tool - 提供 Agent 的统一定义、调试、发布、运行、观测、治理能力 - 成为 Java 生态下可落地的 Agent 基础设施 所有实现必须服务于这个目标。 --- ## 2. 不可破坏的核心原则 ### 2.1 架构原则 第一阶段默认采用： - **模块化单体（Modular Monolith）** - **Control Plane / Exec Plane 双平面架构** - 清晰领域边界，未来按热点拆分 在没有明确任务要求时，禁止： - 擅自引入微服务拆分 - 引入 Spring Cloud 全家桶 - 引入 Nacos / Kafka / Flowable 等重型依赖作为前置条件 - 为“未来扩展”提前设计分布式复杂度 ### 2.2 产品边界原则 第一版后端重点是： - Tool 接入 - Agent 定义与版本发布 - Playground 调试 - Run / Trace 观测 - Executor 注册与治理 - 多租户 / 权限 / 审计骨架 - 插件扩展骨架 第一版前端重点是： - 登录与租户切换 - Agent 管理 - Tool 管理 - Playground - Run / Trace - Executor 管理 - 审计日志 - 基础设置页 在没有明确任务要求时，禁止优先实现： - 复杂多 Agent 编排 - 可视化工作流画布 - 大而全的知识库系统 - 自研向量平台 - 重型规则引擎 - 聊天首页化产品改造 - 为营销展示服务的非核心 UI ### 2.3 工程原则 优先级固定如下： 1. 可落地 2. 边界清晰 3. 易于本地开发与部署 4. 对 Java 团队低侵入 5. 后续可演进 不要为了“更优雅”而牺牲： - 可理解性 - 启动成本 - 调试便利性 - 开源用户上手体验 --- ## 3. 默认技术栈 如无明确任务要求，默认遵守： ### 后端 - Java 21+ - Spring Boot - Spring Security - Spring AI - MySQL - Redis - JWT - OpenAPI / springdoc - SSE - Micrometer + OpenTelemetry - Slf4j / Logback - Java SPI + Spring AutoConfiguration - JSON Schema ### 后端 Java 代码规范补充 后端 Java 代码默认补充遵守以下约束： - 实体类只能使用 `class`，禁止使用 `record` - 实体类命名禁止使用 `*Record` - DTO 请求对象统一使用 `*ReqDTO` - DTO 响应对象统一使用 `*ResDTO` - 请求 DTO 与响应 DTO 应尽量分包存放，优先使用 `reqdto/` 与 `resdto/` 目录 - Mapper 必须通过 XML 编写 SQL，禁止在 Mapper 接口方法上直接写 `@Select`、`@Insert`、`@Update`、`@Delete` - 工具类统一使用 `*Util` 命名，并集中存放在 `utils` 包中 - 字符串、集合、Map 等通用规整逻辑，优先通过 `agentadmin-common` 中统一封装的 Hutool helper 使用，避免各模块重复手写 `trimToNull`、判空与小型容器构造 - 如无当前任务明确要求，后端开发阶段不以“本地启动通过”作为必须完成项；但仍应完成代码级自检，并明确说明未启动验证的风险 ### 前端 - Next.js（App Router） - TypeScript - React - Tailwind CSS - shadcn/ui - Radix UI - TanStack Query - React Hook Form + Zod - OpenAPI 生成 API Client - SSE 流式交互 不要擅自替换为： - 重型服务网格方案 - 非主流框架 - 需要显著增加学习成本或部署复杂度的中间件 - 无明确收益的技术栈迁移 --- ## 4. 项目初始化与仓库结构约束 当前项目**可能尚未完成初始化**。 如果仓库结构尚未建立，则本节用于提供 **推荐的初始化结构** 与 **模块边界心智模型**，而不是声明当前仓库事实。 AI 必须遵守以下规则： 1. 如果仓库已有实际目录结构，优先遵循实际结构 2. 如果仓库尚未初始化，可按本节推荐结构创建 3. 即使目录结构暂未建立，也必须先遵守模块边界，不得混写 4. 不得因为项目尚未初始化，就把所有代码堆在单一目录中 5. 不得在未明确要求时，过早拆成重型多模块、微服务或复杂 monorepo 结构 ### 4.1 初始化阶段的核心原则 项目初始化阶段，优先固定的是： - 模块边界 - 职责分层 - 前后端协作边界 - 接口与状态语义 - 目录落点的一致性 而不是优先追求： - 物理模块数量 - 微服务拆分 - 复杂工程编排 - 多仓库布局 - 过度抽象的基础设施层 默认策略是： **先建立清晰的逻辑边界，再根据实现复杂度逐步演进物理结构。** ### 4.2 后端初始化推荐结构 后端第一阶段推荐采用： - 单仓库 - 模块化单体 - 单 Spring Boot 应用优先 - 清晰包结构优先于 Maven 多模块数量 推荐以逻辑模块先行，至少区分以下领域边界： - `auth` - `tenant` - `rbac` - `agent` - `tool` - `executor` - `runtime` - `model` - `session` - `observability` - `audit` - `plugin` - `common` 如果项目尚未初始化，后端可先按如下形式建立： ```text backend/ src/main/java/com/agentadmin/ auth/ tenant/ rbac/ agent/ tool/ executor/ runtime/ model/ session/ observability/ audit/ plugin/ common/ ``` 说明： - 第一阶段这些模块可以先作为**单体工程中的包边界** - 不要求一开始就拆成多个独立服务 - 不要求一开始就拆成多个独立仓库 - 是否拆成 Maven 多模块，应以实施便利性和边界稳定性为准 - 即使处于单体工程中，也不得跨模块随意共享实现细节 ### 4.3 后端工程初始化方案选择 如需初始化后端工程，优先采用以下顺序： #### 方案 A（推荐） **单 Spring Boot 应用 + 清晰包结构** 适用场景： - 项目刚启动 - 需要快速验证 MVP - 团队人数较少 - 希望降低本地开发与部署成本 优点： - 启动快 - 易调试 - 结构清晰 - 便于后续按热点拆分 #### 方案 B（可选） **Maven 多模块，但仍保持模块化单体** 适用场景： - 已明确存在 SDK、插件 API、Starter 等独立边界 - 希望提前隔离部分依赖 注意： - 仍然不是微服务 - 不应过早把业务模块拆散成独立部署单元 - 如需抽出共享运行内核，应优先建立职责明确的独立模块，例如 `agentadmin-runtime` - 如需抽出 MCP / SYSTEM Tool 的共享发现与绑定支撑，应优先建立职责明确的独立模块，例如 `agentadmin-tool-support` - 禁止在 `agentadmin-server` 内新增模糊目录，如 `core`、`common/core`、`module/core` #### 方案 C（当前不推荐） **按 Control Plane / Exec Plane 提前拆成多服务** 除非任务明确要求，否则初始化阶段不采用。 当前阶段应先固定逻辑边界，而不是提前引入分布式复杂度。 ### 4.4 前端初始化推荐结构 前端第一阶段推荐采用： - 单 Next.js 应用 - App Router - 以 feature 为主组织目录 - 页面、组件、API、状态逻辑分层清晰 如果项目尚未初始化，前端建议按如下形式建立： ```text frontend/ src/ app/ features/ components/ lib/ api/ hooks/ types/ styles/ ``` 说明： - 第一阶段无需提前拆 package monorepo - 优先保证控制面信息架构与组件体系 - 不要为了“未来扩展”提前引入复杂前端工程编排 - 业务逻辑优先沉淀在 `features` - 通用组件与工具能力不得反向承载领域逻辑 ### 4.5 目录与边界约束 即使项目尚未初始化，也必须遵守以下约束： - 领域逻辑不得堆入 `common`、`utils`、`lib` 等模糊目录 - 不得以“先跑通”为借口，把认证、租户、权限、运行、观测逻辑混在一起 - 不得在未形成边界前就把目录结构设计成微服务形态 - 不得用前端页面目录直接承载 API 契约定义 - 不得让前端 feature 与后端领域命名长期失配 - 不得把临时目录结构当成最终结构长期保留 ### 4.6 初始化阶段允许的简化 在不破坏核心边界的前提下，初始化阶段允许以下简化： - 后端先单应用启动 - 前端先单应用启动 - 插件能力先保留接口与扩展点，不急于补全全部实现 - 个别模块先保留薄实现，但命名和边界要正确 - 局部功能先 stub/mock，但必须显式标注，不能伪装成正式实现 ### 4.7 初始化阶段禁止事项 在项目尚未初始化阶段，禁止： - 因为没有现成结构就把所有逻辑塞进一个 `common` 或 `utils` - 过早引入微服务目录布局 - 过早引入复杂 monorepo 工具链 - 过早抽出大量空壳模块 - 用临时目录结构替代正式模块边界思考 - 因“先快速生成代码”而放弃目录与职责约束 ### 4.8 最终判断标准 如果项目尚未初始化，AI 应优先问自己： 1. 这次初始化是否优先固定了逻辑边界，而不是物理复杂度？ 2. 这个目录设计是否有利于 MVP 快速落地？ 3. 这个结构是否便于后续演进，而不是提前引入微服务负担？ 4. 是否避免了把领域逻辑混入模糊公共目录？ 5. 前后端是否都保留了清晰、可持续扩展的边界？ 如果以上问题有两个以上答案是否定的，应先调整初始化方案，再继续实施。 --- ## 5. 任务分类与执行方式 每次任务必须先判断属于哪一类： ### A 类：低风险实现 例如： - 小范围 bugfix - 页面样式修正 - 非公共逻辑的小功能补全 - 测试补充 - 文案调整 - 局部日志增强 可直接实施，但仍需说明范围与验证方式。 ### B 类：中风险实现 例如： - 新增模块内接口 - 新增页面或详情页 - 新增状态分支 - Runtime 内局部行为调整 - Tool / Agent 的字段扩展 - SSE 事件消费增强 - 新增索引、缓存或查询优化 必须先给出局部计划，再实施。 ### C 类：高风险实现 例如： - 数据库 schema 变更 - 状态机变更 - 租户隔离逻辑调整 - 权限判定逻辑调整 - Agent 发布/回滚逻辑调整 - Tool 调用鉴权逻辑调整 - Executor 注册协议调整 - Run / Trace 数据模型调整 - 对外 API 契约调整 - 枚举 / 错误码 / 事件名变更 - 依赖升级或新增中间件 - 跨模块重构 - 公共基类修改 - 命名体系迁移 必须先停下，输出“变更计划 + 影响分析 + 验证方案”，在获得明确继续信号前，不得直接实施。 --- ## 6. AI 修改代码前必须遵守的步骤 每次开始任务前，至少完成以下动作： 1. 明确本次任务目标 2. 明确本次任务分类（A/B/C） 3. 明确本次改动范围 4. 标记不可修改区域 5. 列出计划修改的文件 6. 指出依赖哪些真源文档 7. 说明验证方式 8. 如为 B/C 类任务，先输出局部计划 禁止“顺手”做以下事情： - 无任务要求的大规模重构 - 跨模块重命名 - 批量迁移包结构 - 修改公共基类导致连锁影响 - 因主观偏好替换已有设计 - 借修 bug 顺带改协议 - 借样式优化顺带改交互语义 --- ## 7. 工具与命令优先原则 对于**可以通过命令、脚手架、构建工具、包管理器、代码生成器、测试命令、格式化工具、静态检查工具、数据库迁移工具或官方 CLI 稳定完成的工作**，AI 应优先使用这些可验证手段，而不是手工模拟结果或凭空生成“看起来像”的产物。 ### 7.1 默认原则 优先使用命令或工具的场景包括但不限于： - 初始化项目或子工程 - 安装、移除、升级依赖 - 生成脚手架代码 - 生成 API Client、类型定义、SDK、迁移文件 - 执行构建、测试、格式化、lint、静态检查 - 执行数据库迁移 - 执行代码生成器或协议生成器 - 执行官方推荐的初始化与校验流程 ### 7.2 禁止行为 禁止以下做法： - 明明可以通过稳定命令完成，却手工伪造初始化结果 - 明明需要安装依赖，却只修改清单文件而不执行必要安装步骤 - 明明可以通过生成器产出标准文件，却手写近似替代品 - 未运行构建/测试/格式化/静态检查，却默认认为结果正确 - 把“理论上应该可行”当成“已经完成并验证” ### 7.3 允许的例外 以下情况可不执行命令，但必须说明： - 当前环境不具备相应工具 - 网络、权限或沙箱限制导致命令不可执行 - 任务明确要求只给方案、不实际操作 - 执行代价过高且当前阶段只需提供草稿 此时必须明确说明： - 哪个命令或工具本应执行 - 为什么未执行 - 未执行带来的风险 - 后续建议如何补验证 ### 7.4 判断标准 如果一项工作存在“官方、稳定、可重复、可验证”的命令式做法，默认优先走命令式做法，而不是手工猜测。 --- ## 8. 停机点（必须先停下） 出现以下情况时，AI 必须暂停实现，先报告风险： - 真源文档之间冲突 - 文档与代码实现冲突 - 当前任务会破坏 API 兼容性 - 当前任务需要新增状态、枚举、错误码、事件名 - 当前任务会影响数据库表结构 - 当前任务需要修改权限模型或 tenant 传播规则 - 当前任务会改变 SSE 事件协议 - 当前任务会改变 Run / Trace 记录结构 - 当前任务需要跨前后端同时调整契约 - 当前任务涉及凭证、密钥、认证、审计链路 - 当前任务无法完成必要验证 此时不得直接“按经验继续写”。 --- ## 9. 模块边界约束 ### 9.1 Auth / Tenant / RBAC 这些模块属于平台骨架，必须长期保留。 最低要求： - 用户登录 - 当前租户上下文 - 用户-租户-角色关系 - 基础 RBAC（Admin / Developer / Viewer） - 审计可追责 禁止： - 为了简化演示而删除 tenant_id - 用“只做单用户版本”破坏未来边界 - 将权限判断散落到各处且无统一抽象 - 前端直接根据角色名硬编码页面权限结论 - 绕开 capability / permission 模型直接做隐藏按钮式权限 ### 9.2 Agent Registry 必须围绕“Agent 定义 + 版本 + 发布”设计。 至少保留： - Agent 元数据 - Agent 草稿 / 已发布版本 - 模型策略 - Tool allowlist - Prompt 模板或系统指令 - 发布 / 回滚基础能力 禁止： - 将 Agent 设计成只是一段随意字符串 - 绕过版本对象直接修改线上行为 - 让前端自己拼装发布态语义 ### 9.3 Tool Registry Tool 是项目核心资产模型。 必须支持的来源优先级： 1. Executor 暴露 2. HTTP / OpenAPI 适配 3. 后续扩展 Connector Tool 至少应具备： - 唯一标识 - 名称与描述 - 参数 Schema - 返回 Schema（可先弱约束） - 来源类型 - 可见性与权限控制 - 版本信息 禁止： - 把 Tool 调用写死在 Agent 逻辑里 - 把 Tool 只当作页面展示对象而无真实契约 - 在前后端各自维护两套 Tool 能力语义 - 让 `agent`、`runtime`、`executor` 直接依赖 `tool.mapper`、`tool.entity`、`tool.service.impl` - 让 `agent`、`runtime`、`executor` 直接依赖 `agentadmin-tool-support` 补充约束： - `module/tool` 是系统内唯一 Tool 治理归口 - `agentadmin-tool-support` 只承载 MCP / SYSTEM 的技术适配、动态发现与运行时绑定支撑 - 其他模块只能通过 `module/tool/application` 暴露的统一服务访问 Tool 能力 ### 9.4 Executor Registry Executor 是核心差异化能力之一。 必须优先支持： - Spring Boot Starter 方式接入 - 注册 - 心跳 - 状态同步 - 工具上报 - 基础健康检查 目标是： - 低侵入接入已有 Java 系统 - 尽量少改业务代码 - 不强迫业务方接受复杂基础设施改造 禁止： - 将 Executor 设计成必须依赖复杂注册中心 - 将业务系统接入改造成大规模侵入式改造 ### 9.5 Runtime Runtime 负责一次 Agent 运行的编排执行，不等于复杂工作流引擎。 第一版关注： - Agent 加载 - Tool allowlist 约束 - Prompt 组装 - 模型调用 - Tool 调用循环 - Session / Context 处理 - Run / Step / Event 记录 - SSE 输出 - 错误处理与重试边界 禁止： - 把第一版 Runtime 设计成重量级 DAG 引擎 - 在 Runtime 中偷塞前端展示语义 - 让运行态结构与观测结构完全脱节 ### 9.6 Observability / Audit 可观测性与审计不是附属品。 至少要支持： - 谁触发了运行 - 属于哪个租户 - 使用了哪个 Agent 版本 - 调用了哪些 Tool - 每一步状态如何 - 最终成功或失败原因 - 高风险操作的审计记录 第一版可先以 MySQL + 日志 + OpenTelemetry 为主，不要过早引入大规模日志分析基础设施。 ### 9.7 Frontend Control Plane 前端是控制面，不是聊天产品前台。 必须围绕： - 租户 - Agent - Tool - Executor - Run / Trace - 审计 - 设置 组织信息架构。 禁止： - 以聊天窗口作为全局主导航 - 优先实现节点画布 - 让页面结构偏向 demo 式单页体验 - 用过度动画影响信息效率 --- ## 10. 数据与存储约束 ### 10.1 MySQL 主要承载： - 用户、租户、角色关系 - Agent / Agent Version - Tool / Tool Version - Executor 元数据 - Run / Run Step / Event - Audit Log - 配置类对象 JSON 字段用于： - Tool Schema - Agent 配置快照 - Prompt 模板配置 - 运行上下文快照 - 扩展字段 禁止： - 结构化高频过滤字段只放 JSON - 把关键外键关系偷放扩展字段 - 用 JSON 替代本应独立建模的核心对象 ### 10.2 Redis 主要承载： - 会话缓存 - 临时上下文 - Executor 心跳状态 - 幂等键 - 短期令牌或限流辅助数据 禁止： - 在第一阶段把核心事实数据只放 Redis - 把 Redis 当作长期真源 ### 10.3 不要过度引入 没有明确需求时，不要引入： - 专用向量数据库 - ClickHouse - Elasticsearch - Kafka 作为前置依赖 这些仅在明确出现性能瓶颈、检索需求或日志规模压力后再引入。 --- ## 11. API、状态与兼容性约束 默认 API 风格： - REST 为主 - SSE 用于流式运行输出 - OpenAPI 文档自动生成 要求： - 对外接口命名清晰稳定 - 错误码和错误结构统一 - tenant 上下文来源明确 - capability 表达方式统一 - 分页、过滤、排序结构统一 - SSE 事件名、事件载荷、补拉规则统一 禁止： - 无说明地破坏现有接口契约 - 前后端各自扩展不同字段语义 - 跳过文档直接新增状态或错误码 - 在未同步规范时擅自改 enum / event / code 涉及以下变更时必须明确说明兼容性影响： - 字段删除或重命名 - 响应结构变化 - 鉴权方式变化 - 分页与过滤行为变化 - 事件名变化 - 状态枚举变化 - 错误码语义变化 --- ## 12. 测试与验证要求 AI 生成或修改代码后，至少应满足： 1. 能编译通过 2. 相关单元测试通过 3. 相关集成测试通过（如已有） 4. 不引入明显静态检查问题 5. 变更说明与实际改动一致 6. 文档受影响时已明确同步或标记待同步项 如任务涉及： - 权限 - 租户隔离 - Tool 调用 - Runtime 执行链路 - 发布 / 回滚 - 审计日志 - API 契约 - SSE 事件 - 状态流转 则优先补充测试，而不是只修改主逻辑。 如果无法执行测试，必须明确说明： - 哪些测试未执行 - 为什么未执行 - 风险在哪里 - 建议下一步验证什么 禁止在未说明风险的情况下声称“已完成”。 --- ## 13. 日志、观测与错误处理规范 ### 13.1 日志 日志应具备： - tenant_id - user_id（如有） - agent_id / version - run_id - executor_id（如适用） - trace_id / span_id（如适用） 禁止： - 打印明文密钥 - 打印敏感凭证 - 无边界输出完整上下文 - 用 debug 日志替代审计记录 ### 13.2 错误处理 要求： - 区分用户错误、配置错误、系统错误、外部依赖错误 - 异常信息可排障，但不能泄露敏感信息 - 对 Tool 调用失败、模型调用失败、Executor 不可用等情况给出清晰错误语义 不要： - 大量吞异常 - 模糊返回 - 用 200 + message 模拟失败 - 用前端兜底掩盖后端语义缺失 --- ## 14. 安全与审计约束 以下操作必须可审计： - 登录 - 租户切换 - Agent 发布 / 回滚 - Tool 可见性或权限变更 - 模型配置变更 - 高风险 Tool 调用 - Executor 注册与下线 - 权限授予与收回 - 关键配置修改 禁止： - 在代码中硬编码密钥 - 把凭证提交到仓库 - 省略高风险调用的审计链路 - 在前端持久化高敏感明文 - 通过日志回显敏感凭证 --- ## 15. 文档同步义务 以下变更完成后，必须检查是否需要同步真源文档： - 新增或修改接口 - 新增或修改实体 - 新增或修改状态机 - 新增或修改错误码 - 新增或修改事件名 - 新增或修改权限能力 - 新增或修改命名约定 - 新增或修改联调/验收方式 如果本次改动未同步文档，必须在结果中明确说明： - 哪份文档受影响 - 为什么本次未同步 - 应由谁在何时同步 禁止静默制造“代码新真相”。 --- ## 16. 前后端并行开发约束 前后端必须以接口契约和状态定义为协作边界。 禁止： - 前端绕过 API 规范自行发明字段 - 后端未出契约就要求前端猜结构 - 以后端临时返回为长期依据 - 用 mock 数据偷偷扩展未确认语义 允许： - 在契约已冻结时并行开发 - 在 Preview 能力下做有限前瞻实现 - 在明确标记的实验页面中做受控验证 涉及： - 接口字段变更 - 状态语义变更 - SSE 事件变更 - 错误码变更 必须回看： - `05-api-specification.md` - `07-enum-and-state-definitions.md` - `08-error-code-specification.md` - `10-frontend-backend-collaboration.md` --- ## 17. 对 Codex 的专门说明 本仓库优先适配 Codex 工作方式。 执行任务时，默认遵守以下方式： - 先读本文件，再开始实现 - 先读相关真源文档，再开始动手 - 先给出局部计划，再改代码 - 一次只解决一个明确任务 - 优先做小步、可验证改动 - 优先遵循现有代码风格与模块边界 - 不因“顺手”而扩大改动半径 - 输出必须包含验证结果与未验证风险 - 能用稳定命令或工具完成的事情，优先不要手工模拟 如存在更细粒度目录级 `AGENTS.md`，则子目录文件对该子树生效，应优先遵守。 如存在 `AGENTS.override.md`，则其优先级高于普通 `AGENTS.md`。 --- ## 18. 建议的输出与提交摘要格式 完成任务后，输出摘要时必须包含： 1. 本次改了什么 2. 为什么这样改 3. 涉及哪些模块 / 文件 4. 依赖了哪些真源文档 5. 风险点是什么 6. 执行了哪些验证 7. 哪些地方未验证 8. 是否需要同步文档 9. 是否影响以下边界： - 租户隔离 - 权限模型 - 对外接口契约 - 状态机 / 枚举 / 错误码 - 运行链路 / Trace / SSE 如果是高风险变更，还必须补充： - 兼容性影响 - 回滚思路 - 联调影响面 --- ## 19. 未满足这些条件，不得宣称完成 出现以下任一情况时，不得宣称“已完成”： - 未说明改动范围 - 未说明验证方式 - 高风险任务未先给计划 - 明知有文档冲突却未说明 - 改了接口却未说明兼容性 - 改了状态/错误码/事件却未同步规范或标记 - 未说明未验证部分 - 未说明风险 - 只完成代码生成，但未检查是否符合模块边界 可以说： - “已完成代码修改，但未完成验证” - “已完成局部实现，待联调确认” - “已完成草稿方案，待确认后实施” 禁止把“生成了一版代码”表述成“问题已解决”。 --- ## 20. 明确禁止事项 没有明确任务授权时，禁止： - 把项目改造成聊天产品 - 把项目改造成工作流画布平台 - 删除租户 / 权限 / 审计骨架 - 引入不必要的微服务化改造 - 引入重型中间件作为基础前提 - 擅自重写核心领域模型 - 为了短期演示牺牲长期边界 - 在未验证的情况下声称生产可用 - 让代码实现脱离真源文档自我扩张 - 把 demo 便捷性凌驾于平台边界之上 --- ## 21. 最终判断标准 每次改动前都先问： 1. 这是否强化了 AgentAdmin 作为 Java Agent 基础设施的定位？ 2. 这是否让 Java 团队更容易接入，而不是更难？ 3. 这是否保持了模块化单体与双平面边界？ 4. 这是否保留了租户、权限、审计、观测骨架？ 5. 这是否符合真源文档？ 6. 这是否属于 MVP 真正需要的能力？ 7. 这是否在可验证范围内完成？ 如果以上问题有两个以上答案是否定的，就不要继续实现，先调整方案。