hyb-oa/docs/agent-development-practices.md

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。