# 用 Claude Code 搭建可执行的个人知识库：从文件夹到自动复盘闭环

来源文章：How to Build a Claude Code-Powered Knowledge Base  
来源 URL：https://towardsdatascience.com/how-to-build-a-claude-code-powered-knowledge-base/  
整理方式：基于 Gemini 摘要与浏览器正文抽取结果改写为可落地教程；下文“实践扩展”是面向个人/团队落地的操作化改写，不等同于原文逐字内容。

## 1. 一句话目标

用一个普通文本文件夹作为个人知识库，让 Claude Code 能够在需要时检索、更新和复用你的会议记录、想法、踩坑经验、偏好与项目背景。

最终不是做一个复杂系统，而是形成一个闭环：

```text
记录输入 → 分类存放 → 使用时检索 → 定期复盘 → 清理过时信息
```

## 2. 适合谁

适合以下人群：

- 经常使用 Claude Code / AI Agent 做代码、文档、计划或研究的人；
- 有大量会议、笔记、项目上下文，但经常找不到历史信息的人；
- 想让 AI 不再每次都“从零认识你”的个人或小团队；
- 希望先用低成本方案验证知识库价值，而不是一开始上复杂知识管理系统的人。

暂时不适合：

- 没有稳定文本资料来源的人；
- 需要强权限隔离、审计合规、企业级知识治理的生产环境；
- 期望 AI 自动长期维护一切但不愿做人工确认的人。

## 3. 最小可行架构

推荐从本地纯文本开始。

```text
~/knowledge-base/
├── inbox/                 # 临时入口，未分类材料
├── meetings/              # 会议记录与纪要
├── projects/              # 项目背景、决策、复盘
├── preferences/           # 个人偏好、工作习惯
├── agent-lessons/         # AI Agent 犯错与规避方式
├── workflows/             # 可复用流程、SOP、检查清单
└── archive/               # 过时但仍需保留的材料
```

为什么用文本文件：

- Claude Code 容易读取和搜索；
- Git、备份、diff、审查都简单；
- 迁移成本低；
- 不依赖某个笔记软件的私有格式。

如果你已经重度使用 Notion、Obsidian 或企业文档系统，也可以继续用它们；核心不是工具，而是“AI 能读到、能引用、能更新”。

## 4. 第一步：建立知识库目录

在本地创建一个目录：

```bash
mkdir -p ~/knowledge-base/{inbox,meetings,projects,preferences,agent-lessons,workflows,archive}
```

新建一个入口说明文件：

```markdown
# Knowledge Base Index

本知识库用于保存个人和项目上下文，供我和 Claude Code 检索使用。

## 目录规则

- inbox/：临时材料，等待整理
- meetings/：会议记录，文件名包含日期和主题
- projects/：项目背景、决策和阶段复盘
- preferences/：长期稳定偏好
- agent-lessons/：AI Agent 犯错记录和规避办法
- workflows/：可复用操作流程
- archive/：过时或低频材料

## 使用原则

1. 新材料先进入 inbox，除非分类非常明确。
2. 只有稳定、可复用的信息才进入 preferences 或 workflows。
3. 临时进展不写成长期规则。
4. 任何自动写入都需要可审计、可回滚。
```

## 5. 第二步：让 Claude Code 知道知识库在哪里

关键点：不要只在某个项目的 `CLAUDE.md` 里写知识库路径。项目级说明只在该项目目录下生效，换目录后 Claude Code 可能不知道知识库存在。

推荐在用户级配置里写一段全局规则。Claude Code 的用户级说明文件位于 `~/.claude/CLAUDE.md`（若文件不存在，手动新建即可）：

```markdown
# Personal Knowledge Base

我的个人知识库位于：`~/knowledge-base/`。

使用规则：

1. 当任务需要历史背景、偏好、项目决策或过去踩坑经验时，先搜索知识库。
2. 不要把临时任务进展写入长期知识库。
3. 新增知识前先判断应放在哪一层：
   - 偏好：preferences/
   - 流程：workflows/
   - 项目背景：projects/
   - Agent 经验：agent-lessons/
   - 未分类：inbox/
4. 写入前说明来源、日期和适用范围。
5. 不确定是否应长期保存时，先写入 inbox/，不要直接写成规则。
```

