obsidian-vault/AI-RD-Workflow/40-workflows/trellis-matt/CN/AGENTS.md

全局 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，再用 grill-with-docs review spec。
• 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 等证据。
• 每个 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。
• 使用 grill-with-docs 逐项 review 产品、范围、UX、兼容、风险、验收和关键设计决策。
• 一次只问一个问题；先查环境事实，只把真正属于用户的决策交给用户。
• 每个答案确认后立即同步回 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 或说明阻塞原因。