AGENTS

Purpose: 以官方 Trellis task 为执行合同，驱动 hyb-oa 后续开发、验证和复盘。

Trellis-first 入口

非微小任务先读 .trellis/workflow.md 的阶段索引和当前步骤，按需读取关联规约；本会话已读且未变化的资料不重复通读。纯咨询与小改不默认建 task。
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>/。
执行清单优先使用可用的原生 update_plan；不可用时用当前任务已有 implement.md，小改可在回复记录，不另建计划系统或因此停工。
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 改代码。
公网部署、生产配置、真实数据写入、数据库重置、企业微信写入和真实付款必须另行获得明确批准。
独立复核受工具或 inline 模式限制时，完成可执行的验证并明确标记待独立复核，不虚报通过或反复索取同一授权。提交、推送、归档必须有明确授权；阶段完成不等于整个任务完成。
若 Trellis 规则与业务文档冲突：当前 Trellis task PRD/设计 > 当前模块规约 > 业务规约和 docs/产品设计规则.md 中的体验事实 > Trellis spec > 历史证据；前端视觉裁决优先使用 frontend-design skill，历史 Issue CSV 只用于追溯。

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.

5.9 KiB 原始文件 Blame 文件历史 Unescape Escape