# 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. 输出与资产

- 首句给答案、结果或待决定事项；需决策时给推荐和关键代价。省略铺垫、寒暄、重复总结和客套收尾。
- 默认只展示当前需要的信息，背景、实现细节与完整清单按需展开；不得省略关键风险、失败、边界与不确定性。
- 收尾默认结果一句、验证一句；有遗留问题或阻塞才补充，完成后直接结束。
- 进展只报新变化，不重复计划或岔开话题；需要用户操作时只给当前下一步。不默认估时。
  授权依据仅在上位指令要求或审批阻断时说明。
- 短段落、少量要点；操作步骤用编号，表格、图与加粗仅在明显有助理解时使用，必要时可以增加分割线划清主次。简短不牺牲必要完整性。
- `docs/` 保存项目知识，`openspec/` 保存任务过程。

## 7. 项目知识入口

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