# Agent 生态实践吸收建议

本文分析一组关于大型项目中使用 AI 编程工具的实践材料，并说明哪些内容适合吸收到当前 Codex Harness 能力包，哪些应该保持为项目本地配置或后续扩展。

核心判断：决定效果的不是单个模型，而是围绕模型建立的可导航、可验证、可分发、可复盘的工程环境。对当前能力包来说，分发仓库本身就是这套环境的载体。

## 可吸收内容总览

| 来源思想 | 在当前能力包中的落点 | 吸收方式 |
| --- | --- | --- |
| 根入口规则保持短小 | `templates/runtime/AGENTS.md`、`templates/docs/project-agents-template.md` | 强化短入口、深文档索引、子目录规则分层 |
| 子目录级规则按需加载 | `templates/docs/project-agents-template.md` | 只在目录规则明显不同的模块生成子目录 `AGENTS.md` |
| 代码地图提升检索效率 | `templates/context/repo-map.md`、`update-codemaps` skill | 把 repo map / codemap 作为 AI 导航索引维护 |
| 技能承载固定流程 | `skills/*`、`templates/package-assets/skills/*` | 将安全审查、文档同步、代码地图更新等流程沉淀为 skill |
| Hooks 做自动化一致行为 | `templates/hooks/*` | 保持为增强层，用于 stop-gate、反馈门禁、会话复盘触发 |
| 插件 / 包做团队分发 | 能力包根目录 + package-assets | 通过 package mirrors 分发 rules、skills、prompts、hooks、docs |
| MCP 连接外部系统 | `templates/config/mcp-config.toml`、接入文档 | 只放非敏感模板，真实服务和密钥留在项目配置或环境变量 |
| LSP 提升代码导航 | `global-rules-and-bootstrap.md`、环境检查建议 | 作为环境建议，不把具体语言服务器写成所有项目硬约束 |
| 定期规则治理 | `rule-governance.md`、`best-practices.md` | 3-6 个月或模型升级后清理过时规则 |

## 1. 入口规则分层

材料中强调不要把所有知识都塞进 `CLAUDE.md`。在 Codex / AGENTS 体系里，同样适用：

- 全局 `~/.codex/AGENTS.md` 只放跨项目稳定习惯。
- 项目根 `AGENTS.md` 只放每次会话必须知道的项目规则、真实入口和深文档索引。
- 子目录 `AGENTS.md` 只在 monorepo、支付、权限、数据迁移等目录约束明显不同的地方添加。
- 具体流程、长模板、复盘经验应下沉到 `docs/`、`.codex/rules/`、`.codex/prompts/` 或 skill。

不建议吸收到根入口的内容：

- 某个团队的口头偏好。
- 已经能由 lint、schema、verify、hook 检查的长规则。
- 只对单个模块成立的细节。

## 2. 代码地图作为 AI 导航索引

大型代码库中，AI 最大的浪费通常发生在“找错地方”和“全仓扫描”。因此 当前能力包应把 repo map / codemap 当成一等公民。

推荐结构：

```text
AGENTS.md
docs/ai/repo-map.md
docs/ai/architecture-brief.md
docs/architecture/constraints.md
docs/harness/*
docs/testing/*
```

根 `AGENTS.md` 应明确说明：需要理解代码结构时，先读 `docs/ai/repo-map.md` 或项目声明的同类文件，再进入具体模块；进入具有子目录 `AGENTS.md` 的模块后，必须同时遵守根规则和本地规则。

代码地图应该记录：

- 项目目标和主要业务域。
- 关键目录职责。
- 模块入口和真实 truth source。
- 生成代码、外部系统、敏感目录和禁改区。
- 常用验证命令。
- 最近更新时间和维护责任。

不应记录：

- 大段源码解释。
- 每个函数的实现细节。
- 会频繁变化但没有维护机制的临时路径。

## 3. 技能沉淀固定流程

