77 行
3.5 KiB
Markdown
77 行
3.5 KiB
Markdown
# 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 改动必须包含：变更摘要、验证结果、风险、下一步建议。
|
||
- 涉及文件时提供可点击路径与起始行号。
|