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/

判断标准

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