材料中“技能按需加载”的思想已符合当前 `docs/codex-harness-engineering/templates/package-assets/skills/*` 设计。适合继续吸收的方向：

- 把重复的工作流沉淀成 skill，例如 code review、API contract、E2E planning、codemap 更新、文档同步。
- skill 描述必须写清触发场景，避免每次会话都加载。
- skill 内部要给确定性步骤、输入输出、验证方式和可复用脚本。
- 专家知识优先放 skill，不放根 `AGENTS.md`。

判断是否应创建 skill：

| 条件 | 处理 |
| --- | --- |
| 多个项目复用同一流程 | 创建或更新 skill |
| 只影响当前项目一次 | 放任务文档或 `docs/knowledge/` |
| 可以脚本化 | skill 调用脚本，不重复写大段命令 |
| 必须所有会话知道 | 才升级为 `AGENTS.md` 入口规则 |

## 4. Hooks 的边界

材料中提到 hooks 可用于格式化、检查和会话学习。对当前 Windows + PowerShell driver-first harness，边界应更保守：

- hooks 可以作为增强层，例如 stop-gate、feedback-gate、格式检查提醒、复盘入口。
- 不把 hooks 当主链路；任务选择、验证、trace、commit 仍由 `tools/harness/codex-loop.ps1` 负责。
- 会话复盘不应每轮都写知识库，建议按轮次、失败类型或人工确认触发，避免低质量经验污染规则。
- hook 产生的新知识先进入 `docs/knowledge/` 或 review queue，经治理后再升级为规则、prompt 或 skill。

## 5. 包和插件分发

材料中“插件像私有包一样分发能力”的思想，在这里对应当前能力包根目录与 package-assets：

- `.codex/rules/*` 分发角色和阶段规则。
- `.codex/prompts/*` 分发 driver 注入提示。
- `skills/*` 分发可复用流程。
- `templates/hooks/*` 分发增强 hooks。
- `docs/codex-harness-engineering/*` 分发人类可读方法论。

新增或更新这些能力时，必须按同步矩阵刷新 package mirrors，避免只改活跃副本导致新项目安装不到。

## 6. MCP 与外部系统

MCP 适合连接工单、需求、设计、测试、知识库、监控等外部系统。当前能力包里应吸收的是模板和边界，而不是真实配置：

- 提供 `mcp-config.toml` 示例。
- 文档说明 MCP 适合读取哪些外部 truth source。
- 密钥、token、私有 URL、账号信息必须留在环境变量、用户配置或项目私有配置中。
- 任务声明如果依赖外部系统，完成证据必须包含真实接入成功态和失败态，而不是 mock-only 结果。

## 7. LSP 与导航工具

LSP 对大型项目有明显价值，但具体语言服务器取决于项目技术栈。适合吸收为环境建议：

- 新环境初始化时提示安装对应语言插件或 LSP。
- 对 Java、TypeScript、Python、Go 等项目，在项目 `AGENTS.md` 或 README 中列出本项目推荐工具。
- 不在全局规则里强制某个语言服务器。

## 8. 定期治理

模型能力、工具行为和团队工作流会变化。当前能力包应明确治理节奏：

- 模型或 CLI 大版本升级后，检查 `AGENTS.md`、rules、prompts、skills 是否仍必要。
- 每 3-6 个月清理一次重复、过时、已经自动化的文字规则。
- 对失败复盘优先补测试、schema、verify 或 hook，再考虑写规则。
- 入口规则越短，越容易长期保持有效。

## 推荐落地优先级

1. 先完善 `AGENTS.md` 分层、repo map 模板和 `update-codemaps` skill。
2. 再把高频流程沉淀成 skill，避免继续增肥入口规则。
3. 然后治理 hooks，让它们只做增强和复盘入口。
4. 最后补 MCP、LSP、插件分发文档和环境检查。

这套吸收方式可以把材料中的经验转成当前能力包可分发的工程资产，同时避免把长篇知识直接塞进每次会话上下文。
