# Harness 知识面分层图

本文把当前 Harness 工程里和“知识、上下文、检索、自动加载”相关的文件面一次拆清，回答四个问题：

- 什么会直接进入 Codex 上下文。
- 什么只是运行配置，不应误判为知识真相源。
- 什么属于项目内知识，应提交到仓库。
- 什么属于外部或个人知识，只应查询，不应直接升级为项目规则。

## 1. 总图

```text
用户个人知识 / 本地 KB / Obsidian / 外部文档
  -> 通过 MCP / 本地检索 / 代码语义工具按需查询

Codex 宿主自动加载面
  -> AGENTS 链
  -> developer/system instructions
  -> 被触发的 Skills
  -> hooks additionalContext
  -> IDE / 工具采集上下文

项目导航层 docs/ai/
  -> repo-map
  -> architecture-brief
  -> current-task
  -> project-context
  -> API / DB / decisions / known issues / changelog

项目治理层 docs/harness/ + docs/testing/
  -> driver 协议
  -> prompt / knowledge / rule 集成
  -> MCP / 代码语义 / 回归 / 证据治理

项目知识层 docs/knowledge/
  -> catalog
  -> decisions / guidelines / pitfalls / processes / models

分发与模板层
  -> docs/codex-harness-engineering/templates/*
  -> templates/package-assets/*
```

## 2. 六类知识面

### A. 宿主自动加载面

这是“Codex 在启动或运行时有机会自动带进上下文”的部分。

- `AGENTS.md`
- `.codex/prompts/*`
- `.codex/rules/*`
- `.codex/agents/*`
- 被触发的 `.agents/skills/*/SKILL.md`
- hooks 的 `additionalContext`

这层的核心职责是：

- 定义行为约束
- 定义执行角色
- 控制什么时候查什么
- 告诉模型哪些文件是真相源

这层不适合塞大量长期知识原文。它负责“路由和约束”，不负责“承载全部项目知识正文”。

## B. 项目导航层

这是 `docs/ai/`，作用是让 agent 在不爆上下文的前提下快速理解当前项目。

建议至少包含：

- `repo-map.md`
- `architecture-brief.md`
- `CURRENT_TASK.md`
- `PROJECT_CONTEXT.md`
- `DECISIONS.md`
- `API_MAP.md`
- `DB_SCHEMA.md`
- `KNOWN_ISSUES.md`
- `CHANGELOG_AI.md`

这层的核心职责是：

- 提供最短阅读路径
- 提供项目结构导航
- 为代码语义检索和文档检索提供入口
- 把“当前任务事实”和“长期知识条目”分开

## C. 项目治理层

这是 `docs/harness/` 和 `docs/testing/`。

它们不是普通说明文档，而是 driver、review、verify、archive 等流程会引用的治理真相源。

典型内容：

- `docs/harness/architecture.md`
- `docs/harness/prompt-knowledge-integration.md`
- `docs/harness/knowledge-architecture.md`
- `docs/harness/mcp-knowledge-governance.md`
- `docs/harness/code-semantics-and-navigation.md`
- `docs/testing/*`

这层的核心职责是：

- 规定知识如何被查询、引用、升级、归档
- 规定测试与证据如何左移
- 规定外部知识和项目知识的边界

## D. 项目知识层

这是 `docs/knowledge/`。

这层只放已经值得复用、且应留在仓库中的项目经验：

- 架构决策
- 推荐做法
- 禁止做法与替代方案
- 已知坑
- 过程化经验

这层应通过 `knowledge-catalog.md -> catalog.md -> 具体条目` 的方式渐进读取，而不是整库灌入上下文。

## E. 外部知识层

这是项目外部但与当前实现有关的知识面：

- 官方文档
- 第三方平台文档
- 公共 GitHub 仓库
- 团队共享知识库
- 行业规范

这层通常通过 MCP 或搜索工具访问。默认不直接成为项目真相源，除非被明确转录、验证并沉淀到项目文档或知识条目中。

## F. 个人知识层

这是用户自己的长期经验：

- 本地 Markdown
- Obsidian
- 私有备忘
- 本地脚本说明
- 个人常见问题清单

这层默认不进入仓库，不应被当作团队或项目公共真相源。适合通过本地 KB MCP 查询，或在确认后提炼成项目知识条目。

## 3. 默认查询顺序

推荐执行顺序如下：

1. `AGENTS.md`
2. `docs/ai/repo-map.md`
3. `docs/ai/architecture-brief.md`
4. `docs/ai/CURRENT_TASK.md`
5. 需要时读取 `docs/ai/PROJECT_CONTEXT.md`、`DECISIONS.md`、`API_MAP.md`、`DB_SCHEMA.md`、`KNOWN_ISSUES.md`
6. 进入 `docs/harness/*` 治理真相源
7. 进入 `docs/knowledge/knowledge-catalog.md`
8. 仅在需要时查询 MCP、外部知识或个人知识

## 4. 升级边界

不同知识面之间的升级边界如下：

- 单次任务经验：先写 `docs/ai/CURRENT_TASK.md` 或归档报告，不直接写 `AGENTS.md`
- 可复用项目经验：进入 `docs/knowledge/*`
- 稳定治理规则：进入 `docs/harness/*`、`.codex/prompts/*`、`.codex/rules/*`
- 可安装模板：进入 `docs/codex-harness-engineering/templates/*`
- 可分发镜像：进入 `templates/package-assets/*`

## 5. 常见误区

- 把 `config.toml` 当成知识正文。它主要是运行配置，不是项目知识库。
- 把 `AGENTS.md` 写成超长百科。它应该更像入口规则和导航路由。
- 把外部文档查询结果直接当作项目真相源。需要先验证，再落到仓库。
- 把个人笔记直接升格为团队规则。必须先走项目知识沉淀和证据链。
- 只有文档概念，没有安装模板。这样新项目初始化后会缺文件面。

## 6. 相关文档

- `docs/codex-harness-engineering/codex-host-runtime-and-autoload.md`
- `docs/harness/knowledge-architecture.md`
- `docs/harness/prompt-knowledge-integration.md`
- `docs/harness/mcp-knowledge-governance.md`
- `docs/harness/code-semantics-and-navigation.md`
- `docs/codex-harness-engineering/doc-update-map.md`
