## 模板优先

- 需要影响新项目 bootstrap、生成物结构、默认导航层、默认 prompt、默认规则、默认技能、默认上下文模板时，先修改模板 canonical：
  - `docs/codex-harness-engineering/templates/`
  - `tools/harness/templates/`
  - `docs/codex-harness-engineering/templates/package-assets/`
- 当前仓库根目录下的活跃文档或脚本，只在它本身就是 canonical，或为了验证模板落地效果、保持当前仓库可运行时再同步修改。
- 如果一次改动同时涉及根目录活跃文件和模板文件，优先说明哪一份是 canonical，避免只修当前仓库、不修模板源。

## 任务结构硬门禁

- 未经用户明确同意，不得把标准 `task.json` 模板 phase 压缩成更少任务；正式任务队列至少保留 `ANALYSIS-001`、`TESTCASE-001`、`PLAN-001`。
- P0/P1 项目禁止跳过 `TESTCASE-001`；缺少 `docs/testing/NATURAL_LANGUAGE_TEST_CASES.md`、`ACCEPTANCE_CRITERIA.md`、`TRACEABILITY_MATRIX.md`、`TEST_DATA_MATRIX.md`、`REGRESSION_PLAN.md`、`verify-matrix.md` 任一项，都不得生成最终 `task.json`。
- `feature_impl` 没有 `qa_contract` 不得进入正式任务队列；`qa_contract` 没有完整 `tdd_contract`、`development_validation`、`acceptance_validation` 不得开始实现。
- 单个 `feature_impl` 默认不得覆盖超过 3 条主需求；订单、支付、库存、RBAC 必须拆独立任务；前端和后端不得长期混在同一个 story，除非这是明确的 `release` 任务。

## 子目录 AGENTS 规则

- 新增业务目录、模块职责变化、目录入口变化、目录级测试命令变化时，必须检查并更新最接近该目录的子目录 `AGENTS.md`。
- 目录级 `AGENTS.md` 负责承载局部职责、边界、入口、测试命令、复用模式、坑点和禁止事项；不要把这类规则长期堆在根 `AGENTS.md`。
- 自动托管区块 `AUTO-MODULE-FACTS` 只补动态事实，不等于目录规则完整；即使 facts 已自动刷新，仍需要有人维护手写的局部规则部分。
- 如果 `task.json.owned_paths`、`docs/ai/repo-map.md` 或模块边界已经明确某目录是独立模块，而该目录缺少子目录 `AGENTS.md`，应视为至少 `warn`，高风险目录应直接阻断进入正式任务队列或实现阶段。

## 目录级规则

- 当某个目录满足以下任一条件时，应优先考虑新增或更新该目录下的 `AGENTS.md`，而不是继续扩充根入口：
  - 目录有独立模块职责或技术栈
  - 目录存在与全仓不同的架构边界
  - 目录有独立入口文件、测试命令或验证方式
  - 目录反复出现相同 review 问题、坑点或禁止事项
- 子目录 `AGENTS.md` 应重点写：
  - 该目录负责什么 / 不负责什么
  - 入口文件和核心文件
  - 修改前必须先看的文件
  - 本目录的局部架构规则和复用模式
  - 测试 / 构建 / 验证命令
  - 常见坑和禁止事项
- `docs/ai/repo-map.md` 及模板中的 repo-map 应维护“子目录规则索引”，明确哪些路径已有本地规则、适用于什么场景。

## 必读索引

如果当前仓库是 thin install 项目，而下面列出的 `docs/harness/*`、`docs/testing/*` 或 `docs/knowledge/*` 不在项目根，先读取 `.codex-harness/state/config.json`，再按文档类型改读 `packageRoot` 下模板镜像中的对应文件：
- `docs/harness/*` -> `docs/codex-harness-engineering/templates/docs/*`
- `docs/testing/*` -> `docs/codex-harness-engineering/templates/testing/*`
- `docs/knowledge/*` -> `docs/codex-harness-engineering/templates/knowledge/*`

- Harness 分层分析索引：`harness-analysis/README.md`
- Codex Harness Engineering 总览：`docs/codex-harness-engineering/README.md`
- Codex 宿主自动加载机制：`docs/codex-harness-engineering/codex-host-runtime-and-autoload.md`
- Codex 自动加载优化清单：`harness-analysis/10-codex-autoload-optimization-checklist.md`
- Harness 架构：`docs/harness/architecture.md`
- 架构约束包：`docs/architecture/constraints.md` 或 `task.json.runtime.handoff.truth_sources.architecture`
- 新项目使用：`docs/harness/new-project-usage.md`
- Task 会话与 `task.json` 细则：`docs/harness/task-session-strategy.md`
- 规则治理与 AGENTS.md 分层：`docs/harness/rule-governance.md`
- 回归与验证策略：`docs/harness/regression-rules.md`
- Trace 格式：`docs/harness/trace-format.md`
- 权限策略：`docs/harness/sandbox-policy.md`
- Prompt 与知识集成：`docs/harness/prompt-knowledge-integration.md`

## 当前在做的事情

- 正在持续分析当前仓库里的 Codex 宿主层、Harness 控制层、安装工程和桥接层。
- 当前重点是把“哪些内容会被 Codex 自动加载到上下文、哪些只是运行配置、哪些是 Harness runtime 二次读取”彻底拆清。
- 所有新增分析文档统一落在 `harness-analysis/`，方法论和模板级说明补充到 `docs/codex-harness-engineering/`。
