# Codex Harness Engineering Start Here

这份文档只做一件事：

- 帮第一次进入 `codex-harness-engineering/` 的人快速判断应该先读什么、先做什么。

## 路线 A：先理解方法论

推荐阅读顺序：

1. `README.md`
2. `mode-matrix.md`
3. `codex-host-runtime-and-autoload.md`
4. `knowledge-surface-map.md`
5. `global-rules-and-bootstrap.md`
6. `implementation-guide.md`

## 路线 B：把 Harness 接到一个新项目

推荐阅读顺序：

1. `README.md`
2. `mode-matrix.md`
3. `codex-host-runtime-and-autoload.md`
4. `knowledge-surface-map.md`
5. `global-rules-and-bootstrap.md`
6. `implementation-guide.md`

建议执行顺序：

1. 确认目标目录本身是 Git 仓库。
2. 运行 `templates/bootstrap-codex-harness.ps1`。
3. 如果这是全新仓库，先提交一次 bootstrap 基线。
4. 先裁剪 `docs/ai/repo-map.md` 和 `docs/ai/architecture-brief.md`，让 Agent 能准确导航目标项目。
5. 再补 `docs/ai/CURRENT_TASK.md`；复杂项目再补 `PROJECT_CONTEXT.md`、`DECISIONS.md`、`API_MAP.md`、`DB_SCHEMA.md`、`KNOWN_ISSUES.md`。
6. 如果项目已有明确业务词典、文件命名或类型后缀约束，补齐 `docs/harness/code-style-and-naming.md`，不要只靠口头约定。
7. 需要项目专属 `AGENTS.md` 时，按 `templates/docs/project-agents-template.md` 扫描项目事实后裁剪生成；根 `AGENTS.md` 只保留全局入口规则，目录独有的模块职责、边界和禁止事项优先写进子目录 `AGENTS.md`。
8. 先使用 `templates/runtime/smoke-task.json` 做首次自检。
9. 补齐 `docs/testing/ACCEPTANCE_EXAMPLES.md`、`TRACEABILITY_MATRIX.md`、`TEST_DATA_MATRIX.md` 等实现前 testing truth source。
10. 如果要接外部知识、MCP 或代码语义工具，先读 `docs/harness/mcp-knowledge-governance.md` 和 `docs/harness/code-semantics-and-navigation.md`。
11. 通过后再替换为真实业务 `task.json`。

## 路线 C：给现有项目补自动化

推荐阅读顺序：

1. `README.md`
2. `mode-matrix.md`
3. `codex-host-runtime-and-autoload.md`
4. `knowledge-surface-map.md`
5. `global-rules-and-bootstrap.md`
6. `implementation-guide.md`

## 最短路径

1. 读 `README.md`
2. 读 `mode-matrix.md`
3. 读 `codex-host-runtime-and-autoload.md`
4. 读 `knowledge-surface-map.md`
5. 跑 `templates/bootstrap-codex-harness.ps1`
6. 提交 bootstrap 基线
7. 裁剪 `docs/ai/repo-map.md`
8. 补 `docs/ai/CURRENT_TASK.md`
9. 需要目录级架构规则时，优先给关键目录补子目录 `AGENTS.md`
10. 用 `templates/runtime/smoke-task.json` 跑一次 smoke
11. 补 testing truth source，再进入 `implementation-guide.md`