这一步的目标是让 Claude Code 在任意工作目录都知道：有一个外部知识库可以查。

## 6. 第三步：定义“应该保存什么”

原文建议尽量多保存上下文，但实际落地时建议分层，避免知识库变成垃圾堆。

优先保存：

- 会议结论：谁、何时、讨论了什么、决定了什么；
- 项目决策：为什么选 A 不选 B；
- 可复用流程：下次还能照着做的步骤；
- Agent 失败案例：AI 犯了什么错、如何避免；
- 长期偏好：稳定存在、未来会反复影响工作的偏好；
- 重要上下文：项目边界、目录结构、运行命令、验证方式。

不建议直接保存为长期知识：

- 一次性任务进展；
- 可能一周内过期的状态；
- 未验证的猜测；
- 敏感凭据、Token、Cookie、私钥；
- 只对当前对话有用的中间草稿。

可以用这个判断句：

> 这条信息一周后、一个月后再次出现时，是否仍能减少我重复解释的成本？

如果答案是否定的，先不要写入长期区。

## 7. 第四步：建立手动写入入口

先不要急着全自动。第一阶段只需要一个稳定的人工触发指令。

**推荐用法（先确认，再写入）**：

```text
请判断下面内容是否值得进入我的长期知识库。
如果值得，请给出：
1. 推荐目录
2. 推荐文件名
3. 建议写入内容
4. 为什么不是临时信息
先不要写文件，等我确认。

内容：
<这里粘贴内容>
```

跑通几次、对分类结果满意后，再切换到下面的直接写入版本：

**较激进（流程稳定后再用）**：

```text
把下面内容加入我的知识库。请先判断它属于偏好、流程、项目背景、Agent 经验还是临时 inbox；然后写入合适文件，并在末尾注明来源和日期。

内容：
<这里粘贴要保存的知识>
```

## 8. 第五步：建立会议记录模板

会议是最适合进入知识库的材料之一，因为它通常包含决策、背景和责任人。

模板：

```markdown
# 会议记录：<会议主题>

日期：YYYY-MM-DD  
参会人：A、B、C  
来源：手动记录 / 会议转写 / 日历同步  
项目：<项目名或无>

## 背景

这次会议为什么召开？

## 关键讨论

- 讨论点 1：...
- 讨论点 2：...

## 决策

- 决策 1：...
- 决策 2：...

## 待办

- [ ] 负责人：事项，截止时间

## 可复用知识

哪些内容未来还能复用？

## 后续需要写入的长期知识

- preferences/：...
- workflows/：...
- projects/：...
```

文件名建议：

```text
meetings/2026-05-16-project-name-topic.md
```

## 9. 第六步：记录 Agent 犯错经验

这是原文中特别有价值的一点：记录 AI Agent 的错误和规避方法。

文件模板（`agent-lessons/YYYY-MM-DD-topic.md`）：

```markdown
# Agent 经验：<简短标题>

日期：YYYY-MM-DD  
任务类型：代码 / 文档 / 运维 / 研究 / 其他  
适用范围：个人 / 某项目 / 通用

## 发生了什么

AI 做错了什么？

## 根因

- 缺少上下文？
- 没有先读取文件？
- 没有验证？
- 把临时信息当成长期规则？
- 调用了不该调用的工具？

## 下次规避规则

- 应该先做什么？
- 哪些操作必须确认？
- 如何验证完成？
```

在文件底部或对应任务的提示词里，附上规避指令（直接粘贴给 Claude Code 用）：

```text
以后处理类似任务时，请先读取 <路径>，再执行 <验证命令>。如果验证失败，不要继续扩大修改范围。
```

