# 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` 写明：用途、版本、替代方案、回滚路径。
- 若工具不可用，记录原因并采用最安全替代方案。

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

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