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、data13.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, encodingutf-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 把知识库接入 CodexAGENTS.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, encodingutf-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 从“每次都要重新教”变成了“开口就懂”这个体验的提升是值得花时间搭一次的。