# Architecture Brief

## 1. 系统概览

- 系统边界: 本仓库维护 Codex Harness 安装包和当前仓库运行时，不承载具体业务应用。
- 核心服务: `tools/harness/codex-loop.ps1` driver、`tools/install/bootstrap-codex-harness.ps1` 安装初始化、`refresh-agent-package.ps1` 包同步、`.codex/prompts/*` 执行提示、`.agents/skills/*` 可复用技能。
- 主要数据流: `task.json` -> driver -> `codex exec` -> 验证命令 -> `progress.txt` / trace -> Git commit。

## 2. 分层职责

| 层 | 职责 | 主要目录 |
| --- | --- | --- |
| Runtime 层 | 任务选择、执行、验证、trace、提交 | `tools/harness/codex-loop.ps1`, `task.json`, `.codex/` |
| Package 层 | 当前仓库包根与可分发 package-assets | repo root |
| Template 层 | 新项目 bootstrap 模板 | `docs/codex-harness-engineering/templates/` |
| Knowledge 层 | 深文档、规则治理、测试真相源、知识沉淀 | `docs/harness/`, `docs/testing/`, `docs/knowledge/` |
| Skill 层 | 可复用流程和专用能力 | `.agents/skills/`, `docs/codex-harness-engineering/templates/package-assets/skills/` |

## 3. 真相源

- 产品真相源: `docs/requirement-prep-kit/` 或任务声明。
- 设计真相源: `docs/codex-harness-engineering/templates/design/`。
- Contract 真相源: `docs/codex-harness-engineering/templates/contracts/`。
- 类型真相源: PowerShell scripts、JSON schema、task template。
- 测试真相源: `docs/testing/*`。

## 4. 关键模块

| 模块 | 责任 | 上游 | 下游 | 风险 |
| --- | --- | --- | --- | --- |
| `tools/harness/codex-loop.ps1` | driver-first 自动执行 | `task.json`, `.codex/prompts/*` | trace、progress、commit | 状态伪造、验证缺失 |
| `tools/install/bootstrap-codex-harness.ps1` | 初始化目标项目 runtime/docs/config | templates | 目标项目根目录 | 漏装关键 truth source |
| `refresh-agent-package.ps1` | 刷新当前仓库 package 面和 manifest | root truth source | templates / ai-sync | 镜像漂移 |
| `.agents/skills/` | 活跃技能 canonical | skill authors | `docs/codex-harness-engineering/templates/package-assets/skills`, package-assets | 只改一处导致分发缺失 |
| `docs/codex-harness-engineering/` | 安装包方法论和模板 | root docs / package docs | package-assets docs | 文档和安装行为不一致 |

## 5. 关键约束

- 修改安装行为时，先改 root runtime 或模板 canonical，再同步 `.agents/`、templates 和 package-assets。
- 修改 skills 时，以 `.agents/skills/<name>` 为 canonical。
- 修改 active role rules 时，以 `.codex/rules/agents.md` 为 canonical。
- 文档改动至少运行 `git diff --check`；脚本改动还要做 PowerShell parser 检查。

## 6. 高风险区域

- `task.json` 状态写回。
- Git dirty workspace 检查。
- package mirrors 和 manifest / lock。
- hooks 与 driver 职责边界。
- 外部 MCP、token、cookie、私钥、密码。

## 7. 建议阅读顺序

1. `AGENTS.md`
2. `docs/ai/repo-map.md`
3. `docs/harness/architecture.md`
4. `docs/harness/rule-governance.md`
5. `docs/codex-harness-engineering/README.md`
