# Agent 开发与交付实践

本文是 hyb-oa 使用 AI agent 协作开发的项目级事实源。目标不是追求复杂编排，而是把高频、易出错、需要验证的流程固定下来，让后续交付可复现、可审计、可回滚。

## 来源

- OpenAI Codex Skills: https://developers.openai.com/codex/skills/
- OpenAI Agents 文档: https://platform.openai.com/docs/guides/agents
- OpenAI Evals 文档: https://platform.openai.com/docs/guides/evals
- Anthropic Building Effective Agents: https://www.anthropic.com/engineering/building-effective-agents
- Google Agent Development Kit 文档: https://google.github.io/adk-docs/

## 本项目采用的原则

### 1. 先简单、后编排

默认由主 agent 在当前上下文内完成计划、实现、验证和提交。只有当任务能明确拆分、文件写入范围互不冲突、并且并行能实质缩短关键路径时，才使用子 agent。

不为了“多 agent”而多 agent。复杂编排的收益必须超过上下文丢失、沟通成本和合并风险。

### 2. Issue CSV 是执行合同

所有非微小改动先进入 `issues/*.csv`，再实施。Issue 必须写清：

- 业务流程级影响，不只写文件路径。
- 验收标准，不只写“完成开发”。
- 可执行验证命令或可复现手工步骤。
- 数据迁移、权限、状态机、审批规则的回滚策略。

### 3. Skill 只沉淀操作流程

Skill 用于减少重复沟通和降低遗漏风险，适合沉淀：

- 每轮交付固定流程。
- 试运行和验证顺序。
- Playwright 视觉巡检要求。
- 报销、发票、企业微信等高频业务的检查入口。

Skill 不复制长文档。详细规则放在 `docs/`，Skill 通过 references 指向需要时再读取。

### 4. 文档保存事实源

项目事实源应随仓库版本管理：

- 设计事实源：`docs/product-design-rules.md`
- 报销发票规则：`docs/reimbursement-invoice-rules.md`
- 试运行 Runbook：`docs/trialrun-runbook.md`
- Agent 交付实践：`docs/agent-development-practices.md`

AGENTS.md 只放硬约束和入口，不复制长规则。

### 5. 工具调用必须可验证

优先使用确定性命令和项目已有脚本：

- 后端：`npm run prisma:validate`、`node --check`、相关 Vitest、回归脚本。
- 前端：`npm run typecheck`、`npm run build`。
- 视觉：Playwright PC、mobile、WeCom UA 截图和 DOM 指标。
- 文档/Skill：CSV validator、Skill quick_validate、`git diff --check`。

验证失败时先定位是代码问题、测试桩问题、环境问题还是数据问题。数据库迁移漂移、生产配置、远程服务变更属于高风险操作，必须暂停确认。

### 6. 视觉和业务同时验收

本项目是面向 10 人以下国内科技公司的轻 OA，不只看功能能否跑通，也要看：

- PC 和手机能力是否一致。
- 企业微信入口是否保持登录态和移动布局。
- 页面是否符合 `www.hyinda.com` 的品牌气质。
- 文案是否符合国内 OA 习惯。
- 是否出现 PC 表格误入手机、黑色大块导航、按钮样式不一致、文字截断、弹窗自动弹键盘等明显问题。

### 7. 提交要小批次、中文、可回滚

一次需求可以有多个 commit，但每个 commit 应该能说明一个清晰主题：

- 计划和文档。
- 后端规则和接口。
- 前端体验。
- 测试和视觉验证。

commit message 使用中文并引用 Issue ID，例如 `R121/A1-A3 沉淀交付事实源`。

## 何时更新本文件

当连续两轮以上重复提醒同一类 agent 行为，或者同一类遗漏导致返工时，先判断：

- 是项目事实源：更新 `docs/`。
- 是每轮操作流程：更新 `.agents/skills/hyb-oa-delivery/`。
- 是不可违反硬规则：更新 `AGENTS.md`。