# 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. 直接相关的 active change、current spec、设计、PRD、API 或包内文档。

先确认任务归属并索引候选，再读取小范围片段；优先使用 `rg` / `sed` 并限制搜索路径、文件类型和日志
输出。`CLAUDE.md`、`GEMINI.md` 仅为兼容入口，不覆盖本文件。仅在追溯历史或实现明确依赖时读取
`openspec/changes/archive/`。

## 3. 授权与方案对齐

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

## 4. 任务分流

### L0: 专项能力短路

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

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

<!-- harness:user:l0-custom -->
<!-- 项目专属原子操作请在此处补充，例如：
| 部署 | project-deploy |
-->
<!-- /harness:user:l0-custom -->

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

### L1: 普通开发请求

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

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

### OpenSpec 入口

- OpenSpec 是持久化协调层，不是普通开发的默认前置流程；Brainstorming 默认保持 topic-only。
- 用户显式调用 `/opsx:*` 时加载对应 skill；创建 change、选择 FF、Apply、Archive 和交付动作的授权
  不互相替代。
- `brainstorm.md` 是共同设计的唯一语义源；下游 artifacts 只能投影已确认决定、仓库事实和机械转换，
  不得重新扩散设计。具体状态、依赖、迁移和恢复算法由 OPSX skills 与 schema 负责。
- OPSX 与 OpenSpec 命令在包含 `openspec/` 的 DevKeel 根仓库执行；子项目代码、构建和测试在目标
  子项目执行。已有 active change 按其 selector 继续。

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

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

## 6. 输出与资产

- 面向工程师，结论前置，默认短答、按需展开；省略寒暄、重复与无关过程，不固定字数或条数，不默认估时。
- 用加粗短标签突出结论、风险与待确认项，可配少量语义一致的图标；需决策时给推荐和关键代价。
- 进展只报变化与下一动作；收尾说明结果、验证、遗留问题及必要的下一步建议，保留关键边界与不确定性。
  授权依据仅在上位指令要求或审批阻断时说明。
- 并列用列表、步骤用编号、对比用表格；Mermaid 仅在明显有助理解时使用。
- 获准持久化的知识文档写入 `openspec/`；配置、skills、rules 和 agents 分别位于 `.harness/` 对应目录。

## 7. 项目补充

<!-- harness:user:project -->
<!-- 项目特有的约束、背景、注意事项写在此处 -->
<!-- /harness:user:project -->