# AGENTS.md — Agent 执行契约

## 1. 适用范围

本文件适用于仓库根目录及其子目录。更深层 `AGENTS.md` 只覆盖同事项的冲突约定，其余继续继承。

<!-- harness:user:scope -->
{{SUBMODULE_SECTION}}
<!-- /harness:user:scope -->

## 2. 指令优先级与加载

在平台系统/开发者指令与权限约束内，项目约定优先级为：用户当前明确要求 > 更小作用域
`AGENTS.md` > 当前 `AGENTS.md`。

按以下顺序加载当前任务需要的最小上下文：

1. 当前作用域的 `AGENTS.md`，进入子项目时继续读取其 `AGENTS.md`；
2. `.harness/rules/`、`.harness/skills/` 中描述或路径与任务直接匹配的内容；
3. 按文档入口的读取条件加载当前项目 `docs/` 中相关知识，以及关联的 active change、current spec 或包内文档；不全量加载文档目录。

先确认任务归属并索引候选，再读取小范围片段；优先使用 `rg` / `sed` 并限制搜索路径、文件类型和日志输出。`CLAUDE.md`、`GEMINI.md` 仅为兼容入口，不覆盖本文件。

## 3. 授权与方案对齐

- 仅分析、讨论或请求方案时保持只读。写入须有明确请求，或用户认可已说明动作与范围的实施方案；授权不跨目标，单纯认可方向或补充范围不构成实施授权。授权不清时先澄清。
- 开发默认先调查，说明关键做法、改前/改后的行为、关键取舍、影响范围与验证方式，等待用户认可方案后实施；小任务可简短说明，不能仅列调查、修改、测试等工作步骤。
- 普通的实现、修改或修复请求仍需方案对齐，已有设计稿或改动可逆也不豁免。仅在用户明确要求跳过方案讨论、按其提供的完整方案实施，或已有同范围的方案确认与实施授权时直接推进；
  专项流程中的有效确认同样复用，不重复询问。
- 确认后自主完成范围内工作，局部实现细节自行决定；改变已确认的关键行为、契约、职责边界或核心做法时，只对变化部分重新对齐。
- 本节适用于所有实现入口；Rules、Skills 和执行路径不授予额外权限，专项门禁仍按其约束执行。

## 4. 任务分流

### L0: 专项能力短路

用户显式调用或任务明确命中时，加载对应 skill，不再套用普通开发路由：

| 任务类型 | Skill |
|----------|-------|
| 代码审查 | `review-orchestrator` |
| 测试用例设计 | `test-case-designer` |
| 缺陷管理 | `jira-defect-orchestrator` |
| 调试、诊断与缺陷修复 | `systematic-debugging` |
| 原子提交、推送或 MR/PR | `commit` |

项目专属 skill 优先于通用 skill；专项路由仍遵守第 3 节。

| 任务信号 | 适用入口 |
|----------|----------|
| CLI 模块与依赖调整 | `.harness/rules/architecture-constraints.md`、`.harness/rules/dependency-management.md` |
| 编写或运行测试 | `.harness/rules/testing-strategy.md` |
| Web 页面或路由调整 | `.harness/rules/web-frontend.md` |
| 修改分发指令与 skill | `.harness/rules/skill-versioning.md`、`instruction-maintenance` |

### L1: 普通开发请求

- 输入与方案明确时只做基于仓库事实的 Gap Check，不为形式增加访谈。
- 存在会改变结构、可观察行为或维护方式的关键 gap：加载 `brainstorming`，逐项形成共同设计。
- Direct/Lite/Full 边界不清，或出现持久化、外部契约协调、高后果且难回退的风险信号：加载
  `workflow-routing`；明确的低风险 Direct 不加载它。

| 路径 | 选择条件 | 关键边界 |
|------|----------|----------|
| Direct | 当前会话可完成最小改动与邻近验证 | 不创建 OpenSpec；与 Lite 难分时偏向 Direct |
| Lite | 存在恢复、交接、并行或审计等持久化价值 | 说明具体价值并取得用户同意 |
| Full | 用户显式选择，或命中外部契约/严重后果治理风险 | 说明风险并取得确认；复杂度、文件数或技术名词不是信号 |

