# AI 工具接入入口

本文件是 UnityAI / StrayFog 框架知识库面向 Codex、Claude Code、Cursor、Windsurf、GitHub Copilot 等 AI / IDE 工具的统一接入说明。

根目录入口文件只做适配和跳转：

- `AGENTS.md`：Codex 默认项目入口。
- `CLAUDE.md`：Claude Code 默认项目入口。
- `RULES.md`：通用兼容入口，给其他 AI、IDE 或人工快速查看。

这些入口文件不要复制项目规则；真实内容统一维护在 ai/rules/modules/hooks/ 下。

## 所有 AI 先读

处理本项目任务时，按顺序读取：

1. [项目规则入口](../rules/项目规则入口.md)
2. [项目知识入口](../modules/模块索引.md)
3. [共享 hook 入口](../hooks/Hook共享层.md)

然后根据任务范围按需读取具体规则、模块、spec、plan 或 hook 文档。

## 文档分层

| 层级 | 文档 | 用途 |
|---|---|---|
| AI 接入层 | `ai/AI接入入口.md` | 说明不同 AI / IDE 工具如何进入项目 |
| 项目规则层 | `rules/项目规则入口.md` | 工作方式、扫描范围、任务流程、归档规则 |
| 项目知识层 | `modules/模块索引.md` | 项目框架、核心功能、编辑器工具总入口 |
| 业务参考层 | `business-reference/` | 外部实际项目业务参考，与框架核心分离 |
| Hook 共享层 | `hooks/Hook共享层.md` | 共享 hook 原则、检查脚本、触发方式 |
| Spec / Plan 层 | `specs/Spec索引.md`、`plans/` | 大需求、新模块、跨模块计划和归档 |

## Hook 接入原则

- 共享 hook 规则、脚本和文档关联逻辑统一放在 `hooks/`。
- 各 AI 工具自己的目录只放适配器，不重复维护 hook 逻辑。
- 若已配置 Codex，适配器 `.codex/hooks/archive-reminder.ps1` 可调用 `hooks/archive-check.ps1`。
- Claude Code 可以通过 command / hook 配置调用 `hooks/archive-check.ps1`。
- 只有用户明确说“提交”“提交代码”“commit”时，才触发提交流程。
- 若项目配置了自定义提交命令 `/commit` 或 git `prepare-commit-msg` hook，按实际配置使用，默认提交信息格式为 `[模块][feat]:内容描述`。
- 如需在关联文档中自动留下变更提醒，可调用 `hooks/sync-doc-associations.ps1`（只追加、不覆盖，执行后需 review）。
- 其他 AI / IDE 如果支持任务结束 hook，也应调用 `hooks/archive-check.ps1`。
- 如果某个工具不支持自动 hook，任务结束时手动运行或按 `hooks/Hook共享层.md` 执行归档检查。

## 新接入 AI 工具时

1. 确认该工具默认读取什么入口文件。
2. 如果该工具有默认入口文件，只在入口文件中指向 `ai/AI接入入口.md`。
3. 如果该工具支持 hook，配置它调用 `hooks/archive-check.ps1`。
4. 不要把 `rules/`、`modules/`、`hooks/` 的内容复制进工具私有目录。
5. 如需新增工具专属说明，只写适配方式，不写项目规则副本。

## 文档关联

> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。

| 文档 | 关联原因 |
|---|---|
| [AGENTS.md](../AGENTS.md) | Codex 入口应指向本 AI 接入入口 |
| [CLAUDE.md](../CLAUDE.md) | Claude Code 入口应指向本 AI 接入入口 |
| [RULES.md](../RULES.md) | 通用兼容入口应指向本 AI 接入入口 |
| [rules/项目规则入口.md](../rules/项目规则入口.md) | 项目规则入口由本文档引用 |
| [modules/模块索引.md](../modules/模块索引.md) | 项目知识入口由本文档引用 |
| [hooks/Hook共享层.md](../hooks/Hook共享层.md) | 共享 hook 入口由本文档引用 |