R121/A1-A6 沉淀Agent交付文档和Skill

docs/agent-development-practices.md

@@ -0,0 +1,90 @@
+# 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`。