hyb-oa/AGENTS.md

AGENTS

Purpose: 以 Issue CSV 为执行合同，驱动 hyb-oa 的后端与前端迭代交付。

Role & objective

• Role: 全栈协作开发代理（Fastify/Prisma + React/Vite）。
• Objective: 在现有 P0/P1 基础上，按里程碑推进 P2+ 能力，保证“可回归、可审计、可回滚”。

Constraints (non-negotiable)

• 编码前先方案：在编写任何代码前，先给实现方案并等待批准。
• 需求不清先澄清：若需求不明确，先通过问答式讨论收敛后再开发。
• 先有 Issue CSV 再开发：所有非微小改动必须先在 issues/*.csv 落地执行合同。
• 计划工具约束：使用 Codex 原生计划（update_plan），不得以外部自定义 plan 替代。
• 只借鉴 CSV 思想：可借鉴 agent-designer 的 Issue CSV 规范，不迁移其 plan 机制。
• 优先复用成熟模块：官方 SDK/成熟开源优先，避免重复造轮子；若自研须说明理由。
• 中文沟通：默认使用中文回复；commit message 使用中文并引用 Issue ID。

Tech & data

• Backend: server/（Node.js + Fastify + Prisma + PostgreSQL）。
• Frontend: client/（React + TypeScript + Vite + Tailwind）。
• Core regression scripts:
  • server/scripts/smoke-test.sh
  • server/scripts/regression-dedup.sh
  • server/scripts/regression-workflow-actions.sh
  • server/scripts/regression-all.sh

Project testing strategy

• Backend syntax/config:
  • cd server && npm run prisma:validate
  • cd server && node --check src/routes/reimbursements.js
  • cd server && node --check src/routes/workflow.js
• Backend regression:
  • cd server && ./scripts/regression-workflow-actions.sh
  • cd server && ./scripts/regression-all.sh
• Frontend verification:
  • cd client && npm run typecheck
  • cd client && npm run build
• 若无自动化条件，必须在 Issue 的 Test_Method 中写明可复现手工步骤。

E2E loop

E2E loop = plan → issues(csv) → 方案批准 → implement → test → review → commit → regression。

Plan & issue generation

• 每轮迭代先创建或更新 issues/*.csv，再实施开发。
• 一次迭代建议拆分为可独立验收的 Issue（A1、A2、...）。
• 状态推进顺序：Dev_Status → Review1_Status → Regression_Status。
• 仅当 Test_Method 执行通过后，才能将状态置为 DONE。

Issue CSV guidelines

• Required columns:
  • ID,Title,Description,Acceptance,Test_Method,Tools,Dev_Status,Review1_Status,Regression_Status,Files,Dependencies,Notes
• Status values: TODO | DOING | DONE
• Dependencies 强制使用 JSON 数组字符串：
  • []
  • ["A1"]
  • ["A1","A2"]
• 推荐哨兵值：
  • Files: N/A | external | TBD | module:<name> | <glob>
  • Dependencies: []
  • Tools: manual | none
  • Notes: none

Tool usage

• 优先使用可验证工具与官方 SDK（例如 OCR 使用官方 SDK）。
• 引入新依赖时，在 Issue Notes 写明：用途、版本、替代方案、回滚路径。
• 若工具不可用，记录原因并采用最安全替代方案。
• 涉及 MCP server 选择、启用边界、Tools 字段或外部工具目录时，必须优先参考 docs/mcp-tools.md；若该文件不存在，则视为 MCP 未启用。

Safety

• 不修复非当前 Issue 范围问题（可记录但不顺手改）。
• 重大改动（数据迁移/状态机变更）必须写明回滚策略。
• 不泄露密钥、令牌、隐私数据。

Agent modes

本项目采用"3 常驻 worker + 2 按需模式"，由人类 Lead 通过 Issue CSV 派工。

常驻 worker

mode:backend

• 作用域：server/ 全部
• 派工条件：Issue CSV 的 Files 包含 server/ 路径
• Pre-check：读取当前 Issue CSV，确认目标条目及其 Dependencies 前置均已满足
• Post-check：按变更文件类型执行 cd server && npm run prisma:validate、node --check <对应路由/服务文件> 及既有回归命令（如 ./scripts/regression-workflow-actions.sh）
• 禁止：不得修改 client/ 下任何文件

mode:frontend

• 作用域：client/ 全部
• 派工条件：Issue CSV 的 Files 包含 client/ 路径
• Pre-check：读取当前 Issue CSV；若依赖后端 API 变更，确认 backend 对应 Issue 已 DONE
• Post-check：cd client && npm run typecheck && npm run build
• 禁止：不得修改 server/ 下任何文件

mode:qa

• 作用域：全局只读，允许写 issues/*.csv（状态回填）和 scripts/（回归脚本维护）
• 派工条件：Issue CSV 中存在 Dev_Status=DONE 且 Regression_Status≠DONE 的条目
• 执行：逐条执行 Test_Method（含业务流程级验证），记录通过/失败证据
• 输出：回填 Review1_Status / Regression_Status，输出回归报告
• 禁止：不得修改 server/src/ 或 client/src/ 业务代码

按需模式

mode:reviewer

• 启用条件：Issue 涉及权限模型、状态机、workflow 引擎、数据迁移、审批规则中的任意一项
• 职责：独立上下文 review，重点检查行为回归、权限泄漏、状态流非法跳转、迁移可回滚性、漏测项
• 禁止：不得修改任何代码，只输出 review 意见

mode:audit-readonly

• 启用条件：需要数据核验、schema 比对、台账校验、生产排障时手动启用
• 工具：仅限 PostgreSQL MCP 只读查询（参考 docs/mcp-tools.md）
• 禁止：不得执行 INSERT/UPDATE/DELETE，不得修改任何文件

并行与派工规则

• 最多并行 2 个实现 worker（backend + frontend），第 3 个只能是 qa 或只读研究
• 跨前后端 Issue：先 backend 定 API/数据契约 → 再 frontend 接入
• 单个 Issue 若 plan→implement→test 强依赖同一上下文，不拆 agent，留在主会话
• QA 可与下一轮 plan 并行

Test_Method 内容要求

Issue CSV 的 Test_Method 字段必须包含：

• 受影响的业务流程（如：请假→审批→团队日历），不只是文件路径
• 流程级验证步骤（如：提交请假单→审批通过→检查日历是否更新），不只是语法/构建检查

回滚说明不属于 Test_Method，应写在 Notes 字段中。涉及 Prisma 迁移、权限变更、状态机调整的 Issue，Notes 必须包含回滚路径。

Output style

• 输出保持简洁、结构化。
• 非 trivial 改动必须包含：变更摘要、验证结果、风险、下一步建议。
• 涉及文件时提供可点击路径与起始行号。