> For the complete documentation index, see [llms.txt](https://zhouhao4221.gitbook.io/haiqing-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://zhouhao4221.gitbook.io/haiqing-docs/07-tooling/ai-context-in-project.md).

# AI 信息项目化

为什么 AI 相关信息（提示、规则、需求、上下文）应该和项目代码放在一起，而不是存在聊天记录或外部 Wiki 里——以及四类信息各自放在哪里。

***

## 问题

团队开始使用 AI 工具后，通常会出现这种情况：有效的提示存在个人聊天记录里，需求写在 Notion，代码规范写在内部 Wiki，代码在 Git 仓库。这四处信息各自演进，很快出现漂移——需求改了但 AI 还在按旧规格生成代码，提示更新了但其他人不知道，代码回滚了但需求文档没有跟着回滚。

**根本原因**：AI 需要读取的信息没有被当成项目资产来管理。

***

## 为什么项目化

**上下文完整性** — AI 的输出质量取决于它在会话开始时能读到什么。需求规格、约束、领域术语、开发规范——这些都是 AI 生成代码前需要读取的材料。放在项目里，AI 工具可以直接读取；放在外部系统，只能靠人工搬运，搬运过程必然出现遗漏。

**变更原子性** — 需求改了，代码、测试、提示应该在同一次提交里更新。放在同一个仓库，这是自然的；分开存放则需要跨系统协调，版本漂移不可避免。

**可审查性** — `git blame` 一条需求文档，能看到谁改的、为什么改、改之前是什么。Notion 或 Wiki 的修改历史与代码历史永远是割裂的。

**回滚一致** — 代码回滚时，需求和提示自动回到对应版本，不需要额外操作。

***

## 四个信息层

AI 信息按更新频率和用途分为四层，每层有明确的存放位置。

### 第一层：行为规则（CLAUDE.md）

**放什么**：AI 在这个项目里应该遵守的规则。包括工作流约定（直接推到 main 还是开 PR）、代码风格偏好、禁止操作（如不要自动删除文件）、项目背景说明。

**为什么单独一层**：这类信息是 AI 每次工作都需要读取的约定，而且几乎不变。Claude Code 会在每次会话开始时自动加载 `CLAUDE.md`，不需要人工传递。

**维护方式**：项目根目录放 `CLAUDE.md`，写工作规则；全局 `~/.claude/CLAUDE.md` 写跨项目通用偏好。两级叠加，项目级优先。

```
~/.claude/CLAUDE.md          # 个人全局规则（不提交 git）
project/
└── CLAUDE.md                # 项目规则（提交 git，团队共享）
```

### 第二层：需求规格（docs/requirements/）

**放什么**：PRD（产品需求文档）和 REQ（具体需求文档）。这是 AI 生成代码前最需要读取的材料——功能边界、业务规则、验收标准、接口约定。

**为什么放项目里而不是 Notion/Jira**：AI 无法直接访问外部系统。需求在项目里，AI 可以在开发前直接读取 REQ 文档，生成的代码和测试自然对齐规格。需求在 Notion 里，每次开发前都需要人工复制粘贴，而且不在 git 历史里，无法追溯需求变更。

**维护方式**：使用需求管理工具（如 `/req:init`）初始化目录结构，通过 `/req:new`、`/req:dev`、`/req:done` 驱动需求文档的全生命周期。

```
docs/requirements/
├── PRD.md           # 产品整体规划，版本目标，功能优先级
├── active/          # 进行中的需求（REQ-XXX.md）
├── completed/       # 已完成的需求，作为历史参考
├── modules/         # 模块文档，描述系统各功能模块
└── specs/           # 数据类型、接口契约、业务规则等规范
```

开发一个功能时，AI 读取对应的 REQ 文档，了解功能边界和验收标准，再去读代码——这比只给 AI 看代码的效果好得多。

### 第三层：可复用提示（prompts/ 或 04-prompt/）

**放什么**：针对重复任务提炼出的提示模板。代码生成、错误诊断、重构、PR 评审、需求结构化——这类任务每天都会发生，提示稳定后提炼为模板，下次直接引用。

**为什么项目化**：好的提示是通过实践打磨出来的，不是一次性消耗品。提示存在聊天记录里就丢失了；放进仓库，版本可追溯，团队可共享，改进可积累。

**维护方式**：按任务类型分目录存放。修改提示时，提交信息说明为什么改、改了什么——提示的演进历史和代码一样重要。

```
04-prompt/
├── code/            # 代码生成、重构、测试、错误诊断
├── design/          # 架构设计、UI 设计辅助
├── review/          # PR 评审、代码审查
├── workflow/        # 需求结构化、文档整理
└── templates/       # 通用提示模板框架
```

### 第四层：会话记忆（\~/.claude/memory/）

**放什么**：跨会话需要保留的上下文——用户工作习惯、项目历史决策、工具配置偏好、本次反馈。这类信息在单次会话结束后理应保留，下次会话直接生效。

**为什么单独一层**：这类信息属于"已经告诉过 AI 的事"，不应该每次都重新说。它不是文档，不需要给团队看；它是 AI 个性化适应的积累，存在本地 `~/.claude/` 下。

**维护方式**：让 AI 工具自动积累（如 Claude Code 的 memory 功能）。内容分四类：用户习惯、反馈矫正、项目背景、外部资源引用。

```
~/.claude/projects/<repo>/memory/
├── MEMORY.md        # 索引文件
├── user_*.md        # 用户习惯和偏好
├── feedback_*.md    # 工作方式反馈（做对的和做错的）
├── project_*.md     # 项目背景和决策
└── reference_*.md   # 外部资源引用
```

***

## 完整项目结构

```
project/
├── CLAUDE.md                    # 第一层：行为规则
├── docs/
│   └── requirements/            # 第二层：需求规格
│       ├── PRD.md
│       ├── active/
│       ├── completed/
│       ├── modules/
│       └── specs/
└── 04-prompt/（或 prompts/）     # 第三层：可复用提示
    ├── code/
    ├── design/
    └── review/

# 第四层：会话记忆（本地，不提交 git）
~/.claude/projects/<repo>/memory/
```

***

## 判断标准

| 信息类型               | 属于哪层  | 存放位置                 | 是否提交 git |
| ------------------ | ----- | -------------------- | -------- |
| 工作流规则、代码风格、工具约定    | 行为规则  | `CLAUDE.md`          | 是        |
| 产品规划、功能需求、验收标准     | 需求规格  | `docs/requirements/` | 是        |
| 经过打磨的提示模板          | 可复用提示 | `prompts/`           | 是        |
| 工作习惯、会话反馈、个人偏好     | 会话记忆  | `~/.claude/memory/`  | 否        |
| 多项目共用的规范、模板        | 可复用提示 | 独立仓库 + 文件包共享         | 是（在共享仓库） |
| 运行时动态切换提示（A/B 测试等） | —     | 独立提示管理系统             | 不适用      |

最低起步：维护 `CLAUDE.md` + `docs/requirements/PRD.md`，其他层按需添加。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://zhouhao4221.gitbook.io/haiqing-docs/07-tooling/ai-context-in-project.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.