AGENTS.md · diff
git:20260922.123429c to git:20260923.05b4c72
19 added, 15 removed. Audit A to A.
# 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 或包内文档。
+ 3. 按文档入口的读取条件加载当前项目 `docs/` 中相关知识，以及关联的 active change、current spec
+ 或包内文档；不全量加载文档目录。
- 先确认任务归属并索引候选，再读取小范围片段；优先使用 `rg` / `sed` 并限制搜索路径、文件类型和日志
- 输出。`CLAUDE.md`、`GEMINI.md` 仅为兼容入口，不覆盖本文件。仅在追溯历史或实现明确依赖时读取
- `openspec/changes/archive/`。
+ 先确认任务归属并索引候选，再读取小范围片段；优先使用 `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` |
- <!-- harness:user:l0-custom -->
- <!-- 项目专属原子操作请在此处补充，例如：
- | 部署 | project-deploy |
- -->
- <!-- /harness:user:l0-custom -->
-
项目专属 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 | 用户显式选择，或命中外部契约/严重后果治理风险 | 说明风险并取得确认；复杂度、文件数或技术名词不是信号 |
### 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 仅由用户显式选择。
+ - 开发与本地运行前，读取 [开发指南](docs/development.md)。
+ - 选择测试范围或验证命令前，读取 [测试说明](docs/testing.md)。
+
## 6. 输出与资产
- 面向工程师，结论前置，默认短答、按需展开；省略寒暄、重复与无关过程，不固定字数或条数，不默认估时。
- 用加粗短标签突出结论、风险与待确认项，可配少量语义一致的图标；需决策时给推荐和关键代价。
- 进展只报变化与下一动作；收尾说明结果、验证、遗留问题及必要的下一步建议，保留关键边界与不确定性。
授权依据仅在上位指令要求或审批阻断时说明。
- 并列用列表、步骤用编号、对比用表格；Mermaid 仅在明显有助理解时使用。
- - 获准持久化的知识文档写入 `openspec/`；配置、skills、rules 和 agents 分别位于 `.harness/` 对应目录。
+ - `docs/` 保存项目知识，`openspec/` 保存任务过程。
- ## 7. 项目补充
+ ## 7. 项目知识入口
- <!-- harness:user:project -->
- <!-- 项目特有的约束、背景、注意事项写在此处 -->
- <!-- /harness:user:project -->
+ - 判断项目职责与资产归属时，读取 [项目概览](docs/project.md)。
+ - 调整模块边界或依赖时，读取 [架构说明](docs/architecture.md)。
+
+ - 查找项目知识时，从 [文档索引](docs/README.md) 按任务定位。