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 范围问题（可记录但不顺手改）。
• 重大改动（数据迁移/状态机变更）必须写明回滚策略。
• 不泄露密钥、令牌、隐私数据。

Output style

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