这类内容比普通笔记更有复利，因为它能直接减少未来 AI 反复犯同类错误。

## 10. 第七步：建立每日轻量复盘

每日复盘不要一开始就全自动写入。推荐先生成候选，再人工确认。

复盘提示词：

```text
请复盘我今天的 AI/工作交互记录，提取可能值得进入知识库的内容。

只输出候选，不要写文件。

分类：
1. 长期偏好
2. 可复用流程
3. 项目背景
4. Agent 失败经验
5. 不建议保存的临时信息

每条候选请说明：
- 来源
- 为什么值得保存
- 推荐目录
- 建议写入文本
```

如果你有本地日志，可以先让脚本把当天日志拼成一个输入文件，再交给 Claude Code 分析。

## 11. 第八步：用 cron 做自动提醒，而不是自动放权

原文提到用 cron job 自动复盘。落地时建议先做“提醒 + 生成候选”，不要直接自动改知识库。

示例：每天晚上生成提醒文件。

先创建所需目录：

```bash
mkdir -p ~/knowledge-base/inbox/daily-review
mkdir -p ~/knowledge-base/scripts
```

创建脚本 `~/knowledge-base/scripts/daily-review-reminder.sh`：

```bash
#!/usr/bin/env bash
set -euo pipefail

TODAY="$(date +%F)"
OUT="$HOME/knowledge-base/inbox/daily-review/$TODAY.md"

mkdir -p "$(dirname "$OUT")"

# 如果当天文件已存在则跳过，避免意外覆盖
if [ -f "$OUT" ]; then
  echo "今天的复盘文件已存在：$OUT"
  exit 0
fi

cat > "$OUT" <<EOF
# Daily Knowledge Review - $TODAY

请把今天值得沉淀的内容贴到这里，然后让 Claude Code 按以下分类整理候选：

1. 长期偏好
2. 可复用流程
3. 项目背景
4. Agent 失败经验
5. 不建议保存的临时信息

注意：先生成候选，不要自动写入长期目录。
EOF

echo "已创建复盘文件：$OUT"
```

添加执行权限：

```bash
chmod +x ~/knowledge-base/scripts/daily-review-reminder.sh
```

手动跑一次确认脚本正常工作：

```bash
~/knowledge-base/scripts/daily-review-reminder.sh
```

添加 cron：

```bash
crontab -e
```

加入：

```cron
0 21 * * * $HOME/knowledge-base/scripts/daily-review-reminder.sh
```

这会每天 21:00 创建一个复盘入口文件。

## 12. 第九步：每周处理知识漂移

知识库会过时。你需要定期检查：哪些偏好、流程、项目背景已经变了。

每周检查提示词：

```text
请检查我的知识库是否存在可能过时、冲突或重复的信息。

范围：~/knowledge-base/

请只做审查，不要直接修改文件。

输出：
1. 可能过时的信息
2. 相互冲突的信息
3. 重复或可合并的信息
4. 建议归档的信息
5. 建议修改的文件和修改理由
```

确认后再让 Claude Code 修改。

建议频率：

- 个人知识库：每周一次；
- 高频项目：每个里程碑后一次；
- 团队共享知识库：每次重要决策后人工确认。

## 13. 第十步：让 Claude Code 使用知识库完成任务

使用知识库时，不要只说“帮我做这个”。要明确要求它先检索。

示例：

```text
请先搜索我的知识库 `~/knowledge-base/`，找到与这个任务相关的偏好、项目背景、过去踩坑和可复用流程。

然后基于这些上下文给出执行方案。

任务：
<你的任务>
```

如果是代码任务：

```text
在修改代码前，请先搜索 `~/knowledge-base/projects/` 和 `~/knowledge-base/agent-lessons/`，找出这个项目相关的约束、历史决策和过去失败案例。

只读取和本任务相关的内容，不要扩大范围。
```

## 14. 安全边界

最低安全规则：

