78 行
5.3 KiB
Markdown
78 行
5.3 KiB
Markdown
# AGENTS
|
||
|
||
> Purpose: 以官方 Trellis task 为执行合同，驱动 hyb-oa 后续开发、验证和复盘。
|
||
|
||
## Trellis-first 入口
|
||
|
||
- 开始任何非微小开发、审查、测试或文档治理任务前，先读 `.trellis/workflow.md`。
|
||
- Trellis task 是后续需求拆解、执行、验证和复盘的执行合同；新任务不再强制绑定 `issues/*.csv`。
|
||
- `prd.md` 是任务需求和验收入口；复杂任务补 `design.md` 或 `implement.md`；`implement.jsonl` / `check.jsonl` 只登记稳定 spec 或 research 上下文。
|
||
- `issues/*.csv` 保留为历史审计材料或特殊外部交付导出格式，不再作为新开发的默认前置合同。
|
||
- `docs/` 仍是业务事实源；Trellis spec 沉淀开发流程和高频工程规则。
|
||
|
||
## 不可违反约束
|
||
|
||
- 编码前先方案：非微小改动必须先给实现方案并等待批准。
|
||
- 先有 Trellis task 再开发：非微小改动必须先创建或更新 `.trellis/tasks/<task>/`。
|
||
- 计划工具约束：使用 Codex 原生 `update_plan` 做执行清单，不用外部自定义 plan 替代。
|
||
- Trellis-only：hyb-oa 交付、试运行、视觉复核、报销/OCR/附件、企业微信或部署类任务统一从当前 Trellis task、`.trellis/workflow.md`、`.trellis/spec/hyb-oa/` 和 `docs/` 组织上下文。
|
||
- 中文沟通；commit message 使用中文并引用 Trellis task 名称或任务 ID。
|
||
- 不泄露密码、token、Secret、真实票据、合同正文、银行资料、完整账号、完整本地路径或原始 payload。
|
||
- 不轻易新建文档；优先更新现有事实源、模块规约、操作手册、证据文档或当前 Trellis task。
|
||
- 页面视觉与交互设计以 `frontend-design` skill 为准；`docs/产品设计规则.md` 仅保留业务体验事实、信息架构和验收边界。
|
||
- 面向用户可测试的改动，只有部署与公网检查通过后才能告知用户可以测试。
|
||
|
||
## 当前项目事实源
|
||
|
||
- 文档入口与状态：`docs/文档索引.md`、`docs/文档事实源状态矩阵.md`
|
||
- Agent/Trellis 交付实践：`docs/Agent开发交付实践.md`
|
||
- 产品体验事实源：`docs/产品设计规则.md`（视觉裁决以 `frontend-design` skill 为准）
|
||
- 报销、发票、OCR、附件规则：`docs/报销发票附件规则.md`
|
||
- 试运行与自动化验证：`docs/试运行与自动化验证手册.md`
|
||
- Trellis workflow：`.trellis/workflow.md`
|
||
- Trellis project specs：`.trellis/spec/hyb-oa/`
|
||
|
||
## 技术栈与验证
|
||
|
||
- Backend: `server/`（Node.js + Fastify + Prisma + PostgreSQL）。
|
||
- Frontend: `client/`（React + TypeScript + Vite + Tailwind）。
|
||
- 核心后端验证：`cd server && npm run prisma:validate`，必要时运行相关 `node --check`、Vitest 和回归脚本。
|
||
- 核心前端验证：`cd client && npm run typecheck && npm run build`。
|
||
- 文档/流程验证：`validate_issues_csv.py`、`node scripts/qa/check-process-contract.mjs --baseline --json`、`node scripts/qa/audit-docs.mjs --check-registry`、`node scripts/qa/check-trellis-governance.mjs`、`git diff --check`。
|
||
|
||
## Trellis 使用边界
|
||
|
||
- `.trellis/workspace/` 为本地个人日志，默认不提交；需要沉淀的经验应脱敏后写入 `.trellis/spec/`、`docs/` 或当前 Trellis task。
|
||
- `.trellis/config.yaml` 固定 `session_auto_commit: false`；Trellis 不得自动提交。
|
||
- 当前仅启用 Codex 适配；不把 Cursor/Claude/其他平台迁移作为本轮默认范围。
|
||
- Codex hooks 文件可以存在，但只有用户级配置和 `/hooks` 审核启用后才生效；本项目不把 hook 自动注入作为验收前提。
|
||
|
||
## 编排规则
|
||
|
||
- 默认按 Trellis workflow 执行：task/prd -> design/implement notes（按需） -> implement -> check -> spec/docs update -> commit -> finish。
|
||
- 涉及权限模型、状态机、workflow、数据迁移、审批规则时，实施后必须启动只读 review，不让 reviewer 改代码。
|
||
- 公网部署、生产配置、真实数据写入、数据库重置、企业微信写入和真实付款必须另行获得明确批准。
|
||
- 若 Trellis 规则与业务文档冲突：当前 Trellis task PRD/设计 > 当前模块规约 > 业务规约和 `docs/产品设计规则.md` 中的体验事实 > Trellis spec > 历史证据；前端视觉裁决优先使用 `frontend-design` skill，历史 Issue CSV 只用于追溯。
|
||
|
||
<!-- TRELLIS:START -->
|
||
# Trellis Instructions
|
||
|
||
These instructions are for AI assistants working in this project.
|
||
|
||
This project is managed by Trellis. The working knowledge you need lives under `.trellis/`:
|
||
|
||
- `.trellis/workflow.md` — development phases, when to create tasks, skill routing
|
||
- `.trellis/spec/` — package- and layer-scoped coding guidelines (read before writing code in a given layer)
|
||
- `.trellis/workspace/` — per-developer journals and session traces
|
||
- `.trellis/tasks/` — active and archived tasks (PRDs, research, jsonl context)
|
||
|
||
If a Trellis command is available on your platform (e.g. `/trellis:finish-work`, `/trellis:continue`), prefer it over manual steps. Not every platform exposes every command.
|
||
|
||
If you're using Codex or another agent-capable tool, additional project-scoped helpers may live in:
|
||
- `.agents/skills/` — reusable Trellis skills
|
||
- `.codex/agents/` — optional custom subagents
|
||
|
||
Managed by Trellis. Edits outside this block are preserved; edits inside may be overwritten by a future `trellis update`.
|
||
|
||
<!-- TRELLIS:END -->
|