yuxuanhui
127 lines
9.3 KiB
Markdown
127 lines
9.3 KiB
Markdown
# 全局 Agent 规则
|
||
|
||
以下是本机 Codex 的个人工作约定；系统、开发者、项目级 `AGENTS.md` 和当前用户明确要求始终优先。
|
||
|
||
## 个人偏好
|
||
|
||
- 默认使用简体中文；代码标识符、命令、配置键和路径保持原文。
|
||
- 结论先行；以当前机器、仓库、会话和真实运行结果为准。
|
||
- 默认做最小充分实现，不扩张范围，不覆盖、还原或提交用户已有改动。
|
||
- 最终答复只保留结论、关键证据、实际验证、剩余风险和必要下一步。
|
||
|
||
## 授权边界
|
||
|
||
- 用户只要求回答、解释、分析、诊断、review 或规划时，只读检查并报告；不得修改产品代码或外部状态。
|
||
- 用户明确要求修改、实现、构建或修复时，完成范围内本地改动和非破坏性验证，不重复索要实现确认。
|
||
- 外部系统写入、发送、发布、破坏性操作、付费、权限变更和实质扩张范围前必须确认。
|
||
- Review-only 只报告 findings；只有用户同时要求修复时才修改代码。
|
||
- Diagnosis-only 交付根因、证据和建议；只有用户同时要求修复时才实现。
|
||
- 没有直接验证证据时，不声称完成、通过、可提交或可合并。
|
||
|
||
## 任务分流
|
||
|
||
分流由本文件与项目 `.trellis/workflow.md` 共同决定，顺序如下：
|
||
|
||
1. 当前用户明确指定的 workflow 或 skill。
|
||
2. 明确属于 Inline 的简单任务。
|
||
3. 非简单但能在单会话完成的工程任务，使用当前最匹配的 Matt 方法。
|
||
4. 已有 `.trellis/` 且任务需要跨会话、多项稳定决策、多交付物或 durable research 时，进入 Trellis 生命周期并在其中使用 Matt 方法。
|
||
|
||
### Inline
|
||
|
||
以下任务直接处理，不创建 Trellis task：
|
||
|
||
- 一轮可完成的问答、解释、代码阅读；
|
||
- 局部配置、文案或单文件修改；
|
||
- 根因明确的小修；
|
||
- 影响范围窄、没有需要持久化的设计决策；
|
||
- 当前上下文内可以完成最小验证。
|
||
|
||
### Matt
|
||
|
||
- 按当前可用 skill 的 `description` 路由，不在全局规则复制完整 skill 清单。
|
||
- 用户明确点名且可用的 skill 优先；多个匹配时选范围最窄的一个。
|
||
- 用户要求 `/tdd`、test-first、red-green-refactor 或 integration tests 时使用 `/tdd`，并先确认要测试的公开 seam。
|
||
- 没有精确匹配时由主会话执行标准闭环：证据 → 决策/计划 → 执行 → 验证。
|
||
- 所选 skill 的流程门禁有效，但不得扩大当前用户授权。
|
||
|
||
### Trellis + Matt
|
||
|
||
- Trellis 只管理 task 状态、planning artifacts、research、checkpoint、跨会话恢复和 archive。
|
||
- Matt 只提供当前阶段的工程方法；一个阶段只保留一个 method owner。
|
||
- Phase 1 不使用 `trellis-brainstorm`：主会话先基于证据形成 task artifacts。普通 task 用 `grill-with-docs` review spec；已绑定并审批过的 Feishu Spec/Tickets 先做 source snapshot 一致性检查，只对 task 新增的 decision-bearing delta 使用 `grill-with-docs`。
|
||
- Phase 2 不使用原生 `trellis-implement`：由 `trellis-matt-implement` sub-agent 按已记录的 `standard|tdd` mode 执行；agent 不可用时由主会话按同一 mode fallback。
|
||
- Trellis 详细 phase、breadcrumb、恢复和归档命令以项目 `.trellis/workflow.md` 为准。
|
||
- 简单工作不建 task；项目没有 `.trellis/` 时不主动初始化，除非用户明确要求长期记录或初始化。
|
||
|
||
## Planning 方法
|
||
|
||
- Trellis task 的 `prd.md`、条件性的 `design.md` 和 `implement.md` 是 task-level spec source of truth。
|
||
- Planning artifacts 初稿应来自代码、测试、配置、文档和 task history 等证据。
|
||
- Feishu-bound task 的 Wiki Spec/Base Tickets 继续拥有产品需求、验收和关系事实；Trellis artifacts 只是执行 snapshot 与 task-local planning，不得成为第二份业务 Spec。
|
||
- 每个 Trellis implementation task 在 `prd.md` 的 `Testing Strategy` 记录 `Implementation Mode: standard|tdd`；默认 `standard`。
|
||
- 用户要求 `/tdd`、test-first、red-green-refactor、integration tests 或 reviewed spec 明确要求 TDD 时记录 `tdd`，并在进入执行前确认公开测试 seam。
|
||
- 未绑定外部已审批 Spec 时，使用 `grill-with-docs` 逐项 review 产品、范围、UX、兼容、风险、验收和关键设计决策。
|
||
- Feishu-bound task 若 snapshot 与已审批来源一致且没有新增决策，只做机械一致性检查；若 task-local planning 新增兼容、迁移、rollout/rollback、安全或执行顺序等决策，只 review delta；若改变产品需求、验收、Ticket 身份或 blocker 语义，先回写并重新批准 owning Feishu artifact。
|
||
- 一次只问一个问题；先查环境事实，只把真正属于用户的决策交给用户。
|
||
- 每个答案确认后立即同步回 owning Trellis artifact。
|
||
- `CONTEXT.md` 只保存稳定领域术语；ADR 只保存难以逆转、反直觉且经过真实取舍的决策，不复制 task spec。
|
||
- `grill-with-docs` wrapper 不可加载时，使用 `grilling` + `domain-modeling` 的等价组合。
|
||
- 用户确认 shared understanding 后，视为 spec review 完成；不再增加独立的 Trellis implementation approval。
|
||
|
||
## Implementation 方法
|
||
|
||
- 以 review 完成的 Trellis artifacts 或当前 spec/tickets 作为实现输入。
|
||
- Matt 单会话任务由主会话执行 implementation contract；Trellis Phase 2 由主会话派发 `trellis-matt-implement` 执行被委派的实现切片。
|
||
- `trellis-matt-implement` 是 execution role，不在 sub-agent 内调用 Matt `/implement` wrapper；每个实现切片只有一个 method owner。
|
||
- Dispatch prompt 必须包含 `Active task: <task-path>`、`Implementation mode: standard|tdd` 和 confirmed TDD seams；agent 按 `implement.jsonl`（如有真实条目）→ `prd.md` → `design.md`（如有）→ `implement.md`（如有）读取上下文。
|
||
- `standard` 是默认模式：先完成最小、连贯的实现增量，再运行单测试文件、受影响 type-check 等窄反馈，并在行为存在后按需补充验收/回归测试。
|
||
- `tdd` 只在用户触发且公开 seam 已确认时启用：显式加载 `/tdd`，按一个 failing behavioral test → 最小 green implementation 的 vertical slice 循环。
|
||
- TDD seam 未确认或 `/tdd` 不可加载时返回 `blocked`，不得自行选择、推断或静默降级模式。
|
||
- TDD red → green loop 内不做无关 refactor；refactor 留到主会话最终 review，之后重跑行为测试和完整适用验证。
|
||
- 两种模式结束时都运行完整适用验证。
|
||
- Sub-agent 不修改 Trellis task 状态、requirements 或 acceptance criteria，不执行 Git 写操作，也不派发其他 agent。
|
||
- Sub-agent 返回后由主会话检查完整 diff、同步 checkpoint，并按当前可用 review skill 的 `description` 完成最终 review 和 acceptance；该 skill 明确要求并行时可以使用子 agent。
|
||
- Matt `implement` 中无条件 commit 的步骤不适用；commit 仍由下方版本控制规则约束。
|
||
|
||
## Codex 执行方式
|
||
|
||
- 默认由主会话完成探索、规划、检查和验收；Trellis Phase 2 是明确例外，由当前 workflow 派发 `trellis-matt-implement` 完成实现切片。
|
||
- 默认只派发一个 `trellis-matt-implement`；只有独立 child task 或写入范围完全分离时，才按 workflow/skill 的明确要求并行。
|
||
- 不因为 Trellis 的默认 dispatch banner 自动派发原生 `trellis-implement`。
|
||
- `trellis-matt-implement` 不可用、无法可靠加载 task context 或平台不支持 custom sub-agent 时，由主会话按已记录 mode fallback：`standard` 使用 Matt 适配契约，`tdd` 显式加载 `/tdd`。
|
||
- 子 agent 只拥有被委派的窄任务；主会话负责范围、整合、验收和用户沟通。
|
||
|
||
## Spec 与经验提升
|
||
|
||
- 每个任务都可以判断是否产生了值得提升的知识，但默认不执行 promotion。
|
||
- 只有知识稳定、可复用、已经验证且用户明确确认后，才写入 `.trellis/spec/`、全局规则、skill、hook、test、script 或跨项目知识库。
|
||
- 未满足条件的内容保留在当前 task 的 design/research/retrospective，或在最终答复中列为 candidate。
|
||
|
||
## 工具与代码约定
|
||
|
||
- 搜索文件和文本优先使用 `rg` / `rg --files`。
|
||
- 当前项目存在 `.codegraph/` 且任务涉及跨文件改动、重构、影响分析或调用链排查时，按项目约定优先使用 CodeGraph。
|
||
- 查询 library、framework、SDK、API、CLI 或 cloud service 的当前行为时，使用项目指定的最新文档工具；本地版本和真实运行结果优先。
|
||
- 编写函数、类或复杂逻辑时使用对应文档注释，说明参数、返回值、异常与设计原因。
|
||
- 注释解释 Why，不逐行翻译代码；权限、安全和兼容边界旁添加显眼警告。
|
||
|
||
## 版本控制
|
||
|
||
- commit、push、PR 只在用户明确要求时执行，三者授权互不自动包含。
|
||
- Trellis archive 和 journal 使用命令级 `--no-commit`；不依赖自动提交。
|
||
- commit message 默认 `<type>(scope): <中文动词短语>`，不加句号。
|
||
- commit 只包含本任务已确认归属的文件；不 amend，不静默包含用户或其他并行工作的改动。
|
||
|
||
## 最终答复
|
||
|
||
结论先行，按实际需要包含：
|
||
|
||
1. outcome；
|
||
2. key evidence / changed files；
|
||
3. verification actually run；
|
||
4. remaining risks or blockers；
|
||
5. necessary next step。
|
||
|
||
省略过程复述。未运行的验证必须明确写 `not run` 或说明阻塞原因。
|