用 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 能够在需要时检索、更新和复用你的会议记录、想法、踩坑经验、偏好与项目背景。

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

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

2. 适合谁

适合以下人群：

暂时不适合：

3. 最小可行架构

推荐从本地纯文本开始。

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

为什么用文本文件：

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

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

在本地创建一个目录：

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

新建一个入口说明文件：

# 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（若文件不存在，手动新建即可）：

# Personal Knowledge Base

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

使用规则：

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

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

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

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

优先保存：

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

可以用这个判断句：

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

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

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

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

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

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

内容：
<这里粘贴内容>

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

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

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

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

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

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

模板：

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

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

## 背景

这次会议为什么召开？

## 关键讨论

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

## 决策

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

## 待办

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

## 可复用知识

哪些内容未来还能复用？

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

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

文件名建议：

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

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

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

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

# Agent 经验：<简短标题>

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

## 发生了什么

AI 做错了什么？

## 根因

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

## 下次规避规则

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

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

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

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

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

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

复盘提示词：

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

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

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

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

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

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

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

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

先创建所需目录：

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

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

#!/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"

添加执行权限：

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

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

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

添加 cron：

crontab -e

加入：

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

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

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

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

每周检查提示词：

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

范围：~/knowledge-base/

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

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

确认后再让 Claude Code 修改。

建议频率：

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

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

示例：

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

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

任务：
<你的任务>

如果是代码任务：

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

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

14. 安全边界

最低安全规则：

推荐给知识库启用 Git：

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 .）：

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

15. 验收清单

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

16. 一周落地计划

Day 1：建目录和全局说明

Day 2：导入 3 条真实材料

Day 3：验证检索

让 Claude Code 回答：

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

Day 4：建立写入流程

Day 5：建立每日复盘入口

Day 6：建立漂移检查

Day 7：复盘并收敛规则

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、向量库、自动同步或团队权限。