1. 为什么要把 Codex 和 Obsidian 拼在一起用
1.1 一个真实痛点：AI 每次都在“从零开始”
我用了大半年 AI 编程助手，最大的感受不是它不够聪明，而是它太“健忘”。每次开一个新会话，它就像刚入职的实习生，你得重新交代项目背景、代码规范、目录结构、命名习惯，甚至连“这个仓库里utils目录是公共函数、legacy目录别动”这种常识都要重复讲一遍。讲完一轮，它终于进入状态了，会话也快结束了。下一次，再来一遍。
这个问题的本质是：AI 的上下文窗口是临时的，而你的项目积累是长期的。你脑子里、笔记里、仓库里沉淀下来的那些约定、踩坑记录、架构决策，AI 一概不知道。它只能看到你这次粘贴进去的东西。
Codex 这类命令行 AI 编程工具，本身是支持读取项目内配置文件的（比如AGENTS.md这种约定文件），但它的“记忆”范围通常局限在单个代码仓库。而真正有价值的个人积累，往往散落在你的笔记系统里——需求分析、技术选型对比、历史踩坑、常用片段、领域知识。这些内容如果能让 AI 直接读到，它给出的建议质量会完全不一样。
1.2 组合思路：Obsidian 当“长期记忆”，Codex 当“执行大脑”
Obsidian 是一个基于本地 Markdown 文件的知识库工具，所有笔记都是纯文本，存在你自己的文件夹里。这一点非常关键：纯文本意味着任何程序都能读。你不需要导出、不需要 API、不需要联网，AI 工具直接读文件就行。
所以我的方案是这样的：
- Obsidian 负责沉淀：把项目规范、技术决策、踩坑记录、常用代码片段、领域术语表，全部写成 Markdown 笔记，用标签和双链组织起来。
- Codex 负责调用：通过项目根目录的
AGENTS.md和知识库入口文件index.md，把 Obsidian 里的关键内容“喂”给 AI，让它在干活之前先读一遍你的积累。 - 两者之间的桥梁：一个约定好的目录结构 + 一份索引文件 + 一套标签规范。
这套东西搭好之后，效果是肉眼可见的：AI 生成的代码开始符合你的命名习惯，开始避开你记录过的那些坑，开始用你项目里已有的工具函数而不是重新造轮子。它不再是“通用助手”，而是“了解你项目的助手”。
1.3 适合谁参考这套方案
这套方案不是给所有人准备的，我先说清楚适用边界，免得你搭到一半发现用不上。
适合的人群：有长期维护的个人项目或小团队项目；已经在用 Obsidian 或类似 Markdown 笔记工具；愿意花一两个小时做一次性的结构整理；日常用命令行工具干活，不排斥终端操作。
不太适合的情况：项目生命周期只有几天、做完就扔；完全不用笔记、所有知识都在脑子里；对命令行有强烈抵触。这几种情况下，投入产出比不高，直接用 AI 的默认能力就行。
下面我按“整体设计 → 核心细节 → 实操落地 → 问题排查”的顺序，把这套方案完整拆一遍。中间会穿插我自己踩过的坑和参数选择理由，你可以直接抄，也可以按自己习惯改。
2. 整体架构设计与关键选型理由
2.1 目录结构：为什么知识库要分“三层”
很多人一上来就把所有笔记堆在一个文件夹里，几十上百个文件平铺，找起来靠搜索。自己用还行，但要让 AI 读，就必须有结构，因为 AI 需要知道“先读什么、再读什么”。
我最终定下来的结构是三层：
knowledge-base/ ├── index.md # 总入口，AI 第一个读的文件 ├── 00-rules/ # 规则层：编码规范、命名约定、禁忌 │ ├── coding-style.md │ ├── naming.md │ └── forbidden.md ├── 10-context/ # 上下文层：项目背景、架构决策 │ ├── architecture.md │ ├── tech-stack.md │ └── decisions.md └── 20-snippets/ # 片段层：可复用代码、命令、配置 ├── python-utils.md ├── shell-commands.md └── config-templates.md为什么这么分？因为 AI 读取是有成本（token）的，你不可能每次都把整个知识库塞进去。分层之后，可以按需读取：写代码时重点读00-rules和20-snippets，做架构讨论时重点读10-context。
index.md的作用是“目录的目录”，它不存具体内容，只存“哪个文件讲什么、什么时候该读”。这样 AI 先读index.md，就能自己判断该深入哪个文件。
2.2 为什么用 AGENTS.md 而不是别的文件名
Codex 这类工具读取项目约定文件时，AGENTS.md是一个被广泛支持的约定名。它的位置通常在项目根目录，内容用自然语言写，AI 会把它当作“系统提示”的一部分。
我试过几种方案：把约定写在代码注释里、写在 README 里、写在单独的 config 文件里。实测下来，AGENTS.md的效果最好，原因是：
- 它是纯自然语言，不需要特定格式，写起来没负担。
- 它被工具优先读取，优先级高于普通文件。
- 它不污染代码，不会出现在你的源码目录里。
AGENTS.md里我一般写三部分：项目一句话简介、知识库位置指引、当前任务的重点提醒。注意，这里不要写太长，控制在 50 行以内，否则会挤占上下文。
2.3 标签体系：让 AI 能“按标签取内容”
Obsidian 的标签（#tag）是这套方案里最容易被忽略、但价值很高的部分。原因是：标签可以让你在index.md里用一句话描述“所有带#rule标签的笔记都是硬性规范”，AI 就能理解标签的语义。
我的标签体系很简单，只有四类：
| 标签 | 含义 | AI 使用场景 |
|---|---|---|
#rule | 硬性规范，必须遵守 | 生成代码前必读 |
#context | 背景信息，帮助理解 | 讨论方案时参考 |
#snippet | 可复用片段 | 需要现成代码时调用 |
#pitfall | 踩坑记录 | 避免重复犯错 |
标签不要多，多了就失去意义。四类足够覆盖绝大多数场景。关键是每个标签的语义要稳定，不能今天#rule是规范、明天变成“随便看看”。
2.4 数据流：一次完整的“AI 读知识库”过程
把上面几块拼起来，一次完整的调用流程是这样的：
- 你在项目目录里启动 Codex。
- Codex 读取根目录的
AGENTS.md，知道“这个项目有一个知识库，入口在../knowledge-base/index.md”。 - 你提出任务，比如“帮我写一个解析配置文件的函数”。
- Codex 根据
AGENTS.md的指引，去读index.md，发现00-rules/coding-style.md和20-snippets/python-utils.md相关。 - Codex 读取这两个文件，了解到你的命名习惯和已有的工具函数。
- Codex 生成代码，风格和你的项目一致，并且复用了已有函数。
整个过程你只说了一句话，但 AI 已经“读过”你的积累。这就是这套方案的核心价值。
3. 核心细节解析与实操要点
3.1 index.md 怎么写才让 AI 读得懂
index.md是整套方案的枢纽，写得好不好直接决定效果。我的写法是“表格 + 一句话说明”，不写废话。
# 知识库索引 ## 规则层（生成代码前必读） | 文件 | 内容 | 何时读 | |------|------|--------| | 00-rules/coding-style.md | Python/JS 编码风格 | 写任何代码前 | | 00-rules/naming.md | 变量、函数、文件命名 | 命名新东西时 | | 00-rules/forbidden.md | 禁止使用的库和写法 | 选型时 | ## 上下文层（讨论方案时读） | 文件 | 内容 | 何时读 | |------|------|--------| | 10-context/architecture.md | 整体架构与模块划分 | 涉及跨模块改动 | | 10-context/tech-stack.md | 技术栈与版本 | 引入新依赖时 | ## 片段层（需要现成代码时读） | 文件 | 内容 | 何时读 | |------|------|--------| | 20-snippets/python-utils.md | 常用 Python 工具函数 | 写 Python 时 | | 20-snippets/shell-commands.md | 常用命令 | 写脚本时 |注意几个细节：“何时读”这一列非常重要，它告诉 AI 判断条件，而不是让它无脑全读。表格比列表好，因为 AI 对表格的结构化信息解析更准。文件路径用相对路径，避免绝对路径带来的迁移问题。
提示：
index.md本身不要超过 60 行。它是索引，不是内容。内容多了 AI 反而不愿意深入读具体文件。
3.2 AGENTS.md 的写法与常见误区
AGENTS.md放在代码项目根目录，内容要短、要准。我的模板：
# 项目约定 本项目是一个 XXX 工具，主要用 Python 编写。 ## 知识库 个人知识库位于 `../knowledge-base/`，入口是 `index.md`。 在生成代码前，请先读取 `index.md`，按其中的指引读取相关规则文件。 ## 当前重点 - 正在重构数据层，新代码请放在 `src/data/` 下 - 暂时不要改动 `legacy/` 目录 ## 硬性要求 - 所有新函数必须有类型注解 - 禁止引入新的第三方依赖，除非我明确同意常见误区有三个。第一个是写太长，有人把整个 README 复制进来，结果 AI 读了一半就“忘了”后面的。第二个是写太虚，比如“请写出高质量代码”，这种话对 AI 没有任何指导意义。第三个是路径写错，AGENTS.md里的相对路径是相对于项目根目录的，不是相对于AGENTS.md本身，这点容易搞混。
3.3 规则文件的颗粒度控制
00-rules/下的文件，颗粒度要控制好。太粗（一个文件写所有规范）AI 读起来抓不住重点；太细（每个小规则一个文件）文件太多，索引成本高。
我的经验是：按“决策类型”分文件，而不是按“语言”或“模块”分。比如：
coding-style.md：缩进、引号、行宽、注释风格naming.md：变量、函数、类、文件、常量的命名规则forbidden.md：禁止的库、禁止的写法、禁止的模式
每个文件控制在 100 行以内，用“规则 + 正例 + 反例”的格式写。正反例特别重要，因为 AI 对例子的理解比对抽象规则的理解更准。
## 函数命名 规则：动词开头，小写下划线分隔。 正例：`parse_config`、`load_user_data` 反例：`configParser`、`LoadUserData`、`data1`3.4 片段库的维护节奏
20-snippets/是最容易变成“垃圾堆”的地方。我的做法是：只收录被复用两次以上的片段。用一次就写的代码，不值得进片段库。
每个片段用固定格式：
### 读取 YAML 配置 标签：#snippet 用途：安全读取 YAML，带默认值和错误处理 代码： ```python import yaml from pathlib import Path def load_yaml(path: str, default: dict | None = None) -> dict: p = Path(path) if not p.exists(): return default or {} with p.open("r", encoding="utf-8") as f: return yaml.safe_load(f) or (default or {})这样 AI 读到之后，会直接复用这个函数，而不是重新写一个 `yaml.load(open(...))`。维护节奏上，我一般每周花十分钟整理一次，把本周重复写过的代码提炼进去。 ## 4. 完整实操流程与关键环节 ### 4.1 环境准备：Obsidian 与 Codex 的安装要点 Obsidian 的安装没什么好说的，官网下载对应平台版本即可。关键是**库的位置**：建议把知识库放在一个固定的、路径不含中文和空格的目录下，比如 `~/knowledge-base/`。原因是命令行工具处理含空格路径时容易出问题，虽然可以加引号解决，但能避免就避免。 Codex 的安装，Windows 用户建议用官方安装包，安装完成后确认命令行能调用。安装后第一次运行需要登录，按提示操作即可。如果遇到登录相关的问题，先检查网络环境是否正常，再确认账号状态。 安装完成后，做一个最小验证：在任意目录下运行一次，确认能正常启动、能读取当前目录的文件。这一步很重要，因为后面所有操作都依赖它能读文件。 ### 4.2 知识库初始化：从零搭出三层结构 第一步，在 Obsidian 里新建库，或者在你已有的库里新建一个文件夹作为知识库根目录。我建议**单独建一个库**，而不是混在现有笔记里，原因是隔离性好，AI 读取时不会误读无关内容。 第二步，按第 2.1 节的结构建目录。Obsidian 里建文件夹很简单，右键新建即可。建完后应该是 `00-rules`、`10-context`、`20-snippets` 三个文件夹加一个 `index.md`。 第三步，填充 `index.md`。先按 3.1 节的模板写，文件可以先空着，但索引先建好。这样后面往里填内容时，索引不用反复改。 第四步，给每个文件打标签。Obsidian 里在文件顶部写 `#rule`、`#context` 这类标签即可。标签写在正文第一行，AI 读取时能直接看到。 ### 4.3 把知识库接入 Codex：AGENTS.md 的落地 在你的代码项目根目录新建 `AGENTS.md`，按 3.2 节的模板写。关键是**路径要写对**。假设你的项目在 `~/projects/my-tool/`，知识库在 `~/knowledge-base/`，那么 `AGENTS.md` 里的路径应该写成 `../knowledge-base/index.md`。 写完后做一次验证：在项目目录启动 Codex，问它“你知道我的知识库在哪吗”。如果它能正确说出路径和入口文件，说明接入成功。如果它说不知道，检查 `AGENTS.md` 是否在项目根目录、路径是否正确。 > 注意：不同工具对 `AGENTS.md` 的支持程度不一样。如果发现 AI 没有主动读取，可以在对话开头手动提示一句“请先读 AGENTS.md 和知识库索引”，一般就能触发。 ### 4.4 一次完整的实战：让 AI 按你的规范写代码 假设我要写一个“读取配置文件并返回字典”的函数。没有知识库时，AI 可能生成： ```python def read_config(path): import json with open(path) as f: return json.load(f)有了知识库之后，AI 读到我的coding-style.md（要求类型注解）、naming.md（要求动词开头）、python-utils.md（已有load_yaml函数），生成的代码变成：
from pathlib import Path import yaml def load_config(path: str, default: dict | None = None) -> dict: """读取 YAML 配置，文件不存在时返回默认值。""" p = Path(path) if not p.exists(): return default or {} with p.open("r", encoding="utf-8") as f: return yaml.safe_load(f) or (default or {})差别很明显：有类型注解、命名规范、复用了已有模式、带了错误处理。这就是知识库带来的实际收益。
4.5 参数与配置的选择依据
这套方案里没有太多“参数”需要调，但有几个选择点值得说明理由。
知识库文件数量：我建议控制在 20 个文件以内。超过之后，index.md会变长，AI 读取成本上升。如果内容确实多，就拆成多个知识库，按项目或领域分开。
单个文件长度：控制在 100 行以内。超过之后，AI 容易“读了后面忘前面”。长内容拆成多个文件，用索引串起来。
标签数量：四类足够。标签多了之后，AI 需要额外理解标签语义，反而增加负担。
AGENTS.md 长度：50 行以内。它是“开场白”，不是“说明书”。
这些数字不是硬性规定，是我实测下来比较舒服的区间。你可以根据自己项目复杂度调整，但方向是“宁少勿多”。
5. 常见问题与排查技巧实录
5.1 AI 不读知识库怎么办
这是最常见的问题。排查顺序如下：
先确认AGENTS.md在项目根目录，且文件名大小写正确（有些系统区分大小写）。再确认里面的路径是相对路径且指向正确。然后确认知识库文件确实存在、不是空文件。
如果都正常但 AI 还是不读，就在对话开头手动加一句提示：“请先读取 AGENTS.md，然后按其中的指引读取知识库索引。”实测这一句能解决 90% 的情况。
还有一种可能是工具版本不支持自动读取AGENTS.md。这种情况下，把AGENTS.md的内容直接粘贴到对话开头，效果一样，只是每次要手动操作。
5.2 知识库内容太多导致 AI “抓不住重点”
症状是：AI 读了知识库，但生成的代码还是不符合规范，或者只遵守了一部分。原因通常是知识库太杂，重点不突出。
解决办法是分层读取。不要让 AI 一次读所有文件，而是在index.md里明确“什么任务读什么文件”。比如写代码只读00-rules和20-snippets，讨论架构才读10-context。这样每次读取的内容少而精，AI 的注意力集中。
另一个技巧是把最重要的规则放在文件最前面。AI 读取时对开头内容的记忆更牢。
5.3 标签和双链用不好反而添乱
Obsidian 的双链（[[文件名]]）很好用，但在喂给 AI 时要注意：AI 不一定能解析双链。我的做法是双链只用于人看，AI 读的内容用纯文本路径。
标签同理。标签是给人分类用的，AI 读的是标签的“语义约定”，而不是标签本身。所以index.md里要写清楚“带#rule标签的文件是硬性规范”，AI 才能理解。
如果发现标签体系混乱，就砍掉重来。四类标签，每个文件只打一个主标签，不要一个文件打五六个标签。
5.4 常见问题速查表
| 问题现象 | 可能原因 | 排查方法 |
|---|---|---|
| AI 完全不知道知识库 | AGENTS.md 缺失或路径错 | 检查文件位置和路径写法 |
| AI 读了但不用 | 规则文件太抽象 | 补充正例反例 |
| AI 只遵守部分规则 | 知识库太杂 | 分层读取，精简索引 |
| 生成代码风格不一致 | 规则文件冲突 | 检查是否有矛盾规则 |
| 每次都要手动提示 | 工具不支持自动读取 | 手动粘贴或换工具版本 |
| 知识库越用越乱 | 缺乏维护节奏 | 每周整理一次，只留复用片段 |
5.5 我踩过的几个坑
第一个坑是路径用绝对路径。一开始我图省事，AGENTS.md里写了/Users/xxx/knowledge-base/index.md，结果换台机器就失效了。后来全部改成相对路径，问题解决。
第二个坑是规则写得太理想化。我一开始写“代码要优雅、要可读”，AI 完全不知道该怎么执行。后来改成具体规则，比如“函数不超过 30 行”“变量名不超过 20 字符”，效果立刻不一样。
第三个坑是片段库不更新。有段时间我忙着写业务，片段库三个月没动，结果 AI 复用的还是老写法，而项目里已经换了新工具函数。后来定了每周整理的习惯，才没再出问题。
第四个坑是一次读太多。我试过让 AI 一次读整个知识库，结果它生成的代码反而更差，因为注意力被分散了。后来改成按需读取，质量明显提升。
这套方案的核心其实不是工具，而是你有没有把积累写下来。工具只是让这些积累能被 AI 读到。如果你平时不记笔记，那再好的方案也搭不起来。反过来，如果你已经有笔记习惯，这套东西一两个小时就能搭好，之后每次用 AI 都能省下大量重复交代的时间。我自己用下来，最直观的感受是：AI 从“每次都要重新教”变成了“开口就懂”，这个体验的提升是值得花时间搭一次的。