- 不保存密钥、Token、Cookie、私钥；
- 不让 AI 无确认地删除或覆盖知识库内容；
- 自动化任务先生成候选，不直接改长期知识；
- 每条长期知识都要有来源和日期；
- 重要流程修改前先备份或使用 Git；
- 涉及公司、客户、个人隐私的信息要脱敏或放入受控系统。

推荐给知识库启用 Git：

```bash
cd ~/knowledge-base

# 先建 .gitignore，防止意外提交敏感文件
cat > .gitignore <<'EOF'
# 敏感文件
*.env
*.key
*.pem
*.token
secrets/
private/
EOF

git init
git add .gitignore
git add -p  # 逐块确认，确保只提交预期内容
git commit -m "init knowledge base"
```

之后每次重要修改后提交（同样建议用 `git add -p` 而非 `git add .`）：

```bash
git add -p
git commit -m "docs: update knowledge base"
```

## 15. 验收清单

完成以下检查，才算第一版知识库落地：

- [ ] 已创建知识库目录；
- [ ] 已有入口说明文件；
- [ ] Claude Code 的用户级说明中写明知识库路径；
- [ ] 至少有 3 条真实材料进入知识库；
- [ ] 至少有 1 条 Agent 失败经验；
- [ ] 已建立每日复盘入口或提醒；
- [ ] 已建立每周知识漂移检查提示词；
- [ ] 已配置 Git 或其他备份机制；
- [ ] Claude Code 能在一个新目录下主动找到并使用知识库。

## 16. 一周落地计划

### Day 1：建目录和全局说明

- 创建 `~/knowledge-base/`；
- 写 `Knowledge Base Index`；
- 在用户级 Claude Code 说明中加入知识库路径和使用规则。

### Day 2：导入 3 条真实材料

- 一条会议记录（参考第 8 节模板）；
- 一条项目背景（格式示例：`projects/项目名.md`，写明目录结构、关键命令、约束和已知坑）；
- 一条 Agent 犯错经验（参考第 9 节模板）。

### Day 3：验证检索

让 Claude Code 回答：

```text
请搜索我的知识库，告诉我最近有哪些项目决策、偏好和 Agent 失败经验可能影响今天的工作。
```

### Day 4：建立写入流程

- 固定“候选 → 人工确认 → 写入”的提示词；
- 不急着自动化。

### Day 5：建立每日复盘入口

- 创建 daily review 模板；
- 配置 cron 或日历提醒。

### Day 6：建立漂移检查

- 跑一次只读检查；
- 找出过时、重复、冲突内容。

### Day 7：复盘并收敛规则

- 哪些材料真的有用？
- 哪些目录太细或太粗？
- 哪些写入应该更保守？
- 是否允许 Claude Code 在确认后直接修改？

## 17. 常见坑

### 坑 1：一开始就设计复杂系统

先用文件夹和 Markdown。只有当检索、权限、多人协作成为真实瓶颈时，再考虑数据库、向量库或知识平台。

### 坑 2：什么都写成长期规则

长期规则太多会互相冲突。临时进展、一次性结论、未验证想法先放 inbox。

### 坑 3：只在项目级文件里告诉 Claude Code

这会导致 Claude Code 换目录后不知道知识库存在。应使用用户级说明。

### 坑 4：自动化直接改核心知识

先让自动化生成候选，人工确认后再写入。等流程稳定后，再逐步放宽权限。

### 坑 5：不处理过时信息

知识库不是只增不减。每周或每个里程碑后要检查漂移、冲突和重复。

## 18. 推荐的最小起步方案

如果只做一件事，按这个顺序：

1. 建一个 `~/knowledge-base/` 文件夹；
2. 把路径写进用户级 Claude Code 说明；
3. 保存 3 类内容：会议决策、项目背景、Agent 犯错经验；
4. 每天生成候选，每周检查过时；
5. 所有自动写入先人工确认。

这已经足够让知识库开始产生价值。后续再谈 Notion、向量库、自动同步或团队权限。