主题
01.3 Projects 项目与知识库
[Projects] (项目) 是网页端唯一的持久化上下文机制。用好它，等于给 Claude 装了长期记忆。
读完你能做什么：设计出一个不会随着资料增多而变笨的项目知识库，并知道什么内容绝不该放进去。
一、Project 是什么
一个 [Projects] (项目) = 一组共享同一份背景知识与指令的对话集合。
text
Project「支付系统重构」
├── [Custom Instructions] (自定义指令) ← 每次对话自动注入
├── [Project Knowledge] (项目知识库) ← 上传的文件，按需检索
└── 对话
├── 对话 1：梳理现有架构
├── 对话 2：设计新方案
└── 对话 3：评审风险三个对话彼此不共享聊天记录，但共享指令与知识库。
二、[Custom Instructions] (自定义指令) 怎么写
这是 Project 里价值最高的一栏，因为它每次对话都会加载。
2.1 结构模板
text
<role>
你是本项目的资深技术顾问，熟悉支付领域的合规要求与高并发架构。
</role>
<project_context>
- 系统：某电商平台的支付网关，日均 200 万笔交易
- 技术栈：Java 17 + Spring Boot 3 + PostgreSQL 15 + Kafka
- 当前痛点：对账模块耦合严重，扩展新支付渠道需要改 12 个文件
- 团队：4 名后端，无专职测试
</project_context>
<rules>
- 所有方案必须给出「改动范围」与「回滚方案」两栏
- 涉及金额计算一律使用 BigDecimal，禁止 double
- 引用知识库内容时必须注明来源文件名
- 知识库中没有的信息，明确说「知识库未涵盖」，不要基于通用经验推测本项目的实现
</rules>
<output_format>
技术方案统一按以下结构输出：
1. 问题定义
2. 方案（含改动范围、回滚方案）
3. 风险与未知项
</output_format>2.2 三条硬规则
| 规则 | 原因 |
|---|---|
| 控制在 300 字以内的核心事实 | 每次对话都要消耗这些 token，而且指令越长，单条指令的权重越被稀释（见 04.2） |
| 写"必须/禁止"，不写"尽量/最好" | 模糊约束等于没有约束 |
| 定期删除过时内容 | 矛盾的指令会让模型随机选一条执行 |
三、[Project Knowledge] (项目知识库) 的检索机制
这是最多人误解的地方。
3.1 它不是「全部塞进上下文」
知识库里的文件不会在每次对话时全量进入上下文窗口。系统会根据你的提问做相关性检索，只把相关片段拉进来。
这意味着三件事：
- 文件命名极其重要 ——
payment-reconciliation-design-v3.md远好过文档3.md。检索时文件名是重要信号。 - 单个文件内部要有清晰的标题结构 —— 便于切分与定位。
- 无关文件会稀释检索质量 —— 传 50 个文件里有 40 个过时，命中率必然下降。
3.2 什么该放，什么不该放
| ✅ 适合放进知识库 | ❌ 不适合 |
|---|---|
| 架构设计文档、ADR | 完整的源代码仓库（用 Claude Code） |
| API 规范、数据字典 | 每天变化的日志、监控数据 |
| 领域知识、业务规则 | 含密钥、Token、生产数据库连接串的配置 |
| 团队编码规范 | 超大的二进制文件 |
| 历史决策记录与其理由 | 与本项目无关的通用技术文章 |
| 关键的会议纪要摘要 | 未脱敏的客户 PII 数据 |
⚠️ 安全提醒：上传前做一次密钥扫描。一个简单的本地检查：
bashgrep -rIn -E "(api[_-]?key|secret|password|token|BEGIN (RSA|OPENSSH) PRIVATE KEY)" ./docs-to-upload/
四、知识库的组织范式
4.1 推荐：一份「索引文件」+ 若干主题文件
在知识库里放一个 00-INDEX.md：
markdown
# 项目知识库索引
## 架构类
- `arch-overview.md` —— 系统全局架构与模块边界
- `arch-payment-flow.md` —— 支付主流程时序
- `arch-reconciliation.md` —— 对账模块现状（问题最集中的地方）
## 规范类
- `spec-api-conventions.md` —— REST API 命名与错误码规范
- `spec-coding-style.md` —— Java 编码规范
## 决策类
- `adr-001-why-kafka.md` —— 为什么选 Kafka 而不是 RabbitMQ
- `adr-002-bigdecimal.md` —— 金额精度处理决策
## 已废弃（勿参考）
- 无然后在 [Custom Instructions] (自定义指令) 里加一句：
text
知识库中的 00-INDEX.md 是全部资料的索引，回答前先确认相关文件。这一招显著提升检索命中率 —— 它把「模糊语义检索」变成了「先查目录再定位」。
4.2 反模式：把所有东西倒进去
症状：上传了 80 个文件后，Claude 开始给出前后矛盾的答案，或者引用了三个版本前的设计。
根因：新旧文档并存，检索时命中了旧版本。
修复：
- 建立
已废弃分区，或直接删除旧文件（保留在别处） - 在每个文件顶部标注
> 状态：现行 / 已废弃（被 xxx.md 取代） · 更新日期：2026-06-15
五、Project vs 其他持久化方案
| 方案 | 持久化什么 | 适合 |
|---|---|---|
[Projects] (项目) 知识库 | 参考资料 | 网页端，非代码型知识 |
[Custom Instructions] (自定义指令) | 行为规则 | 网页端，每次都要遵守的规则 |
CLAUDE.md | 项目事实与规范 | Claude Code，代码仓库 |
Skill | 可复用流程 | Claude Code / CoWork，多步操作 |
| MCP Server | 实时数据接入 | 需要查询活数据（数据库、工单系统） |
关键判断：知识库适合静态、低频变化的内容。如果资料每天都变，你需要的是 MCP 连接器，不是知识库。见 07.1 MCP 协议原理。
六、一个完整的 Project 搭建流程
以「接手一个陌生业务系统」为例：
第 1 步：建 Project，先只写最小指令
text
<role>你是本项目的技术顾问。</role>
<rules>
- 知识库未涵盖的内容，明确说明「知识库未涵盖」，不要推测
- 引用时注明来源文件名
</rules>第 2 步：上传 3-5 份核心文档（不要一次传满）
第 3 步：用一轮对话验证检索质量
text
不要回答任何业务问题。先做一件事：
列出你在知识库中实际能检索到的所有文件名，以及每份文件的一句话摘要。
如果某个文件你无法定位内容，也明确指出。这一步能立刻暴露「文件传上去了但检索不到」的问题。
第 4 步：根据检索结果补充 00-INDEX.md，完善 [Custom Instructions] (自定义指令)
第 5 步：再逐步补充剩余资料，每次补充后重复第 3 步验证。
延伸阅读
- 01.4 Artifacts 工件深度用法
- 04.3 幻觉的成因与锁死方案 —— "知识库未涵盖"这类约束为什么有效
- 05.6 CLAUDE.md 项目记忆 —— Claude Code 侧的对应机制