## 模板优先

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

## 目录级规则

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

## 必读索引

如果当前仓库是 thin install 项目，而下面列出的 `docs/harness/*` 或 `docs/knowledge/*` 不在项目根，先读取 `.codex-harness/state/config.json`，再到其中 `packageRoot` 下查同路径文件。

- 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/`。
