## 根规则定位

- 本文件只保留当前项目每次会话都必须遵守的硬约束和阅读入口。
- 项目专属事实、目录职责、入口文件、局部测试命令和常见坑，优先写到对应子目录 `AGENTS.md`，不要长期堆在根入口。
- 如果某条规则已经能由 schema、lint、hook、driver 或脚本确定性检查，优先依赖自动化，不要在根入口重复展开成长说明。

## 任务结构硬门禁

- 未经用户明确同意，不得把标准 `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` 任务。

## 实施边界

- 不得伪造 `task.json` 完成状态、trace、测试结果或 review 结论；完成状态只能由 runtime gate 写回。
- 不得修改当前任务 `owned_paths` 之外的文件；发现必须改边界外内容时先 `BLOCKED`，补齐计划或拆任务。
- 不得顺手修无关问题、扩大 diff、引入未经批准依赖，或静默修改公共契约、schema、路由和导出面。
- 不得把 token、cookie、私钥、密码、生产敏感数据写入仓库、trace、文档、截图或日志。

## 代码质量铁律

- 新文件和新目录必须放在符合当前项目模块职责的位置；不要用 `temp/`、`utils2/`、`common2/`、`newFeature/` 这类临时目录容纳实现。
- 先复用现有模块、组件、契约和工具；只有在复用和成熟方案都不适合时，才做最小自定义实现。
- 不得复制业务规则、映射逻辑或平行再造一层近似抽象；发现重复实现时优先收敛到既有模式。
- 不得把领域逻辑、权限判断、状态机、事务一致性或关键副作用直接塞进页面、路由、控制器、脚本入口或测试替身。
- 命名必须准确表达业务概念、动作和边界；不要使用 `processData`、`handleThing`、`doAction` 这类模糊名。
- 错误处理不能静默吞错；失败路径必须保留上下文，并对调用方、用户或后续任务可诊断。
- 单任务只做最小必要改动；如果发现必须扩大范围，先补计划、拆任务或阻塞，不要直接扩面。

## 子目录 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/ai/repo-map.md` 和 `docs/ai/architecture-brief.md`，确认目录边界、模块职责和阅读顺序。
- 再读 `docs/harness/architecture.md`、`docs/harness/code-quality-model.md`、`docs/harness/task-session-strategy.md`、`docs/harness/rule-governance.md`、`docs/harness/regression-rules.md`。
- 涉及任务执行、验收或回归时，再读 `docs/testing/*`、`docs/architecture/constraints.md`、`task.json` 与相关 trace。

## 本地化要求

- 初始化后，必须按当前项目事实裁剪本文件，不要长期保留模板口吻、示例路径或与项目无关的治理说明。
- 当某个目录已经有独立模块职责、技术栈、入口、测试命令或边界规则时，应补充该目录自己的 `AGENTS.md`。
