57 lines
6.6 KiB
Markdown
57 lines
6.6 KiB
Markdown
# AI 工程执行与协作约束
|
|
|
|
## 读取条件
|
|
|
|
- 运行、构建、依赖、临时目录、工作树、部署、数据库、跨模块改动或独立任务协作时读取本文件。
|
|
- 普通代码定位仍先按根 `AGENTS.md` 的项目和业务路由进入最近的项目/模块指引；本文件不替代业务索引。
|
|
|
|
## 根目录、临时目录与依赖复用
|
|
|
|
- 根目录只保留 `apps/` 前端应用、`baiyue-firstleg/` 后端独立仓库、`docs/` 产品与契约文档三类业务事实来源；新增业务源码或服务不得直接放在根目录。
|
|
- `.vscode/`、`.impeccable/`、`.superpowers/` 和根 `.codex-temp/` 属于本地工具或缓存，不作为业务入口；根 `.codex-temp/` 不得存放项目副本。
|
|
- `output/`、`outputs/`、`dist/`、`target/`、日志和临时文件属于生成物，不纳入索引；空的临时产物目录应及时清理。
|
|
- 启动服务、测试、类型检查和构建默认直接在目标项目目录执行，并复用现有 `node_modules/`、Maven 本地仓库及其他依赖缓存；不得仅为运行或验证创建 `.codex-temp/<task>`、`.codex-tmp/<task>` 或完整项目副本。
|
|
- 不得复制、移动或手工链接现有 `node_modules/` 到临时目录。依赖缺失或锁文件变化时，在目标项目执行其声明的安装命令。
|
|
- 当前开发阶段不得因小功能、缺陷修复、联调、测试、构建、端口冲突、未提交修改或希望获得“干净目录”而创建 `wk`/Git worktree、临时分支或项目副本；统一直接在当前工作区、当前分支修改和验证，不得自行创建或切换分支。
|
|
- 只有用户在当前轮明确要求隔离分支或 worktree 时才可例外。例外时必须先说明原因、精确位置和清理条件，放在目标项目之外；任务结束且无进程占用后立即清理。
|
|
- 禁止在 `apps/*/`、`baiyue-firstleg/` 及业务模块内部新增 `.codex-temp/`、`.codex-tmp/`、`worktree/` 或类似项目副本。遗留目录须先确认没有运行进程和唯一证据，再按精确路径清理。
|
|
- 端口冲突通过停止已知旧进程或指定其他端口解决，不得复制项目。普通验证应直接覆盖当前未提交修改，不为获得“干净目录”绕开真实变更。
|
|
|
|
## 当前开发阶段
|
|
|
|
- 项目尚未上线，没有需要兼容的生产存量数据、线上客户端或已发布接口版本；用户确认上线后应重新建立版本兼容和升级规则。
|
|
- 对已确认目标直接收敛实现、接口、状态、权限、OpenAPI、前端消费者和初始化 SQL；旧实现冲突时直接修改或移除，不默认保留旧字段、接口、权限、状态或行为的兼容分支。
|
|
- 当前不设计数据迁移、双写、灰度、回滚版本、旧客户端兼容或新旧协议并行，也不为历史开发数据新增迁移脚本；数据库结构以最新完整初始化 SQL 为准。
|
|
- 已有历史 SQL 只用于开发追溯，不构成兼容依据；后端位于独立 Git 仓库 `../baiyue-firstleg/`，执行 Git 命令前确认当前工作目录。
|
|
- “无需兼容和迁移”不授权自动重置数据库、删除数据、执行 SQL 或部署环境。
|
|
|
|
## 联调、部署与数据库
|
|
|
|
- 默认只准备代码、验证结果和人工部署步骤，不触发 Jenkins、不启动本地 Java/Nacos/数据库，也不修改测试环境数据。
|
|
- 只有用户在当前轮明确授权指定环境、服务和提交时，才可部署或执行 HTTP 验收；测试环境数据库默认只读。
|
|
- 环境地址、凭据和 Token 不写入源码或 `AGENTS.md`。接口不可用或契约不一致时记录路径、状态、错误码、`requestId`/`traceId` 和阻断原因，不回退到模拟成功。
|
|
- 具体联调脚本、服务启动和验收命令以目标项目指引及 `测试环境Jenkins部署指南.md` 为准。
|
|
|
|
## 通用工程与质量门禁
|
|
|
|
- 保持变更小而聚焦，遵循目标项目现有命名、分层和格式，不顺手重构无关代码。
|
|
- 优先复用现有依赖和公共能力；新增或升级依赖前说明必要性、影响范围和替代方案。
|
|
- 不提交依赖目录、构建产物、运行日志、编辑器缓存或本地临时文件；不写入密钥、令牌、真实客户数据或环境特定地址。
|
|
- 用户可见文案保持清晰一致；代码标识符使用英文，业务说明和文档可使用中文。
|
|
- 仅运行目标项目实际声明的安装、检查、测试和构建命令。每次变更至少验证直接受影响的项目，跨项目变更还要验证对应消费者。
|
|
- 修改方法、构造器、组件 Props、函数、接口、DTO 或请求/响应参数时，定向检索全部生产调用、测试调用、Mock、Fixture、契约测试和脚本引用，并同步修改。
|
|
- 参数或类型签名变化必须运行会编译测试源码的最小检查；无法验证时明确列出未验证范围。
|
|
- 修复缺陷优先增加复现测试；没有现成测试设施时不为小改动引入整套框架，应记录验证步骤和剩余风险。
|
|
- UI 变更按受影响范围检查加载、空态、错误态、权限、目标视口和可访问性；Admin/Client 视觉细则查 `Admin-Client前端原型还原验收规则.md` 和目标应用指引。
|
|
- 需求、技术栈或接口未确认时停在可逆设计阶段，不自行作出高成本平台决策。
|
|
|
|
## 独立任务与多任务协作
|
|
|
|
- 普通任务不读取协作登记。只有用户明确指定当前对话为总控，或要求检索历史任务、独立任务或跨对话通信时，才读取 `独立任务协作登记.md`。
|
|
- 检索历史任务只使用本机 `~/.codex/session_index.jsonl`、`~/.codex/state_5.sqlite`、`~/.codex/sessions/` 和已知本地任务，不依赖聚合本地、远程主机或云端对话的列表接口。
|
|
- 被指定为总控只授权规划、拆解、协调和复用已登记任务，不授权创建新的用户可见独立任务；临时并行默认使用当前对话或内部子代理。
|
|
- 创建用户可见独立任务必须由用户在当前轮明确要求，并确认精确数量、稳定职责和所属总控；历史授权以及“继续处理”“拆分”“安排”“并行”等表述不构成创建授权。
|
|
- 创建前必须查询登记表并优先复用职责匹配的 `task_id`；一次性缺陷、排障、部署、临时验收和只为提速的并行工作不得登记为长期任务。
|
|
- 创建成功后先登记稳定 `task_id`、所属总控和唯一长期职责，再下发工作；不自动创建替代任务或归档、解档、恢复、迁移任务。
|
|
- 并行前明确文件归属和共享契约。共享导航、根路由、权限初始化和统一 SQL 由已登记的对应总控统一集成；发生重叠时保留现有改动并跨任务协调。
|