- 显式 `/opsx:*` 加载对应 skill；各操作的授权不互相替代，已有 change 按其 selector 继续。
- OpenSpec 命令在包含 `openspec/` 的根仓库执行；子项目代码、构建与测试在目标子项目执行。

## 5. 实施、验证与审查

- 实施选择最小、可验证的改动；交付前完成对应验证与低成本 diff 自审，并提供可观察的完成证据。
- 先运行与改动最接近的验证，再按风险扩大；长输出保留失败用例、错误栈和关键摘要。
- 必要验证通过后，只有新改动、失败或未解决疑点才追加检查，不无理由重复测试或扩大验证范围。
- 影响共享核心或跨模块行为、验证证据较弱、存在明确不确定性、diff 超出确认范围，或用户/项目要求时，使用 `review-orchestrator`。
- worktree、实现 subagent、TDD、独立 review 和 commit 不是默认门禁；TDD 仅在有稳定测试接缝或项目
  要求时使用，review 按风险触发，worktree/subagent 按用户或项目要求使用，commit 仅由用户显式选择。

- 开发与本地运行前，读取 [开发指南](docs/development.md)。
- 选择测试范围或验证命令前，读取 [测试说明](docs/testing.md)。

## 6. 输出与资产

### 结果与依据

- 首句回答问题或说明结果，随后按任务需要呈现依据、影响与边界、下一步；省略空项，简单答复不强加标题。
- 来源紧邻所支撑的判断；区分仓库事实、Agent 建议、已确认决定和未决问题，不把推测写成决定，不省略关键风险、失败和不确定性。
- 密集信息先归纳再展开，各层可独立扫读。并列项用列表，步骤用编号，取舍用表格，避免在长段或单元格中混合结论、依据、风险与建议。职责、权限、状态或数据流难以用文字说明时，可用 Mermaid 配一句结论；图不替代关键文字。

### 进展更新

- 只报新变化、影响和下一动作，不重复总结，不加铺垫、寒暄、客套收尾或默认估时。
- 仅在上位指令要求或审批阻断时说明授权依据。

### 用户决策

- 只有现有决定或授权无法覆盖、且会改变权限模型、可观察行为或关键取舍的阻塞项，或缺少用户才能提供的信息时，才请求决策。每次只问最高价值的一项，统一放在末尾的独立决策区；能依据现有授权和事实推进时不提问。
- 写清要决定的契约；可枚举时给出互斥、可按编号回复的选项，标明推荐项、依据或适用前提及各项主要代价；否则明确所需信息。
- 优先使用可呈现且能等待实际答复的点击选择控件；无控件、未实际呈现或用户反馈看不到时，立即改用完整的文字选项。工具返回“已接受”不等于展示成功。
- **确认门禁**：仅用户实际提交且含义明确的答复可作为选择或确认依据；工具受理、推荐项、默认选中、控件关闭、超时或回合结束均不得视为用户确认。
- **等待门禁**：需要用户决定的事项在收到明确答复前保持未决，不登记为已确认决定，不执行依赖动作或推进下游流程；不依赖该答案的调查和检查可继续。

### 最终收尾

- 需要决策时用点击控件或文字版 **需要你选择**；无需决策但有重要信息时用 **必读**，简单答复可直接结束。
  **必读** 只保留少量要点，按需标注 **已确认**、**依据**、**边界或待核实**、**产物与验证**、**下一步** 并链接产物，不重复正文或过程记录；持续讨论只保留影响后续选择的决定和开放项。
- **控件生命周期门禁**：非阻塞控件尚未收到答复时，若无法确认其在回合结束后仍保留，必须改用文字版 **需要你选择** 收尾，完整保留同一问题、编号选项与取舍；无法枚举时写清所需信息。不得只发送结果总结而丢失待答问题。
- 收尾与正文分离：点击控件作为独立选择区；文字收尾前留空行和 Markdown 分割线 `---`，再以 `### 需要你选择` 或 `### 必读` 开始。
  每次只用一种收尾，之后不再追加正文。

资产位置：`docs/` 保存项目知识，`openspec/` 保存任务过程。

## 7. 项目知识入口

- 判断项目职责与资产归属时，读取 [项目概览](docs/project.md)。
- 调整模块边界或依赖时，读取 [架构说明](docs/architecture.md)。
- 查找项目知识时，从 [文档索引](docs/README.md) 按任务定位。